tirpc/rpc/svc.h

0001 /*  $NetBSD: svc.h,v 1.17 2000/06/02 22:57:56 fvdl Exp $    */
0002
0003 /*
0004  * Copyright (c) 2009, Sun Microsystems, Inc.
0005  * All rights reserved.
0006  *
0007  * Redistribution and use in source and binary forms, with or without
0008  * modification, are permitted provided that the following conditions are met:
0009  * - Redistributions of source code must retain the above copyright notice,
0010  *   this list of conditions and the following disclaimer.
0011  * - Redistributions in binary form must reproduce the above copyright notice,
0012  *   this list of conditions and the following disclaimer in the documentation
0013  *   and/or other materials provided with the distribution.
0014  * - Neither the name of Sun Microsystems, Inc. nor the names of its
0015  *   contributors may be used to endorse or promote products derived
0016  *   from this software without specific prior written permission.
0017  *
0018  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0019  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0020  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0021  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
0022  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0023  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0024  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0025  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0026  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0027  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0028  * POSSIBILITY OF SUCH DAMAGE.
0029  *
0030  *  from: @(#)svc.h 1.35 88/12/17 SMI
0031  *  from: @(#)svc.h      1.27    94/04/25 SMI
0032  * $FreeBSD: src/include/rpc/svc.h,v 1.24 2003/06/15 10:32:01 mbr Exp $
0033  */
0034
0035 /*
0036  * svc.h, Server-side remote procedure call interface.
0037  *
0038  * Copyright (C) 1986-1993 by Sun Microsystems, Inc.
0039  */
0040
0041 #ifndef _TIRPC_SVC_H
0042 #define _TIRPC_SVC_H
0043
0044 /*
0045  * This interface must manage two items concerning remote procedure calling:
0046  *
0047  * 1) An arbitrary number of transport connections upon which rpc requests
0048  * are received.  The two most notable transports are TCP and UDP;  they are
0049  * created and registered by routines in svc_tcp.c and svc_udp.c, respectively;
0050  * they in turn call xprt_register and xprt_unregister.
0051  *
0052  * 2) An arbitrary number of locally registered services.  Services are
0053  * described by the following four data: program number, version number,
0054  * "service dispatch" function, a transport handle, and a boolean that
0055  * indicates whether or not the exported program should be registered with a
0056  * local binder service;  if true the program's number and version and the
0057  * port number from the transport handle are registered with the binder.
0058  * These data are registered with the rpc svc system via svc_register.
0059  *
0060  * A service's dispatch function is called whenever an rpc request comes in
0061  * on a transport.  The request's program and version numbers must match
0062  * those of the registered service.  The dispatch function is passed two
0063  * parameters, struct svc_req * and SVCXPRT *, defined below.
0064  */
0065
0066 /*
0067  *      Service control requests
0068  */
0069 #define SVCGET_VERSQUIET    1
0070 #define SVCSET_VERSQUIET    2
0071 #define SVCGET_CONNMAXREC   3
0072 #define SVCSET_CONNMAXREC   4
0073
0074 /*
0075  * Operations for rpc_control().
0076  */
0077 #define RPC_SVC_CONNMAXREC_SET  0   /* set max rec size, enable nonblock */
0078 #define RPC_SVC_CONNMAXREC_GET  1
0079
0080 enum xprt_stat {
0081     XPRT_DIED,
0082     XPRT_MOREREQS,
0083     XPRT_IDLE
0084 };
0085
0086 /*
0087  * Server side transport handle
0088  */
0089 typedef struct __rpc_svcxprt {
0090     int     xp_fd;
0091 #define xp_sock     xp_fd
0092     u_short     xp_port;     /* associated port number */
0093     const struct xp_ops {
0094         /* receive incoming requests */
0095         bool_t  (*xp_recv)(struct __rpc_svcxprt *, struct rpc_msg *);
0096         /* get transport status */
0097         enum xprt_stat (*xp_stat)(struct __rpc_svcxprt *);
0098         /* get arguments */
0099         bool_t  (*xp_getargs)(struct __rpc_svcxprt *, xdrproc_t,
0100                 void *);
0101         /* send reply */
0102         bool_t  (*xp_reply)(struct __rpc_svcxprt *, struct rpc_msg *);
0103         /* free mem allocated for args */
0104         bool_t  (*xp_freeargs)(struct __rpc_svcxprt *, xdrproc_t,
0105                 void *);
0106         /* destroy this struct */
0107         void    (*xp_destroy)(struct __rpc_svcxprt *);
0108     } *xp_ops;
0109     int     xp_addrlen;  /* length of remote address */
0110     struct sockaddr_in6 xp_raddr;    /* remote addr. (backward ABI compat) */
0111     /* XXX - fvdl stick this here for ABI backward compat reasons */
0112     const struct xp_ops2 {
0113         /* catch-all function */
0114         bool_t  (*xp_control)(struct __rpc_svcxprt *, const u_int,
0115                 void *);
0116     } *xp_ops2;
0117     char        *xp_tp;      /* transport provider device name */
0118     char        *xp_netid;   /* network token */
0119     struct netbuf   xp_ltaddr;   /* local transport address */
0120     struct netbuf   xp_rtaddr;   /* remote transport address */
0121     struct opaque_auth xp_verf;  /* raw response verifier */
0122     void        *xp_p1;      /* private: for use by svc ops */
0123     void        *xp_p2;      /* private: for use by svc ops */
0124     void        *xp_p3;      /* private: for use by svc lib */
0125     int     xp_type;     /* transport type */
0126 } SVCXPRT;
0127
0128 /*
0129  * Service request
0130  */
0131 struct svc_req {
0132     /* ORDER: compatibility with legacy RPC */
0133     u_int32_t   rq_prog;    /* service program number */
0134     u_int32_t   rq_vers;    /* service protocol version */
0135     u_int32_t   rq_proc;    /* the desired procedure */
0136     struct opaque_auth rq_cred; /* raw creds from the wire */
0137     void        *rq_clntcred;   /* read only cooked cred */
0138     SVCXPRT     *rq_xprt;   /* associated transport */
0139
0140     /* New with TI-RPC */
0141     caddr_t     rq_clntname;    /* read only client name */
0142     caddr_t     rq_svcname; /* read only cooked service cred */
0143 };
0144
0145 /*
0146  *  Approved way of getting address of caller
0147  */
0148 #define svc_getrpccaller(x) (&(x)->xp_rtaddr)
0149
0150 /*
0151  * Operations defined on an SVCXPRT handle
0152  *
0153  * SVCXPRT      *xprt;
0154  * struct rpc_msg   *msg;
0155  * xdrproc_t         xargs;
0156  * void *        argsp;
0157  */
0158 #define SVC_RECV(xprt, msg)             \
0159     (*(xprt)->xp_ops->xp_recv)((xprt), (msg))
0160 #define svc_recv(xprt, msg)             \
0161     (*(xprt)->xp_ops->xp_recv)((xprt), (msg))
0162
0163 #define SVC_STAT(xprt)                  \
0164     (*(xprt)->xp_ops->xp_stat)(xprt)
0165 #define svc_stat(xprt)                  \
0166     (*(xprt)->xp_ops->xp_stat)(xprt)
0167
0168 #define SVC_GETARGS(xprt, xargs, argsp)         \
0169     (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp))
0170 #define svc_getargs(xprt, xargs, argsp)         \
0171     (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp))
0172
0173 #define SVC_REPLY(xprt, msg)                \
0174     (*(xprt)->xp_ops->xp_reply) ((xprt), (msg))
0175 #define svc_reply(xprt, msg)                \
0176     (*(xprt)->xp_ops->xp_reply) ((xprt), (msg))
0177
0178 #define SVC_FREEARGS(xprt, xargs, argsp)        \
0179     (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp))
0180 #define svc_freeargs(xprt, xargs, argsp)        \
0181     (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp))
0182
0183 #define SVC_DESTROY(xprt)               \
0184     (*(xprt)->xp_ops->xp_destroy)(xprt)
0185 #define svc_destroy(xprt)               \
0186     (*(xprt)->xp_ops->xp_destroy)(xprt)
0187
0188 #define SVC_CONTROL(xprt, rq, in)           \
0189     (*(xprt)->xp_ops2->xp_control)((xprt), (rq), (in))
0190
0191 /*
0192  * Service registration
0193  *
0194  * svc_reg(xprt, prog, vers, dispatch, nconf)
0195  *  const SVCXPRT *xprt;
0196  *  const rpcprog_t prog;
0197  *  const rpcvers_t vers;
0198  *  const void (*dispatch)();
0199  *  const struct netconfig *nconf;
0200  */
0201
0202 #ifdef __cplusplus
0203 extern "C" {
0204 #endif
0205 extern bool_t   svc_reg(SVCXPRT *, const rpcprog_t, const rpcvers_t,
0206             void (*)(struct svc_req *, SVCXPRT *),
0207             const struct netconfig *);
0208 #ifdef __cplusplus
0209 }
0210 #endif
0211
0212 /*
0213  * Service un-registration
0214  *
0215  * svc_unreg(prog, vers)
0216  *  const rpcprog_t prog;
0217  *  const rpcvers_t vers;
0218  */
0219
0220 #ifdef __cplusplus
0221 extern "C" {
0222 #endif
0223 extern void svc_unreg(const rpcprog_t, const rpcvers_t);
0224 #ifdef __cplusplus
0225 }
0226 #endif
0227
0228 /*
0229  * Transport registration.
0230  *
0231  * xprt_register(xprt)
0232  *  SVCXPRT *xprt;
0233  */
0234 #ifdef __cplusplus
0235 extern "C" {
0236 #endif
0237 extern void xprt_register(SVCXPRT *);
0238 #ifdef __cplusplus
0239 }
0240 #endif
0241
0242 /*
0243  * Transport un-register
0244  *
0245  * xprt_unregister(xprt)
0246  *  SVCXPRT *xprt;
0247  */
0248 #ifdef __cplusplus
0249 extern "C" {
0250 #endif
0251 extern void xprt_unregister(SVCXPRT *);
0252 #ifdef __cplusplus
0253 }
0254 #endif
0255
0256
0257 /*
0258  * When the service routine is called, it must first check to see if it
0259  * knows about the procedure;  if not, it should call svcerr_noproc
0260  * and return.  If so, it should deserialize its arguments via
0261  * SVC_GETARGS (defined above).  If the deserialization does not work,
0262  * svcerr_decode should be called followed by a return.  Successful
0263  * decoding of the arguments should be followed the execution of the
0264  * procedure's code and a call to svc_sendreply.
0265  *
0266  * Also, if the service refuses to execute the procedure due to too-
0267  * weak authentication parameters, svcerr_weakauth should be called.
0268  * Note: do not confuse access-control failure with weak authentication!
0269  *
0270  * NB: In pure implementations of rpc, the caller always waits for a reply
0271  * msg.  This message is sent when svc_sendreply is called.
0272  * Therefore pure service implementations should always call
0273  * svc_sendreply even if the function logically returns void;  use
0274  * xdr.h - xdr_void for the xdr routine.  HOWEVER, tcp based rpc allows
0275  * for the abuse of pure rpc via batched calling or pipelining.  In the
0276  * case of a batched call, svc_sendreply should NOT be called since
0277  * this would send a return message, which is what batching tries to avoid.
0278  * It is the service/protocol writer's responsibility to know which calls are
0279  * batched and which are not.  Warning: responding to batch calls may
0280  * deadlock the caller and server processes!
0281  */
0282
0283 #ifdef __cplusplus
0284 extern "C" {
0285 #endif
0286 extern bool_t   svc_sendreply(SVCXPRT *, xdrproc_t, void *);
0287 extern void svcerr_decode(SVCXPRT *);
0288 extern void svcerr_weakauth(SVCXPRT *);
0289 extern void svcerr_noproc(SVCXPRT *);
0290 extern void svcerr_progvers(SVCXPRT *, rpcvers_t, rpcvers_t);
0291 extern void svcerr_auth(SVCXPRT *, enum auth_stat);
0292 extern void svcerr_noprog(SVCXPRT *);
0293 extern void svcerr_systemerr(SVCXPRT *);
0294 extern int  rpc_reg(rpcprog_t, rpcvers_t, rpcproc_t,
0295             char *(*)(char *), xdrproc_t, xdrproc_t,
0296             char *);
0297 #ifdef __cplusplus
0298 }
0299 #endif
0300
0301 /*
0302  * Lowest level dispatching -OR- who owns this process anyway.
0303  * Somebody has to wait for incoming requests and then call the correct
0304  * service routine.  The routine svc_run does infinite waiting; i.e.,
0305  * svc_run never returns.
0306  * Since another (co-existant) package may wish to selectively wait for
0307  * incoming calls or other events outside of the rpc architecture, the
0308  * routine svc_getreq is provided.  It must be passed readfds, the
0309  * "in-place" results of a select system call (see select, section 2).
0310  */
0311
0312 /*
0313  * Global keeper of rpc service descriptors in use
0314  * dynamic; must be inspected before each call to select
0315  */
0316 extern int svc_maxfd;
0317 extern fd_set svc_fdset;
0318 #define svc_fds svc_fdset.fds_bits[0]   /* compatibility */
0319 extern struct pollfd *svc_pollfd;
0320 extern int svc_max_pollfd;
0321
0322 /*
0323  * a small program implemented by the svc_rpc implementation itself;
0324  * also see clnt.h for protocol numbers.
0325  */
0326 #ifdef __cplusplus
0327 extern "C" {
0328 #endif
0329 extern void rpctest_service(void);
0330 #ifdef __cplusplus
0331 }
0332 #endif
0333
0334 #ifdef __cplusplus
0335 extern "C" {
0336 #endif
0337 extern void svc_getreq(int);
0338 extern void svc_getreqset(fd_set *);
0339 extern void svc_getreq_common(int);
0340 struct pollfd;
0341 extern void svc_getreq_poll(struct pollfd *, int);
0342
0343 extern void svc_run(void);
0344 extern void svc_exit(void);
0345 #ifdef __cplusplus
0346 }
0347 #endif
0348
0349 /*
0350  * Socket to use on svcxxx_create call to get default socket
0351  */
0352 #define RPC_ANYSOCK -1
0353 #define RPC_ANYFD   RPC_ANYSOCK
0354
0355 /*
0356  * These are the existing service side transport implementations
0357  */
0358
0359 #ifdef __cplusplus
0360 extern "C" {
0361 #endif
0362 /*
0363  * Transport independent svc_create routine.
0364  */
0365 extern int svc_create(void (*)(struct svc_req *, SVCXPRT *),
0366                const rpcprog_t, const rpcvers_t, const char *);
0367 /*
0368  *      void (*dispatch)();             -- dispatch routine
0369  *      const rpcprog_t prognum;        -- program number
0370  *      const rpcvers_t versnum;        -- version number
0371  *      const char *nettype;            -- network type
0372  */
0373
0374
0375 /*
0376  * Generic server creation routine. It takes a netconfig structure
0377  * instead of a nettype.
0378  */
0379
0380 extern SVCXPRT *svc_tp_create(void (*)(struct svc_req *, SVCXPRT *),
0381                    const rpcprog_t, const rpcvers_t,
0382                    const struct netconfig *);
0383         /*
0384          * void (*dispatch)();            -- dispatch routine
0385          * const rpcprog_t prognum;       -- program number
0386          * const rpcvers_t versnum;       -- version number
0387          * const struct netconfig *nconf; -- netconfig structure
0388          */
0389
0390
0391 /*
0392  * Generic TLI create routine
0393  */
0394 extern SVCXPRT *svc_tli_create(const int, const struct netconfig *,
0395                    const struct t_bind *, const u_int,
0396                    const u_int);
0397 /*
0398  *      const int fd;                   -- connection end point
0399  *      const struct netconfig *nconf;  -- netconfig structure for network
0400  *      const struct t_bind *bindaddr;  -- local bind address
0401  *      const u_int sendsz;             -- max sendsize
0402  *      const u_int recvsz;             -- max recvsize
0403  */
0404
0405 /*
0406  * Connectionless and connectionful create routines
0407  */
0408
0409 extern SVCXPRT *svc_vc_create(const int, const u_int, const u_int);
0410 /*
0411  *      const int fd;                           -- open connection end point
0412  *      const u_int sendsize;                   -- max send size
0413  *      const u_int recvsize;                   -- max recv size
0414  */
0415
0416 /*
0417  * Added for compatibility to old rpc 4.0. Obsoleted by svc_vc_create().
0418  */
0419 extern SVCXPRT *svcunix_create(int, u_int, u_int, char *);
0420
0421 extern SVCXPRT *svc_dg_create(const int, const u_int, const u_int);
0422         /*
0423          * const int fd;                                -- open connection
0424          * const u_int sendsize;                        -- max send size
0425          * const u_int recvsize;                        -- max recv size
0426          */
0427
0428
0429 /*
0430  * the routine takes any *open* connection
0431  * descriptor as its first input and is used for open connections.
0432  */
0433 extern SVCXPRT *svc_fd_create(const int, const u_int, const u_int);
0434 /*
0435  *      const int fd;                           -- open connection end point
0436  *      const u_int sendsize;                   -- max send size
0437  *      const u_int recvsize;                   -- max recv size
0438  */
0439
0440 /*
0441  * Added for compatibility to old rpc 4.0. Obsoleted by svc_fd_create().
0442  */
0443 extern SVCXPRT *svcunixfd_create(int, u_int, u_int);
0444
0445 /*
0446  * Memory based rpc (for speed check and testing)
0447  */
0448 extern SVCXPRT *svc_raw_create(void);
0449
0450 /*
0451  * svc_dg_enable_cache() enables the cache on dg transports.
0452  */
0453 int svc_dg_enablecache(SVCXPRT *, const u_int);
0454
0455 int __rpc_get_local_uid(SVCXPRT *_transp, uid_t *_uid);
0456
0457 #ifdef __cplusplus
0458 }
0459 #endif
0460
0461
0462 /* for backward compatibility */
0463 #include <rpc/svc_soc.h>
0464
0465
0466
0467 #endif /* !_TIRPC_SVC_H */