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