1/* 2 * Copyright (c) 1999 Apple Computer, Inc. All rights reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * Portions Copyright (c) 1999 Apple Computer, Inc. All Rights 7 * Reserved. This file contains Original Code and/or Modifications of 8 * Original Code as defined in and that are subject to the Apple Public 9 * Source License Version 1.1 (the "License"). You may not use this file 10 * except in compliance with the License. Please obtain a copy of the 11 * License at http://www.apple.com/publicsource and read it before using 12 * this file. 13 * 14 * The Original Code and all software distributed under the License are 15 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER 16 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 17 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 18 * FITNESS FOR A PARTICULAR PURPOSE OR NON- INFRINGEMENT. Please see the 19 * License for the specific language governing rights and limitations 20 * under the License. 21 * 22 * @APPLE_LICENSE_HEADER_END@ 23 */ 24/* 25 * Sun RPC is a product of Sun Microsystems, Inc. and is provided for 26 * unrestricted use provided that this legend is included on all tape 27 * media and as a part of the software program in whole or part. Users 28 * may copy or modify Sun RPC without charge, but are not authorized 29 * to license or distribute it to anyone else except as part of a product or 30 * program developed by the user. 31 * 32 * SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE 33 * WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR 34 * PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE. 35 * 36 * Sun RPC is provided with no support and without any obligation on the 37 * part of Sun Microsystems, Inc. to assist in its use, correction, 38 * modification or enhancement. 39 * 40 * SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE 41 * INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY SUN RPC 42 * OR ANY PART THEREOF. 43 * 44 * In no event will Sun Microsystems, Inc. be liable for any lost revenue 45 * or profits or other special, indirect and consequential damages, even if 46 * Sun has been advised of the possibility of such damages. 47 * 48 * Sun Microsystems, Inc. 49 * 2550 Garcia Avenue 50 * Mountain View, California 94043 51 * 52 * from: @(#)svc.h 1.20 88/02/08 SMI 53 * from: @(#)svc.h 2.2 88/07/29 4.0 RPCSRC 54 * $Id: svc.h,v 1.4 2004/11/25 19:41:19 emoy Exp $ 55 */ 56 57/* 58 * svc.h, Server-side remote procedure call interface. 59 * 60 * Copyright (C) 1984, Sun Microsystems, Inc. 61 */ 62 63#ifndef _RPC_SVC_H 64#define _RPC_SVC_H 65#include <sys/cdefs.h> 66 67/* 68 * This interface must manage two items concerning remote procedure calling: 69 * 70 * 1) An arbitrary number of transport connections upon which rpc requests 71 * are received. The two most notable transports are TCP and UDP; they are 72 * created and registered by routines in svc_tcp.c and svc_udp.c, respectively; 73 * they in turn call xprt_register and xprt_unregister. 74 * 75 * 2) An arbitrary number of locally registered services. Services are 76 * described by the following four data: program number, version number, 77 * "service dispatch" function, a transport handle, and a boolean that 78 * indicates whether or not the exported program should be registered with a 79 * local binder service; if true the program's number and version and the 80 * port number from the transport handle are registered with the binder. 81 * These data are registered with the rpc svc system via svc_register. 82 * 83 * A service's dispatch function is called whenever an rpc request comes in 84 * on a transport. The request's program and version numbers must match 85 * those of the registered service. The dispatch function is passed two 86 * parameters, struct svc_req * and SVCXPRT *, defined below. 87 */ 88 89enum xprt_stat { 90 XPRT_DIED, 91 XPRT_MOREREQS, 92 XPRT_IDLE 93}; 94 95/* 96 * Server side transport handle 97 */ 98typedef struct { 99 int xp_sock; 100 unsigned short xp_port; /* associated port number */ 101 struct xp_ops { 102#ifdef __cplusplus 103 bool_t (*xp_recv)(...); /* receive incomming requests */ 104 enum xprt_stat (*xp_stat)(...); /* get transport status */ 105 bool_t (*xp_getargs)(...); /* get arguments */ 106 bool_t (*xp_reply)(...); /* send reply */ 107 bool_t (*xp_freeargs)(...);/* free mem allocated for args */ 108 void (*xp_destroy)(...); /* destroy this struct */ 109#else 110 /* DO NOT REMOVE THE COMMENTED OUT ...: fixincludes needs to see them */ 111 bool_t (*xp_recv)(/*...*/); /* receive incomming requests */ 112 enum xprt_stat (*xp_stat)(/*...*/); /* get transport status */ 113 bool_t (*xp_getargs)(/*...*/); /* get arguments */ 114 bool_t (*xp_reply)(/*...*/); /* send reply */ 115 bool_t (*xp_freeargs)(/*...*/);/* free mem allocated for args */ 116 void (*xp_destroy)(/*...*/); /* destroy this struct */ 117#endif 118 } *xp_ops; 119 int xp_addrlen; /* length of remote address */ 120 struct sockaddr_in xp_raddr; /* remote address */ 121 struct opaque_auth xp_verf; /* raw response verifier */ 122 caddr_t xp_p1; /* private */ 123 caddr_t xp_p2; /* private */ 124} SVCXPRT; 125 126/* 127 * Approved way of getting address of caller 128 */ 129#define svc_getcaller(x) (&(x)->xp_raddr) 130 131/* 132 * Operations defined on an SVCXPRT handle 133 * 134 * SVCXPRT *xprt; 135 * struct rpc_msg *msg; 136 * xdrproc_t xargs; 137 * caddr_t argsp; 138 */ 139#define SVC_RECV(xprt, msg) \ 140 (*(xprt)->xp_ops->xp_recv)((xprt), (msg)) 141#define svc_recv(xprt, msg) \ 142 (*(xprt)->xp_ops->xp_recv)((xprt), (msg)) 143 144#define SVC_STAT(xprt) \ 145 (*(xprt)->xp_ops->xp_stat)(xprt) 146#define svc_stat(xprt) \ 147 (*(xprt)->xp_ops->xp_stat)(xprt) 148 149#define SVC_GETARGS(xprt, xargs, argsp) \ 150 (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp)) 151#define svc_getargs(xprt, xargs, argsp) \ 152 (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp)) 153 154#define SVC_REPLY(xprt, msg) \ 155 (*(xprt)->xp_ops->xp_reply) ((xprt), (msg)) 156#define svc_reply(xprt, msg) \ 157 (*(xprt)->xp_ops->xp_reply) ((xprt), (msg)) 158 159#define SVC_FREEARGS(xprt, xargs, argsp) \ 160 (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp)) 161#define svc_freeargs(xprt, xargs, argsp) \ 162 (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp)) 163 164#define SVC_DESTROY(xprt) \ 165 (*(xprt)->xp_ops->xp_destroy)(xprt) 166#define svc_destroy(xprt) \ 167 (*(xprt)->xp_ops->xp_destroy)(xprt) 168 169 170/* 171 * Service request 172 */ 173struct svc_req { 174#ifdef __LP64__ 175 unsigned int rq_prog; /* service program number */ 176 unsigned int rq_vers; /* service protocol version */ 177 unsigned int rq_proc; /* the desired procedure */ 178#else 179 unsigned long rq_prog; /* service program number */ 180 unsigned long rq_vers; /* service protocol version */ 181 unsigned long rq_proc; /* the desired procedure */ 182#endif 183 struct opaque_auth rq_cred; /* raw creds from the wire */ 184 caddr_t rq_clntcred; /* read only cooked cred */ 185 SVCXPRT *rq_xprt; /* associated transport */ 186}; 187 188 189/* 190 * Service registration 191 * 192 * svc_register(xprt, prog, vers, dispatch, protocol) 193 * SVCXPRT *xprt; 194 * u_long prog; 195 * u_long vers; 196 * void (*dispatch)(...); // fixincludes needs the ..., even in a comment 197 * int protocol; like TCP or UDP, zero means do not register 198 */ 199__BEGIN_DECLS 200#ifdef __LP64__ 201extern bool_t svc_register __P((SVCXPRT *, unsigned int, unsigned int, void (*)(), int)); 202#else 203extern bool_t svc_register __P((SVCXPRT *, unsigned long, unsigned long, void (*)(), int)); 204#endif 205__END_DECLS 206 207/* 208 * Service un-registration 209 * 210 * svc_unregister(prog, vers) 211 * u_long prog; 212 * u_long vers; 213 */ 214__BEGIN_DECLS 215#ifdef __LP64__ 216extern void svc_unregister __P((unsigned int, unsigned int)); 217#else 218extern void svc_unregister __P((unsigned long, unsigned long)); 219#endif 220__END_DECLS 221 222/* 223 * Transport registration. 224 * 225 * xprt_register(xprt) 226 * SVCXPRT *xprt; 227 */ 228__BEGIN_DECLS 229extern void xprt_register __P((SVCXPRT *)); 230__END_DECLS 231 232/* 233 * Transport un-register 234 * 235 * xprt_unregister(xprt) 236 * SVCXPRT *xprt; 237 */ 238__BEGIN_DECLS 239extern void xprt_unregister __P((SVCXPRT *)); 240__END_DECLS 241 242 243 244 245/* 246 * When the service routine is called, it must first check to see if it 247 * knows about the procedure; if not, it should call svcerr_noproc 248 * and return. If so, it should deserialize its arguments via 249 * SVC_GETARGS (defined above). If the deserialization does not work, 250 * svcerr_decode should be called followed by a return. Successful 251 * decoding of the arguments should be followed the execution of the 252 * procedure's code and a call to svc_sendreply. 253 * 254 * Also, if the service refuses to execute the procedure due to too- 255 * weak authentication parameters, svcerr_weakauth should be called. 256 * Note: do not confuse access-control failure with weak authentication! 257 * 258 * NB: In pure implementations of rpc, the caller always waits for a reply 259 * msg. This message is sent when svc_sendreply is called. 260 * Therefore pure service implementations should always call 261 * svc_sendreply even if the function logically returns void; use 262 * xdr.h - xdr_void for the xdr routine. HOWEVER, tcp based rpc allows 263 * for the abuse of pure rpc via batched calling or pipelining. In the 264 * case of a batched call, svc_sendreply should NOT be called since 265 * this would send a return message, which is what batching tries to avoid. 266 * It is the service/protocol writer's responsibility to know which calls are 267 * batched and which are not. Warning: responding to batch calls may 268 * deadlock the caller and server processes! 269 */ 270 271__BEGIN_DECLS 272extern bool_t svc_sendreply __P((SVCXPRT *, xdrproc_t, char *)); 273extern void svcerr_decode __P((SVCXPRT *)); 274extern void svcerr_weakauth __P((SVCXPRT *)); 275extern void svcerr_noproc __P((SVCXPRT *)); 276#ifdef __LP64__ 277extern void svcerr_progvers __P((SVCXPRT *, unsigned int, unsigned int)); 278#else 279extern void svcerr_progvers __P((SVCXPRT *, unsigned long, unsigned long)); 280#endif 281extern void svcerr_auth __P((SVCXPRT *, enum auth_stat)); 282extern void svcerr_noprog __P((SVCXPRT *)); 283extern void svcerr_systemerr __P((SVCXPRT *)); 284__END_DECLS 285 286/* 287 * Lowest level dispatching -OR- who owns this process anyway. 288 * Somebody has to wait for incoming requests and then call the correct 289 * service routine. The routine svc_run does infinite waiting; i.e., 290 * svc_run never returns. 291 * Since another (co-existant) package may wish to selectively wait for 292 * incoming calls or other events outside of the rpc architecture, the 293 * routine svc_getreq is provided. It must be passed readfds, the 294 * "in-place" results of a select system call (see select, section 2). 295 */ 296 297/* 298 * Global keeper of rpc service descriptors in use 299 * dynamic; must be inspected before each call to select 300 */ 301#ifdef FD_SETSIZE 302extern fd_set svc_fdset; 303#define svc_fds svc_fdset.fds_bits[0] /* compatibility */ 304#else 305extern int svc_fds; 306#endif /* def FD_SETSIZE */ 307 308/* 309 * a small program implemented by the svc_rpc implementation itself; 310 * also see clnt.h for protocol numbers. 311 */ 312extern void rpctest_service(); 313 314__BEGIN_DECLS 315extern void svc_getreq __P((int)); 316extern void svc_getreqset __P((fd_set *)); 317extern void svc_run __P((void)); 318__END_DECLS 319 320/* 321 * Socket to use on svcxxx_create call to get default socket 322 */ 323#define RPC_ANYSOCK -1 324 325/* 326 * These are the existing service side transport implementations 327 */ 328 329/* 330 * Memory based rpc for testing and timing. 331 */ 332__BEGIN_DECLS 333extern SVCXPRT *svcraw_create __P((void)); 334__END_DECLS 335 336 337/* 338 * Udp based rpc. 339 */ 340__BEGIN_DECLS 341extern SVCXPRT *svcudp_create __P((int)); 342extern SVCXPRT *svcudp_bufcreate __P((int, unsigned int, unsigned int)); 343__END_DECLS 344 345 346/* 347 * Tcp based rpc. 348 */ 349__BEGIN_DECLS 350extern SVCXPRT *svctcp_create __P((int, unsigned int, unsigned int)); 351__END_DECLS 352 353/* 354 * Any open file descriptor based rpc. 355 */ 356__BEGIN_DECLS 357extern SVCXPRT *svcfd_create __P((int, u_int, u_int)); 358__END_DECLS 359 360#endif /* !_RPC_SVC_H */ 361