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
