Details | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
4973 | right-hear | 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 | |||
30 | /* |
||
31 | * svc.h, Server-side remote procedure call interface. |
||
32 | * |
||
33 | * Copyright (C) 1984, Sun Microsystems, Inc. |
||
34 | */ |
||
35 | |||
36 | #ifndef _RPC_SVC_H |
||
37 | #define _RPC_SVC_H 1 |
||
38 | |||
39 | #include |
||
40 | #include |
||
41 | |||
42 | __BEGIN_DECLS |
||
43 | |||
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 | */ |
||
75 | typedef struct SVCXPRT SVCXPRT; |
||
76 | struct SVCXPRT { |
||
77 | int xp_sock; |
||
78 | unsigned short xp_port; /* associated port number */ |
||
79 | const struct xp_ops { |
||
80 | bool_t (*xp_recv) (SVCXPRT *__xprt, struct rpc_msg *__msg); |
||
81 | /* receive incoming requests */ |
||
82 | enum xprt_stat (*xp_stat) (SVCXPRT *__xprt); |
||
83 | /* get transport status */ |
||
84 | bool_t (*xp_getargs) (SVCXPRT *__xprt, xdrproc_t __xdr_args, |
||
85 | char* args_ptr); /* get arguments */ |
||
86 | bool_t (*xp_reply) (SVCXPRT *__xprt, struct rpc_msg *__msg); |
||
87 | /* send reply */ |
||
88 | bool_t (*xp_freeargs) (SVCXPRT *__xprt, xdrproc_t __xdr_args, |
||
89 | char* args_ptr); |
||
90 | /* free mem allocated for args */ |
||
91 | void (*xp_destroy) (SVCXPRT *__xprt); |
||
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 | char* xp_p1; /* private */ |
||
98 | char* xp_p2; /* private */ |
||
99 | char xp_pad [256]; /* padding, internal use */ |
||
100 | }; |
||
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 | * char* 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 { |
||
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 | char* rq_clntcred; /* read only cooked cred */ |
||
155 | SVCXPRT *rq_xprt; /* associated transport */ |
||
156 | }; |
||
157 | |||
158 | #ifndef __DISPATCH_FN_T |
||
159 | #define __DISPATCH_FN_T |
||
160 | typedef void (*__dispatch_fn_t) (struct svc_req*, SVCXPRT*); |
||
161 | #endif |
||
162 | |||
163 | /* |
||
164 | * Service registration |
||
165 | * |
||
166 | * svc_register(xprt, prog, vers, dispatch, protocol) |
||
167 | * SVCXPRT *xprt; |
||
168 | * rpcprog_t prog; |
||
169 | * rpcvers_t vers; |
||
170 | * void (*dispatch)(struct svc_req*, SVCXPRT*); |
||
171 | * rpcprot_t protocol; like TCP or UDP, zero means do not register |
||
172 | */ |
||
173 | extern bool_t svc_register (SVCXPRT *__xprt, rpcprog_t __prog, |
||
174 | rpcvers_t __vers, __dispatch_fn_t __dispatch, |
||
175 | rpcprot_t __protocol) __THROW; |
||
176 | |||
177 | /* |
||
178 | * Service un-registration |
||
179 | * |
||
180 | * svc_unregister(prog, vers) |
||
181 | * rpcprog_t prog; |
||
182 | * rpcvers_t vers; |
||
183 | */ |
||
184 | extern void svc_unregister (rpcprog_t __prog, rpcvers_t __vers) __THROW; |
||
185 | |||
186 | /* |
||
187 | * Transport registration. |
||
188 | * |
||
189 | * xprt_register(xprt) |
||
190 | * SVCXPRT *xprt; |
||
191 | */ |
||
192 | extern void xprt_register (SVCXPRT *__xprt) __THROW; |
||
193 | |||
194 | /* |
||
195 | * Transport un-register |
||
196 | * |
||
197 | * xprt_unregister(xprt) |
||
198 | * SVCXPRT *xprt; |
||
199 | */ |
||
200 | extern void xprt_unregister (SVCXPRT *__xprt) __THROW; |
||
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 |
||
206 | * and return. If so, it should deserialize its arguments via |
||
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 |
||
217 | * msg. This message is sent when svc_sendreply is called. |
||
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 | |||
229 | extern bool_t svc_sendreply (SVCXPRT *xprt, xdrproc_t __xdr_results, |
||
230 | char* __xdr_location) __THROW; |
||
231 | |||
232 | extern void svcerr_decode (SVCXPRT *__xprt) __THROW; |
||
233 | |||
234 | extern void svcerr_weakauth (SVCXPRT *__xprt) __THROW; |
||
235 | |||
236 | extern void svcerr_noproc (SVCXPRT *__xprt) __THROW; |
||
237 | |||
238 | extern void svcerr_progvers (SVCXPRT *__xprt, rpcvers_t __low_vers, |
||
239 | rpcvers_t __high_vers) __THROW; |
||
240 | |||
241 | extern void svcerr_auth (SVCXPRT *__xprt, enum auth_stat __why) __THROW; |
||
242 | |||
243 | extern void svcerr_noprog (SVCXPRT *__xprt) __THROW; |
||
244 | |||
245 | extern void svcerr_systemerr (SVCXPRT *__xprt) __THROW; |
||
246 | |||
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. |
||
252 | * Since another (coexistent) package may wish to selectively wait for |
||
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 |
||
260 | * dynamic; must be inspected before each call to select |
||
261 | */ |
||
262 | |||
263 | extern struct pollfd *svc_pollfd; |
||
264 | extern int svc_max_pollfd; |
||
265 | extern fd_set svc_fdset; |
||
266 | #define svc_fds svc_fdset.fds_bits[0] /* compatibility */ |
||
267 | |||
268 | /* |
||
269 | * a small program implemented by the svc_rpc implementation itself; |
||
270 | * also see clnt.h for protocol numbers. |
||
271 | */ |
||
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; |
||
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 | */ |
||
291 | extern SVCXPRT *svcraw_create (void) __THROW; |
||
292 | |||
293 | /* |
||
294 | * Udp based rpc. |
||
295 | */ |
||
296 | extern SVCXPRT *svcudp_create (int __sock) __THROW; |
||
297 | extern SVCXPRT *svcudp_bufcreate (int __sock, unsigned int __sendsz, unsigned int __recvsz) |
||
298 | __THROW; |
||
299 | |||
300 | /* |
||
301 | * Tcp based rpc. |
||
302 | */ |
||
303 | extern SVCXPRT *svctcp_create (int __sock, unsigned int __sendsize, unsigned int __recvsize) |
||
304 | __THROW; |
||
305 | |||
306 | |||
307 | /* |
||
308 | * Unix based rpc. |
||
309 | */ |
||
310 | extern SVCXPRT *svcunix_create (int __sock, unsigned int __sendsize, unsigned int __recvsize, |
||
311 | char *__path) __THROW; |
||
312 | |||
313 | |||
314 | __END_DECLS |
||
315 | |||
316 | #endif /* rpc/svc.h */ |