]>
Commit | Line | Data |
---|---|---|
28f540f4 RM |
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. | |
fc933e28 | 8 | * |
28f540f4 RM |
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. | |
fc933e28 | 12 | * |
28f540f4 RM |
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. | |
fc933e28 | 16 | * |
28f540f4 RM |
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. | |
fc933e28 | 20 | * |
28f540f4 RM |
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. | |
fc933e28 | 24 | * |
28f540f4 RM |
25 | * Sun Microsystems, Inc. |
26 | * 2550 Garcia Avenue | |
27 | * Mountain View, California 94043 | |
28 | */ | |
29 | ||
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 UD |
84 | bool_t (*xp_getargs) (SVCXPRT *__xprt, xdrproc_t __xdr_args, |
85 | caddr_t args_ptr); /* get arguments */ | |
86 | bool_t (*xp_reply) (SVCXPRT *__xprt, struct rpc_msg *__msg); | |
e7fd8a39 | 87 | /* send reply */ |
c1422e5b UD |
88 | bool_t (*xp_freeargs) (SVCXPRT *__xprt, xdrproc_t __xdr_args, |
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 */ | |
95 | struct sockaddr_in xp_raddr; /* remote address */ | |
96 | struct opaque_auth xp_verf; /* raw response verifier */ | |
97 | caddr_t xp_p1; /* private */ | |
98 | caddr_t xp_p2; /* private */ | |
99 | }; | |
28f540f4 RM |
100 | |
101 | /* | |
102 | * Approved way of getting address of caller | |
103 | */ | |
104 | #define svc_getcaller(x) (&(x)->xp_raddr) | |
105 | ||
106 | /* | |
107 | * Operations defined on an SVCXPRT handle | |
108 | * | |
109 | * SVCXPRT *xprt; | |
110 | * struct rpc_msg *msg; | |
111 | * xdrproc_t xargs; | |
112 | * caddr_t argsp; | |
113 | */ | |
114 | #define SVC_RECV(xprt, msg) \ | |
115 | (*(xprt)->xp_ops->xp_recv)((xprt), (msg)) | |
116 | #define svc_recv(xprt, msg) \ | |
117 | (*(xprt)->xp_ops->xp_recv)((xprt), (msg)) | |
118 | ||
119 | #define SVC_STAT(xprt) \ | |
120 | (*(xprt)->xp_ops->xp_stat)(xprt) | |
121 | #define svc_stat(xprt) \ | |
122 | (*(xprt)->xp_ops->xp_stat)(xprt) | |
123 | ||
124 | #define SVC_GETARGS(xprt, xargs, argsp) \ | |
125 | (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp)) | |
126 | #define svc_getargs(xprt, xargs, argsp) \ | |
127 | (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp)) | |
128 | ||
129 | #define SVC_REPLY(xprt, msg) \ | |
130 | (*(xprt)->xp_ops->xp_reply) ((xprt), (msg)) | |
131 | #define svc_reply(xprt, msg) \ | |
132 | (*(xprt)->xp_ops->xp_reply) ((xprt), (msg)) | |
133 | ||
134 | #define SVC_FREEARGS(xprt, xargs, argsp) \ | |
135 | (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp)) | |
136 | #define svc_freeargs(xprt, xargs, argsp) \ | |
137 | (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp)) | |
138 | ||
139 | #define SVC_DESTROY(xprt) \ | |
140 | (*(xprt)->xp_ops->xp_destroy)(xprt) | |
141 | #define svc_destroy(xprt) \ | |
142 | (*(xprt)->xp_ops->xp_destroy)(xprt) | |
143 | ||
144 | ||
145 | /* | |
146 | * Service request | |
147 | */ | |
148 | struct svc_req { | |
bdb04ee8 UD |
149 | rpcprog_t rq_prog; /* service program number */ |
150 | rpcvers_t rq_vers; /* service protocol version */ | |
151 | rpcproc_t rq_proc; /* the desired procedure */ | |
152 | struct opaque_auth rq_cred; /* raw creds from the wire */ | |
153 | caddr_t rq_clntcred; /* read only cooked cred */ | |
154 | SVCXPRT *rq_xprt; /* associated transport */ | |
28f540f4 RM |
155 | }; |
156 | ||
76b87c03 | 157 | #ifndef __DISPATCH_FN_T |
50304ef0 | 158 | #define __DISPATCH_FN_T |
c1422e5b | 159 | typedef void (*__dispatch_fn_t) (struct svc_req*, SVCXPRT*); |
50304ef0 | 160 | #endif |
28f540f4 RM |
161 | |
162 | /* | |
163 | * Service registration | |
164 | * | |
165 | * svc_register(xprt, prog, vers, dispatch, protocol) | |
166 | * SVCXPRT *xprt; | |
bdb04ee8 UD |
167 | * rpcprog_t prog; |
168 | * rpcvers_t vers; | |
28f540f4 | 169 | * void (*dispatch)(); |
bdb04ee8 | 170 | * rpcprot_t protocol; like TCP or UDP, zero means do not register |
28f540f4 | 171 | */ |
c1422e5b UD |
172 | extern bool_t svc_register (SVCXPRT *__xprt, rpcprog_t __prog, |
173 | rpcvers_t __vers, __dispatch_fn_t __dispatch, | |
174 | rpcprot_t __protocol) __THROW; | |
28f540f4 RM |
175 | |
176 | /* | |
177 | * Service un-registration | |
178 | * | |
179 | * svc_unregister(prog, vers) | |
bdb04ee8 UD |
180 | * rpcprog_t prog; |
181 | * rpcvers_t vers; | |
28f540f4 | 182 | */ |
c1422e5b | 183 | extern void svc_unregister (rpcprog_t __prog, rpcvers_t __vers) __THROW; |
28f540f4 RM |
184 | |
185 | /* | |
186 | * Transport registration. | |
187 | * | |
188 | * xprt_register(xprt) | |
189 | * SVCXPRT *xprt; | |
190 | */ | |
c1422e5b | 191 | extern void xprt_register (SVCXPRT *__xprt) __THROW; |
28f540f4 RM |
192 | |
193 | /* | |
194 | * Transport un-register | |
195 | * | |
196 | * xprt_unregister(xprt) | |
197 | * SVCXPRT *xprt; | |
198 | */ | |
c1422e5b | 199 | extern void xprt_unregister (SVCXPRT *__xprt) __THROW; |
28f540f4 RM |
200 | |
201 | ||
202 | /* | |
203 | * When the service routine is called, it must first check to see if it | |
204 | * knows about the procedure; if not, it should call svcerr_noproc | |
fc933e28 | 205 | * and return. If so, it should deserialize its arguments via |
28f540f4 RM |
206 | * SVC_GETARGS (defined above). If the deserialization does not work, |
207 | * svcerr_decode should be called followed by a return. Successful | |
208 | * decoding of the arguments should be followed the execution of the | |
209 | * procedure's code and a call to svc_sendreply. | |
210 | * | |
211 | * Also, if the service refuses to execute the procedure due to too- | |
212 | * weak authentication parameters, svcerr_weakauth should be called. | |
213 | * Note: do not confuse access-control failure with weak authentication! | |
214 | * | |
215 | * NB: In pure implementations of rpc, the caller always waits for a reply | |
fc933e28 | 216 | * msg. This message is sent when svc_sendreply is called. |
28f540f4 RM |
217 | * Therefore pure service implementations should always call |
218 | * svc_sendreply even if the function logically returns void; use | |
219 | * xdr.h - xdr_void for the xdr routine. HOWEVER, tcp based rpc allows | |
220 | * for the abuse of pure rpc via batched calling or pipelining. In the | |
221 | * case of a batched call, svc_sendreply should NOT be called since | |
222 | * this would send a return message, which is what batching tries to avoid. | |
223 | * It is the service/protocol writer's responsibility to know which calls are | |
224 | * batched and which are not. Warning: responding to batch calls may | |
225 | * deadlock the caller and server processes! | |
226 | */ | |
227 | ||
c1422e5b UD |
228 | extern bool_t svc_sendreply (SVCXPRT *xprt, xdrproc_t __xdr_results, |
229 | caddr_t __xdr_location) __THROW; | |
fc933e28 | 230 | |
c1422e5b | 231 | extern void svcerr_decode (SVCXPRT *__xprt) __THROW; |
fc933e28 | 232 | |
c1422e5b | 233 | extern void svcerr_weakauth (SVCXPRT *__xprt) __THROW; |
fc933e28 | 234 | |
c1422e5b | 235 | extern void svcerr_noproc (SVCXPRT *__xprt) __THROW; |
fc933e28 | 236 | |
c1422e5b UD |
237 | extern void svcerr_progvers (SVCXPRT *__xprt, rpcvers_t __low_vers, |
238 | rpcvers_t __high_vers) __THROW; | |
fc933e28 | 239 | |
c1422e5b | 240 | extern void svcerr_auth (SVCXPRT *__xprt, enum auth_stat __why) __THROW; |
fc933e28 | 241 | |
c1422e5b | 242 | extern void svcerr_noprog (SVCXPRT *__xprt) __THROW; |
fc933e28 | 243 | |
c1422e5b | 244 | extern void svcerr_systemerr (SVCXPRT *__xprt) __THROW; |
fc933e28 | 245 | |
28f540f4 RM |
246 | /* |
247 | * Lowest level dispatching -OR- who owns this process anyway. | |
248 | * Somebody has to wait for incoming requests and then call the correct | |
249 | * service routine. The routine svc_run does infinite waiting; i.e., | |
250 | * svc_run never returns. | |
5b826692 | 251 | * Since another (coexistent) package may wish to selectively wait for |
28f540f4 RM |
252 | * incoming calls or other events outside of the rpc architecture, the |
253 | * routine svc_getreq is provided. It must be passed readfds, the | |
254 | * "in-place" results of a select system call (see select, section 2). | |
255 | */ | |
256 | ||
257 | /* | |
258 | * Global keeper of rpc service descriptors in use | |
fc933e28 | 259 | * dynamic; must be inspected before each call to select |
28f540f4 | 260 | */ |
bdb04ee8 UD |
261 | |
262 | extern struct pollfd *svc_pollfd; | |
263 | extern int svc_max_pollfd; | |
28f540f4 RM |
264 | extern fd_set svc_fdset; |
265 | #define svc_fds svc_fdset.fds_bits[0] /* compatibility */ | |
28f540f4 RM |
266 | |
267 | /* | |
268 | * a small program implemented by the svc_rpc implementation itself; | |
269 | * also see clnt.h for protocol numbers. | |
270 | */ | |
c1422e5b UD |
271 | extern void svc_getreq (int __rdfds) __THROW; |
272 | extern void svc_getreq_common (const int __fd) __THROW; | |
273 | extern void svc_getreqset (fd_set *__readfds) __THROW; | |
274 | extern void svc_getreq_poll (struct pollfd *, const int) __THROW; | |
275 | extern void svc_exit (void) __THROW; | |
276 | extern void svc_run (void) __THROW; | |
28f540f4 RM |
277 | |
278 | /* | |
279 | * Socket to use on svcxxx_create call to get default socket | |
280 | */ | |
281 | #define RPC_ANYSOCK -1 | |
282 | ||
283 | /* | |
284 | * These are the existing service side transport implementations | |
285 | */ | |
286 | ||
287 | /* | |
288 | * Memory based rpc for testing and timing. | |
289 | */ | |
c1422e5b | 290 | extern SVCXPRT *svcraw_create (void) __THROW; |
28f540f4 RM |
291 | |
292 | /* | |
293 | * Udp based rpc. | |
294 | */ | |
c1422e5b UD |
295 | extern SVCXPRT *svcudp_create (int __sock) __THROW; |
296 | extern SVCXPRT *svcudp_bufcreate (int __sock, u_int __sendsz, u_int __recvsz) | |
297 | __THROW; | |
28f540f4 RM |
298 | |
299 | /* | |
300 | * Tcp based rpc. | |
301 | */ | |
c1422e5b UD |
302 | extern SVCXPRT *svctcp_create (int __sock, u_int __sendsize, u_int __recvsize) |
303 | __THROW; | |
28f540f4 RM |
304 | |
305 | ||
e852e889 UD |
306 | /* |
307 | * Unix based rpc. | |
308 | */ | |
c1422e5b UD |
309 | extern SVCXPRT *svcunix_create (int __sock, u_int __sendsize, u_int __recvsize, |
310 | char *__path) __THROW; | |
e852e889 UD |
311 | |
312 | ||
fc933e28 | 313 | __END_DECLS |
28f540f4 | 314 | |
5107cf1d | 315 | #endif /* rpc/svc.h */ |