• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 #ifdef __cplusplus
40 extern "C" {
41 #endif
42 
43 #include <rpc/types.h>
44 
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 bool_t 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 /*
68  * Server side transport handle
69  */
70 struct SVCXPRT;
71 typedef struct SVCXPRT SVCXPRT;
72 
73 /*
74  * Service request
75  */
76 struct svc_req {
77   rpcprog_t rq_prog;            /* service program number */
78   rpcvers_t rq_vers;            /* service protocol version */
79   rpcproc_t rq_proc;            /* the desired procedure */
80   SVCXPRT *rq_xprt;             /* associated transport */
81 };
82 
83 #ifndef __DISPATCH_FN_T
84 #define __DISPATCH_FN_T
85 typedef void (*__dispatch_fn_t) (struct svc_req*, SVCXPRT*);
86 #endif
87 
88 /*
89  * Transport registration.
90  *
91  * xprt_register(xprt)
92  *      SVCXPRT *xprt;
93  */
94 extern void xprt_register (SVCXPRT *__xprt);
95 
96 /*
97  * Transport un-register
98  *
99  * xprt_unregister(xprt)
100  *      SVCXPRT *xprt;
101  */
102 extern void xprt_unregister (SVCXPRT *__xprt);
103 
104 /*
105  * Service registration (registers only with plugger module)
106  *
107  * svc_register_with_plugger(xprt, prog, vers, dispatch, protocol)
108  *	SVCXPRT *xprt;
109  *	rpcprog_t prog;
110  *	rpcvers_t vers;
111  *	void (*dispatch)(struct svc_req*, SVCXPRT*);
112  *	rpcprot_t protocol;  like TCP or UDP, zero means do not register
113  */
114 extern bool_t svc_register_with_plugger (SVCXPRT *__xprt, rpcprog_t __prog,
115                                          rpcvers_t __vers,
116                                          __dispatch_fn_t __dispatch,
117                                          rpcprot_t __protocol);
118 
119 /*
120  * Service registration (registers with plugger module and lower layers)
121  *
122  * svc_register(xprt, prog, vers, dispatch, protocol)
123  *	SVCXPRT *xprt;
124  *	rpcprog_t prog;
125  *	rpcvers_t vers;
126  *	void (*dispatch)(struct svc_req*, SVCXPRT*);
127  *	rpcprot_t protocol;  like TCP or UDP, zero means do not register
128  */
129 extern bool_t svc_register (SVCXPRT *__xprt, rpcprog_t __prog,
130                             rpcvers_t __vers, __dispatch_fn_t __dispatch,
131                             rpcprot_t __protocol);
132 
133 extern void svc_destroy(SVCXPRT *xprt);
134 
135 /*
136  * Service un-registration
137  *
138  * svc_unregister(xprt, prog, vers)
139  *  SVCXPRT *xprt
140  *	rpcprog_t prog;
141  *	rpcvers_t vers;
142  */
143 void
144 svc_unregister (SVCXPRT *__xprt, rpcprog_t prog, rpcvers_t vers);
145 
146 /*
147  * Service Enable
148  *
149  * svc_enable( prog, vers )
150  *	rpcprog_t prog;
151  *	rpcvers_t vers;
152  */
153 #define svc_enable(prog, vers) svc_lock(prog, vers, FALSE)
154 
155 /*
156  * Service Disable
157  *
158  * svc_disable( prog, vers )
159  *	rpcprog_t prog;
160  *	rpcvers_t vers;
161  */
162 #define svc_disable(prog, vers) svc_lock(prog, vers, TRUE)
163 
164 extern void svc_lock(rpcprog_t __prog, rpcvers_t __vers, bool_t __lock);
165 
166 /*
167  * When the service routine is called, it must first check to see if it
168  * knows about the procedure;  if not, it should call svcerr_noproc
169  * and return.  If so, it should deserialize its arguments via
170  * SVC_GETARGS (defined above).  If the deserialization does not work,
171  * svcerr_decode should be called followed by a return.  Successful
172  * decoding of the arguments should be followed the execution of the
173  * procedure's code and a call to svc_sendreply.
174  *
175  * Also, if the service refuses to execute the procedure due to too-
176  * weak authentication parameters, svcerr_weakauth should be called.
177  * Note: do not confuse access-control failure with weak authentication!
178  *
179  * NB: In pure implementations of rpc, the caller always waits for a reply
180  * msg.  This message is sent when svc_sendreply is called.
181  * Therefore pure service implementations should always call
182  * svc_sendreply even if the function logically returns void;  use
183  * xdr.h - xdr_void for the xdr routine.  HOWEVER, tcp based rpc allows
184  * for the abuse of pure rpc via batched calling or pipelining.  In the
185  * case of a batched call, svc_sendreply should NOT be called since
186  * this would send a return message, which is what batching tries to avoid.
187  * It is the service/protocol writer's responsibility to know which calls are
188  * batched and which are not.  Warning: responding to batch calls may
189  * deadlock the caller and server processes!
190  */
191 
192 extern bool_t svc_getargs(SVCXPRT *xdr, xdrproc_t xdr_args, caddr_t args_ptr);
193 extern bool_t svc_freeargs(SVCXPRT *xdr, xdrproc_t xdr_args, caddr_t args_ptr);
194 
195 extern bool_t	svc_sendreply (SVCXPRT *xprt, xdrproc_t __xdr_results,
196 			       caddr_t __xdr_location);
197 
198 /*
199  * Socket to use on svcxxx_create call to get default socket
200  */
201 #define	RPC_ANYSOCK	-1
202 
203 /*
204  * Router based rpc.
205  */
206 extern SVCXPRT *svcrtr_create (void);
207 
208 extern void svcerr_decode (SVCXPRT *);
209 extern void svcerr_weakauth (SVCXPRT *);
210 extern void svcerr_noproc (SVCXPRT *);
211 extern void svcerr_noprog (SVCXPRT *);
212 extern void svcerr_systemerr (SVCXPRT *);
213 extern void svcerr_progvers (SVCXPRT *, rpcvers_t __low_vers, rpcvers_t __high_vers);
214 extern void svcerr_auth (SVCXPRT *, auth_stat __why);
215 
216 #ifdef __cplusplus
217 }
218 #endif
219 
220 #endif /* rpc/svc.h */
221