]>
Commit | Line | Data |
---|---|---|
cb636bb2 UD |
1 | /* |
2 | * Sun RPC is a product of Sun Microsystems, Inc. and is provided for | |
3 | * unrestricted use provided that this legend is included on all tape | |
4 | * media and as a part of the software program in whole or part. Users | |
5 | * may copy or modify Sun RPC without charge, but are not authorized | |
6 | * to license or distribute it to anyone else except as part of a product or | |
7 | * program developed by the user. | |
8 | * | |
9 | * SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE | |
10 | * WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR | |
11 | * PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE. | |
12 | * | |
13 | * Sun RPC is provided with no support and without any obligation on the | |
14 | * part of Sun Microsystems, Inc. to assist in its use, correction, | |
15 | * modification or enhancement. | |
16 | * | |
17 | * SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE | |
18 | * INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY SUN RPC | |
19 | * OR ANY PART THEREOF. | |
20 | * | |
21 | * In no event will Sun Microsystems, Inc. be liable for any lost revenue | |
22 | * or profits or other special, indirect and consequential damages, even if | |
23 | * Sun has been advised of the possibility of such damages. | |
24 | * | |
25 | * Sun Microsystems, Inc. | |
26 | * 2550 Garcia Avenue | |
27 | * Mountain View, California 94043 | |
28 | */ | |
29 | ||
28f540f4 RM |
30 | /* |
31 | * svc.h, Server-side remote procedure call interface. | |
32 | * | |
33 | * Copyright (C) 1984, Sun Microsystems, Inc. | |
34 | */ | |
35 | ||
5107cf1d UD |
36 | #ifndef _RPC_SVC_H |
37 | #define _RPC_SVC_H 1 | |
28f540f4 | 38 | |
e7fd8a39 UD |
39 | #include <features.h> |
40 | #include <rpc/rpc_msg.h> | |
41 | ||
fc933e28 RM |
42 | __BEGIN_DECLS |
43 | ||
28f540f4 RM |
44 | /* |
45 | * This interface must manage two items concerning remote procedure calling: | |
46 | * | |
47 | * 1) An arbitrary number of transport connections upon which rpc requests | |
48 | * are received. The two most notable transports are TCP and UDP; they are | |
49 | * created and registered by routines in svc_tcp.c and svc_udp.c, respectively; | |
50 | * they in turn call xprt_register and xprt_unregister. | |
51 | * | |
52 | * 2) An arbitrary number of locally registered services. Services are | |
53 | * described by the following four data: program number, version number, | |
54 | * "service dispatch" function, a transport handle, and a boolean that | |
55 | * indicates whether or not the exported program should be registered with a | |
56 | * local binder service; if true the program's number and version and the | |
57 | * port number from the transport handle are registered with the binder. | |
58 | * These data are registered with the rpc svc system via svc_register. | |
59 | * | |
60 | * A service's dispatch function is called whenever an rpc request comes in | |
61 | * on a transport. The request's program and version numbers must match | |
62 | * those of the registered service. The dispatch function is passed two | |
63 | * parameters, struct svc_req * and SVCXPRT *, defined below. | |
64 | */ | |
65 | ||
66 | enum xprt_stat { | |
67 | XPRT_DIED, | |
68 | XPRT_MOREREQS, | |
69 | XPRT_IDLE | |
70 | }; | |
71 | ||
72 | /* | |
73 | * Server side transport handle | |
74 | */ | |
e7fd8a39 UD |
75 | typedef struct SVCXPRT SVCXPRT; |
76 | struct SVCXPRT { | |
77 | int xp_sock; | |
78 | u_short xp_port; /* associated port number */ | |
79 | const struct xp_ops { | |
c1422e5b | 80 | bool_t (*xp_recv) (SVCXPRT *__xprt, struct rpc_msg *__msg); |
e7fd8a39 | 81 | /* receive incoming requests */ |
c1422e5b | 82 | enum xprt_stat (*xp_stat) (SVCXPRT *__xprt); |
e7fd8a39 | 83 | /* get transport status */ |
c1422e5b | 84 | bool_t (*xp_getargs) (SVCXPRT *__xprt, xdrproc_t __xdr_args, |
d82a27f8 | 85 | caddr_t __args_ptr); /* get arguments */ |
c1422e5b | 86 | bool_t (*xp_reply) (SVCXPRT *__xprt, struct rpc_msg *__msg); |
e7fd8a39 | 87 | /* send reply */ |
c1422e5b | 88 | bool_t (*xp_freeargs) (SVCXPRT *__xprt, xdrproc_t __xdr_args, |
d82a27f8 | 89 | caddr_t __args_ptr); |
e7fd8a39 | 90 | /* free mem allocated for args */ |
c1422e5b | 91 | void (*xp_destroy) (SVCXPRT *__xprt); |
e7fd8a39 UD |
92 | /* destroy this struct */ |
93 | } *xp_ops; | |
94 | int xp_addrlen; /* length of remote address */ | |
be18eced | 95 | struct sockaddr_in xp_raddr; /* remote address */ |
e7fd8a39 UD |
96 | struct opaque_auth xp_verf; /* raw response verifier */ |
97 | caddr_t xp_p1; /* private */ | |
98 | caddr_t xp_p2; /* private */ | |
ada24bb2 | 99 | char xp_pad [256]; /* padding, internal use */ |
e7fd8a39 | 100 | }; |
28f540f4 RM |
101 | |
102 | /* | |
103 | * Approved way of getting address of caller | |
104 | */ | |
105 | #define svc_getcaller(x) (&(x)->xp_raddr) | |
106 | ||
107 | /* | |
108 | * Operations defined on an SVCXPRT handle | |
109 | * | |
110 | * SVCXPRT *xprt; | |
111 | * struct rpc_msg *msg; | |
112 | * xdrproc_t xargs; | |
113 | * caddr_t argsp; | |
114 | */ | |
115 | #define SVC_RECV(xprt, msg) \ | |
116 | (*(xprt)->xp_ops->xp_recv)((xprt), (msg)) | |
117 | #define svc_recv(xprt, msg) \ | |
118 | (*(xprt)->xp_ops->xp_recv)((xprt), (msg)) | |
119 | ||
120 | #define SVC_STAT(xprt) \ | |
121 | (*(xprt)->xp_ops->xp_stat)(xprt) | |
122 | #define svc_stat(xprt) \ | |
123 | (*(xprt)->xp_ops->xp_stat)(xprt) | |
124 | ||
125 | #define SVC_GETARGS(xprt, xargs, argsp) \ | |
126 | (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp)) | |
127 | #define svc_getargs(xprt, xargs, argsp) \ | |
128 | (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp)) | |
129 | ||
130 | #define SVC_REPLY(xprt, msg) \ | |
131 | (*(xprt)->xp_ops->xp_reply) ((xprt), (msg)) | |
132 | #define svc_reply(xprt, msg) \ | |
133 | (*(xprt)->xp_ops->xp_reply) ((xprt), (msg)) | |
134 | ||
135 | #define SVC_FREEARGS(xprt, xargs, argsp) \ | |
136 | (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp)) | |
137 | #define svc_freeargs(xprt, xargs, argsp) \ | |
138 | (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp)) | |
139 | ||
140 | #define SVC_DESTROY(xprt) \ | |
141 | (*(xprt)->xp_ops->xp_destroy)(xprt) | |
142 | #define svc_destroy(xprt) \ | |
143 | (*(xprt)->xp_ops->xp_destroy)(xprt) | |
144 | ||
145 | ||
146 | /* | |
147 | * Service request | |
148 | */ | |
149 | struct svc_req { | |
bdb04ee8 UD |
150 | rpcprog_t rq_prog; /* service program number */ |
151 | rpcvers_t rq_vers; /* service protocol version */ | |
152 | rpcproc_t rq_proc; /* the desired procedure */ | |
153 | struct opaque_auth rq_cred; /* raw creds from the wire */ | |
154 | caddr_t rq_clntcred; /* read only cooked cred */ | |
155 | SVCXPRT *rq_xprt; /* associated transport */ | |
28f540f4 RM |
156 | }; |
157 | ||
76b87c03 | 158 | #ifndef __DISPATCH_FN_T |
50304ef0 | 159 | #define __DISPATCH_FN_T |
c1422e5b | 160 | typedef void (*__dispatch_fn_t) (struct svc_req*, SVCXPRT*); |
50304ef0 | 161 | #endif |
28f540f4 RM |
162 | |
163 | /* | |
164 | * Service registration | |
165 | * | |
166 | * svc_register(xprt, prog, vers, dispatch, protocol) | |
167 | * SVCXPRT *xprt; | |
bdb04ee8 UD |
168 | * rpcprog_t prog; |
169 | * rpcvers_t vers; | |
0ebfb8d7 | 170 | * void (*dispatch)(struct svc_req*, SVCXPRT*); |
bdb04ee8 | 171 | * rpcprot_t protocol; like TCP or UDP, zero means do not register |
28f540f4 | 172 | */ |
c1422e5b UD |
173 | extern bool_t svc_register (SVCXPRT *__xprt, rpcprog_t __prog, |
174 | rpcvers_t __vers, __dispatch_fn_t __dispatch, | |
175 | rpcprot_t __protocol) __THROW; | |
28f540f4 RM |
176 | |
177 | /* | |
178 | * Service un-registration | |
179 | * | |
180 | * svc_unregister(prog, vers) | |
bdb04ee8 UD |
181 | * rpcprog_t prog; |
182 | * rpcvers_t vers; | |
28f540f4 | 183 | */ |
c1422e5b | 184 | extern void svc_unregister (rpcprog_t __prog, rpcvers_t __vers) __THROW; |
28f540f4 RM |
185 | |
186 | /* | |
187 | * Transport registration. | |
188 | * | |
189 | * xprt_register(xprt) | |
190 | * SVCXPRT *xprt; | |
191 | */ | |
c1422e5b | 192 | extern void xprt_register (SVCXPRT *__xprt) __THROW; |
28f540f4 RM |
193 | |
194 | /* | |
195 | * Transport un-register | |
196 | * | |
197 | * xprt_unregister(xprt) | |
198 | * SVCXPRT *xprt; | |
199 | */ | |
c1422e5b | 200 | extern void xprt_unregister (SVCXPRT *__xprt) __THROW; |
28f540f4 RM |
201 | |
202 | ||
203 | /* | |
204 | * When the service routine is called, it must first check to see if it | |
205 | * knows about the procedure; if not, it should call svcerr_noproc | |
fc933e28 | 206 | * and return. If so, it should deserialize its arguments via |
28f540f4 RM |
207 | * SVC_GETARGS (defined above). If the deserialization does not work, |
208 | * svcerr_decode should be called followed by a return. Successful | |
209 | * decoding of the arguments should be followed the execution of the | |
210 | * procedure's code and a call to svc_sendreply. | |
211 | * | |
212 | * Also, if the service refuses to execute the procedure due to too- | |
213 | * weak authentication parameters, svcerr_weakauth should be called. | |
214 | * Note: do not confuse access-control failure with weak authentication! | |
215 | * | |
216 | * NB: In pure implementations of rpc, the caller always waits for a reply | |
fc933e28 | 217 | * msg. This message is sent when svc_sendreply is called. |
28f540f4 RM |
218 | * Therefore pure service implementations should always call |
219 | * svc_sendreply even if the function logically returns void; use | |
220 | * xdr.h - xdr_void for the xdr routine. HOWEVER, tcp based rpc allows | |
221 | * for the abuse of pure rpc via batched calling or pipelining. In the | |
222 | * case of a batched call, svc_sendreply should NOT be called since | |
223 | * this would send a return message, which is what batching tries to avoid. | |
224 | * It is the service/protocol writer's responsibility to know which calls are | |
225 | * batched and which are not. Warning: responding to batch calls may | |
226 | * deadlock the caller and server processes! | |
227 | */ | |
228 | ||
d82a27f8 | 229 | extern bool_t svc_sendreply (SVCXPRT *__xprt, xdrproc_t __xdr_results, |
c1422e5b | 230 | caddr_t __xdr_location) __THROW; |
fc933e28 | 231 | |
c1422e5b | 232 | extern void svcerr_decode (SVCXPRT *__xprt) __THROW; |
fc933e28 | 233 | |
c1422e5b | 234 | extern void svcerr_weakauth (SVCXPRT *__xprt) __THROW; |
fc933e28 | 235 | |
c1422e5b | 236 | extern void svcerr_noproc (SVCXPRT *__xprt) __THROW; |
fc933e28 | 237 | |
c1422e5b UD |
238 | extern void svcerr_progvers (SVCXPRT *__xprt, rpcvers_t __low_vers, |
239 | rpcvers_t __high_vers) __THROW; | |
fc933e28 | 240 | |
c1422e5b | 241 | extern void svcerr_auth (SVCXPRT *__xprt, enum auth_stat __why) __THROW; |
fc933e28 | 242 | |
c1422e5b | 243 | extern void svcerr_noprog (SVCXPRT *__xprt) __THROW; |
fc933e28 | 244 | |
c1422e5b | 245 | extern void svcerr_systemerr (SVCXPRT *__xprt) __THROW; |
fc933e28 | 246 | |
28f540f4 RM |
247 | /* |
248 | * Lowest level dispatching -OR- who owns this process anyway. | |
249 | * Somebody has to wait for incoming requests and then call the correct | |
250 | * service routine. The routine svc_run does infinite waiting; i.e., | |
251 | * svc_run never returns. | |
5b826692 | 252 | * Since another (coexistent) package may wish to selectively wait for |
28f540f4 RM |
253 | * incoming calls or other events outside of the rpc architecture, the |
254 | * routine svc_getreq is provided. It must be passed readfds, the | |
255 | * "in-place" results of a select system call (see select, section 2). | |
256 | */ | |
257 | ||
258 | /* | |
259 | * Global keeper of rpc service descriptors in use | |
fc933e28 | 260 | * dynamic; must be inspected before each call to select |
28f540f4 | 261 | */ |
bdb04ee8 UD |
262 | |
263 | extern struct pollfd *svc_pollfd; | |
264 | extern int svc_max_pollfd; | |
28f540f4 RM |
265 | extern fd_set svc_fdset; |
266 | #define svc_fds svc_fdset.fds_bits[0] /* compatibility */ | |
28f540f4 RM |
267 | |
268 | /* | |
269 | * a small program implemented by the svc_rpc implementation itself; | |
270 | * also see clnt.h for protocol numbers. | |
271 | */ | |
c1422e5b UD |
272 | extern void svc_getreq (int __rdfds) __THROW; |
273 | extern void svc_getreq_common (const int __fd) __THROW; | |
274 | extern void svc_getreqset (fd_set *__readfds) __THROW; | |
275 | extern void svc_getreq_poll (struct pollfd *, const int) __THROW; | |
276 | extern void svc_exit (void) __THROW; | |
277 | extern void svc_run (void) __THROW; | |
28f540f4 RM |
278 | |
279 | /* | |
280 | * Socket to use on svcxxx_create call to get default socket | |
281 | */ | |
282 | #define RPC_ANYSOCK -1 | |
283 | ||
284 | /* | |
285 | * These are the existing service side transport implementations | |
286 | */ | |
287 | ||
288 | /* | |
289 | * Memory based rpc for testing and timing. | |
290 | */ | |
c1422e5b | 291 | extern SVCXPRT *svcraw_create (void) __THROW; |
28f540f4 RM |
292 | |
293 | /* | |
294 | * Udp based rpc. | |
295 | */ | |
c1422e5b UD |
296 | extern SVCXPRT *svcudp_create (int __sock) __THROW; |
297 | extern SVCXPRT *svcudp_bufcreate (int __sock, u_int __sendsz, u_int __recvsz) | |
298 | __THROW; | |
28f540f4 RM |
299 | |
300 | /* | |
301 | * Tcp based rpc. | |
302 | */ | |
c1422e5b UD |
303 | extern SVCXPRT *svctcp_create (int __sock, u_int __sendsize, u_int __recvsize) |
304 | __THROW; | |
28f540f4 | 305 | |
2bcaff08 UD |
306 | /* |
307 | * FD based rpc. | |
308 | */ | |
309 | extern SVCXPRT *svcfd_create (int __sock, u_int __sendsize, u_int __recvsize) | |
310 | __THROW; | |
28f540f4 | 311 | |
e852e889 UD |
312 | /* |
313 | * Unix based rpc. | |
314 | */ | |
c1422e5b UD |
315 | extern SVCXPRT *svcunix_create (int __sock, u_int __sendsize, u_int __recvsize, |
316 | char *__path) __THROW; | |
e852e889 UD |
317 | |
318 | ||
fc933e28 | 319 | __END_DECLS |
28f540f4 | 320 | |
5107cf1d | 321 | #endif /* rpc/svc.h */ |