Return to svc.h CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / sunrpc

Annotation of 43BSD/contrib/sunrpc/svc.h, revision 1.1

1.1     ! root        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: /*      @(#)svc.h 1.2 85/02/08 SMI      */
        !            30: 
        !            31: /*
        !            32:  * svc.h, Server-side remote procedure call interface.
        !            33:  *
        !            34:  * Copyright (C) 1984, Sun Microsystems, Inc.
        !            35:  */
        !            36: 
        !            37: /*
        !            38:  * This interface must manage two items concerning remote procedure calling:
        !            39:  *
        !            40:  * 1) An arbitrary number of transport connections upon which rpc requests
        !            41:  * are received.  The two most notable transports are TCP and UDP;  they are
        !            42:  * created and registered by routines in svc_tcp.c and svc_udp.c, respectively;
        !            43:  * they in turn call xprt_register and xprt_unregister.
        !            44:  *
        !            45:  * 2) An arbitrary number of locally registered services.  Services are
        !            46:  * described by the following four data: program number, version number,
        !            47:  * "service dispatch" function, a transport handle, and a boolean that
        !            48:  * indicates whether or not the exported program should be registered with a
        !            49:  * local binder service;  if true the program's number and version and the
        !            50:  * port number from the transport handle are registered with the binder.
        !            51:  * These data are registered with the rpc svc system via svc_register.
        !            52:  *
        !            53:  * A service's dispatch function is called whenever an rpc request comes in
        !            54:  * on a transport.  The request's program and version numbers must match
        !            55:  * those of the registered service.  The dispatch function is passed two
        !            56:  * parameters, struct svc_req * and SVCXPRT *, defined below.
        !            57:  */
        !            58: 
        !            59: enum xprt_stat {
        !            60:        XPRT_DIED,
        !            61:        XPRT_MOREREQS,
        !            62:        XPRT_IDLE
        !            63: };
        !            64: 
        !            65: /*
        !            66:  * Server side transport handle
        !            67:  */
        !            68: typedef struct {
        !            69:        int             xp_sock;
        !            70:        u_short         xp_port;         /* associated port number */
        !            71:        struct xp_ops {
        !            72:            bool_t      (*xp_recv)();    /* receive incomming requests */
        !            73:            enum xprt_stat (*xp_stat)(); /* get transport status */
        !            74:            bool_t      (*xp_getargs)(); /* get arguments */
        !            75:            bool_t      (*xp_reply)();   /* send reply */
        !            76:            bool_t      (*xp_freeargs)();/* free mem allocated for args */
        !            77:            void        (*xp_destroy)(); /* destroy this struct */
        !            78:        } *xp_ops;
        !            79:        int             xp_addrlen;      /* length of remote address */
        !            80:        struct sockaddr_in xp_raddr;     /* remote address */
        !            81:        struct opaque_auth xp_verf;      /* raw response verifier */
        !            82:        caddr_t         xp_p1;           /* private */
        !            83:        caddr_t         xp_p2;           /* private */
        !            84: } SVCXPRT;
        !            85: 
        !            86: /*
        !            87:  *  Approved way of getting address of caller
        !            88:  */
        !            89: #define svc_getcaller(x) (&(x)->xp_raddr)
        !            90: 
        !            91: /*
        !            92:  * Operations defined on an SVCXPRT handle
        !            93:  *
        !            94:  * SVCXPRT             *xprt;
        !            95:  * struct rpc_msg      *msg;
        !            96:  * xdrproc_t            xargs;
        !            97:  * caddr_t              argsp;
        !            98:  */
        !            99: #define SVC_RECV(xprt, msg)                            \
        !           100:        (*(xprt)->xp_ops->xp_recv)((xprt), (msg))
        !           101: #define svc_recv(xprt, msg)                            \
        !           102:        (*(xprt)->xp_ops->xp_recv)((xprt), (msg))
        !           103: 
        !           104: #define SVC_STAT(xprt)                                 \
        !           105:        (*(xprt)->xp_ops->xp_stat)(xprt)
        !           106: #define svc_stat(xprt)                                 \
        !           107:        (*(xprt)->xp_ops->xp_stat)(xprt)
        !           108: 
        !           109: #define SVC_GETARGS(xprt, xargs, argsp)                        \
        !           110:        (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp))
        !           111: #define svc_getargs(xprt, xargs, argsp)                        \
        !           112:        (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp))
        !           113: 
        !           114: #define SVC_REPLY(xprt, msg)                           \
        !           115:        (*(xprt)->xp_ops->xp_reply) ((xprt), (msg))
        !           116: #define svc_reply(xprt, msg)                           \
        !           117:        (*(xprt)->xp_ops->xp_reply) ((xprt), (msg))
        !           118: 
        !           119: #define SVC_FREEARGS(xprt, xargs, argsp)               \
        !           120:        (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp))
        !           121: #define svc_freeargs(xprt, xargs, argsp)               \
        !           122:        (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp))
        !           123: 
        !           124: #define SVC_DESTROY(xprt)                              \
        !           125:        (*(xprt)->xp_ops->xp_destroy)(xprt)
        !           126: #define svc_destroy(xprt)                              \
        !           127:        (*(xprt)->xp_ops->xp_destroy)(xprt)
        !           128: 
        !           129: 
        !           130: /*
        !           131:  * Service request
        !           132:  */
        !           133: struct svc_req {
        !           134:        u_long          rq_prog;        /* service program number */
        !           135:        u_long          rq_vers;        /* service protocol version */
        !           136:        u_long          rq_proc;        /* the desired procedure */
        !           137:        struct opaque_auth rq_cred;     /* raw creds from the wire */
        !           138:        caddr_t         rq_clntcred;    /* read only cooked cred */
        !           139:        SVCXPRT *rq_xprt;               /* associated transport */
        !           140: };
        !           141: 
        !           142: 
        !           143: /*
        !           144:  * Service registration
        !           145:  *
        !           146:  * svc_register(xprt, prog, vers, dispatch, protocol)
        !           147:  *     SVCXPRT *xprt;
        !           148:  *     u_long prog;
        !           149:  *     u_long vers;
        !           150:  *     void (*dispatch)();
        !           151:  *     int protocol;  /* like TCP or UDP, zero means do not register 
        !           152:  */
        !           153: extern bool_t  svc_register();
        !           154: 
        !           155: /*
        !           156:  * Service un-registration
        !           157:  *
        !           158:  * svc_unregister(prog, vers)
        !           159:  *     u_long prog;
        !           160:  *     u_long vers;
        !           161:  */
        !           162: extern void    svc_unregister();
        !           163: 
        !           164: /*
        !           165:  * Transport registration.
        !           166:  *
        !           167:  * xprt_register(xprt)
        !           168:  *     SVCXPRT *xprt;
        !           169:  */
        !           170: extern void    xprt_register();
        !           171: 
        !           172: /*
        !           173:  * Transport un-register
        !           174:  *
        !           175:  * xprt_unregister(xprt)
        !           176:  *     SVCXPRT *xprt;
        !           177:  */
        !           178: extern void    xprt_unregister();
        !           179: 
        !           180: 
        !           181: /*
        !           182:  * When the service routine is called, it must first check to see if it
        !           183:  * knows about the procedure;  if not, it should call svcerr_noproc
        !           184:  * and return.  If so, it should deserialize its arguments via 
        !           185:  * SVC_GETARGS (defined above).  If the deserialization does not work,
        !           186:  * svcerr_decode should be called followed by a return.  Successful
        !           187:  * decoding of the arguments should be followed the execution of the
        !           188:  * procedure's code and a call to svc_sendreply.
        !           189:  *
        !           190:  * Also, if the service refuses to execute the procedure due to too-
        !           191:  * weak authentication parameters, svcerr_weakauth should be called.
        !           192:  * Note: do not confuse access-control failure with weak authentication!
        !           193:  *
        !           194:  * NB: In pure implementations of rpc, the caller always waits for a reply
        !           195:  * msg.  This message is sent when svc_sendreply is called.  
        !           196:  * Therefore pure service implementations should always call
        !           197:  * svc_sendreply even if the function logically returns void;  use
        !           198:  * xdr.h - xdr_void for the xdr routine.  HOWEVER, tcp based rpc allows
        !           199:  * for the abuse of pure rpc via batched calling or pipelining.  In the
        !           200:  * case of a batched call, svc_sendreply should NOT be called since
        !           201:  * this would send a return message, which is what batching tries to avoid.
        !           202:  * It is the service/protocol writer's responsibility to know which calls are
        !           203:  * batched and which are not.  Warning: responding to batch calls may
        !           204:  * deadlock the caller and server processes!
        !           205:  */
        !           206: 
        !           207: extern bool_t  svc_sendreply();
        !           208: extern void    svcerr_noproc();
        !           209: extern void    svcerr_decode();
        !           210: extern void    svcerr_weakauth();
        !           211: 
        !           212: /*
        !           213:  * Lowest level dispatching -OR- who owns this process anyway.
        !           214:  * Somebody has to wait for incoming requests and then call the correct
        !           215:  * service routine.  The routine svc_run does infinite waiting; i.e.,
        !           216:  * svc_run never returns.
        !           217:  * Since another (co-existant) package may wish to selectively wait for
        !           218:  * incoming calls or other events outside of the rpc architecture, the
        !           219:  * routine svc_getreq is provided.  It must be passed readfds, the
        !           220:  * "in-place" results of a select system call (see select, section 2).
        !           221:  */
        !           222: 
        !           223: /* dynamic; must be inspected before each call to select */
        !           224: extern int svc_fds;
        !           225: 
        !           226: extern void    svc_getreq();
        !           227: extern void    svc_run();  /* never returns */
        !           228: 
        !           229: /*
        !           230:  * a small program implemented by the svc_rpc implementation itself;
        !           231:  * also see clnt.h for protocol numbers.
        !           232:  */
        !           233: extern void rpctest_service();
        !           234: 
        !           235: /*
        !           236:  * Socket to use on svcxxx_create call to get default socket
        !           237:  */
        !           238: #define        RPC_ANYSOCK     -1
        !           239: 
        !           240: /*
        !           241:  * These are the existing service side transport implementations
        !           242:  */
        !           243: 
        !           244: /*
        !           245:  * Memory based rpc for testing and timing.
        !           246:  */
        !           247: extern SVCXPRT *svcraw_create();
        !           248: 
        !           249: /*
        !           250:  * Udp based rpc.
        !           251:  */
        !           252: extern SVCXPRT *svcudp_create();
        !           253: 
        !           254: /*
        !           255:  * Tcp based rpc.
        !           256:  */
        !           257: extern SVCXPRT *svctcp_create();
        !           258: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.