home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.2 (Developer) / NS_dev_3.2.iso / NextDeveloper / Headers / bsd / rpc / clnt.h < prev    next >
C/C++ Source or Header  |  1993-04-13  |  7KB  |  310 lines
  1. /*    @(#)clnt.h    1.1 88/03/04 4.0NFSSRC SMI    */
  2.  
  3. /* 
  4.  * Copyright (c) 1988 by Sun Microsystems, Inc.
  5.  *  1.31 88/02/08 SMI  
  6.  */
  7.  
  8.  
  9. /*
  10.  * clnt.h - Client side remote procedure call interface.
  11.  */
  12.  
  13. #ifndef _CLNT_
  14. #define _CLNT_
  15.  
  16. #ifdef RPC_SUCCESS
  17. /*
  18.  * RPC_SUCCESS is also defined in <sys/message.h>
  19.  */
  20. #undef RPC_SUCCESS
  21. #endif RPC_SUCCESS
  22.  
  23. /*
  24.  * Rpc calls return an enum clnt_stat.  This should be looked at more,
  25.  * since each implementation is required to live with this (implementation
  26.  * independent) list of errors.
  27.  */
  28. enum clnt_stat {
  29.     RPC_SUCCESS=0,            /* call succeeded */
  30.     /*
  31.      * local errors
  32.      */
  33.     RPC_CANTENCODEARGS=1,        /* can't encode arguments */
  34.     RPC_CANTDECODERES=2,        /* can't decode results */
  35.     RPC_CANTSEND=3,            /* failure in sending call */
  36.     RPC_CANTRECV=4,            /* failure in receiving result */
  37.     RPC_TIMEDOUT=5,            /* call timed out */
  38.     RPC_INTR=18,                    /* call interrupted */
  39.     /*
  40.      * remote errors
  41.      */
  42.     RPC_VERSMISMATCH=6,        /* rpc versions not compatible */
  43.     RPC_AUTHERROR=7,        /* authentication error */
  44.     RPC_PROGUNAVAIL=8,        /* program not available */
  45.     RPC_PROGVERSMISMATCH=9,        /* program version mismatched */
  46.     RPC_PROCUNAVAIL=10,        /* procedure unavailable */
  47.     RPC_CANTDECODEARGS=11,        /* decode arguments error */
  48.     RPC_SYSTEMERROR=12,        /* generic "other problem" */
  49.  
  50.     /*
  51.      * callrpc & clnt_create errors
  52.      */
  53.     RPC_UNKNOWNHOST=13,        /* unknown host name */
  54.     RPC_UNKNOWNPROTO=17,        /* unkown protocol */
  55.  
  56.     /*
  57.      * _ create errors
  58.      */
  59.     RPC_PMAPFAILURE=14,        /* the pmapper failed in its call */
  60.     RPC_PROGNOTREGISTERED=15,    /* remote program is not registered */
  61.     /*
  62.      * unspecified error
  63.      */
  64.     RPC_FAILED=16
  65. };
  66.  
  67.  
  68. /*
  69.  * Error info.
  70.  */
  71. struct rpc_err {
  72.     enum clnt_stat re_status;
  73.     union {
  74.         int RE_errno;        /* realated system error */
  75.         enum auth_stat RE_why;    /* why the auth error occurred */
  76.         struct {
  77.             u_long low;    /* lowest verion supported */
  78.             u_long high;    /* highest verion supported */
  79.         } RE_vers;
  80.         struct {        /* maybe meaningful if RPC_FAILED */
  81.             long s1;
  82.             long s2;
  83.         } RE_lb;        /* life boot & debugging only */
  84.     } ru;
  85. #define    re_errno    ru.RE_errno
  86. #define    re_why        ru.RE_why
  87. #define    re_vers        ru.RE_vers
  88. #define    re_lb        ru.RE_lb
  89. };
  90.  
  91.  
  92. /*
  93.  * Client rpc handle.
  94.  * Created by individual implementations, see e.g. rpc_udp.c.
  95.  * Client is responsible for initializing auth, see e.g. auth_none.c.
  96.  */
  97. typedef struct {
  98.     AUTH    *cl_auth;            /* authenticator */
  99.     struct clnt_ops {
  100.         enum clnt_stat    (*cl_call)();    /* call remote procedure */
  101.         void        (*cl_abort)();    /* abort a call */
  102.         void        (*cl_geterr)();    /* get specific error code */
  103.         bool_t        (*cl_freeres)(); /* frees results */
  104.         void        (*cl_destroy)();/* destroy this structure */
  105.         bool_t          (*cl_control)();/* the ioctl() of rpc */
  106.     } *cl_ops;
  107.     caddr_t            cl_private;    /* private stuff */
  108. } CLIENT;
  109.  
  110.  
  111. /*
  112.  * client side rpc interface ops
  113.  *
  114.  * Parameter types are:
  115.  *
  116.  */
  117.  
  118. /*
  119.  * enum clnt_stat
  120.  * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
  121.  *     CLIENT *rh;
  122.  *    u_long proc;
  123.  *    xdrproc_t xargs;
  124.  *    caddr_t argsp;
  125.  *    xdrproc_t xres;
  126.  *    caddr_t resp;
  127.  *    struct timeval timeout;
  128.  */
  129. #define    CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs)    \
  130.     ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
  131. #define    clnt_call(rh, proc, xargs, argsp, xres, resp, secs)    \
  132.     ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
  133.  
  134. /*
  135.  * void
  136.  * CLNT_ABORT(rh);
  137.  *     CLIENT *rh;
  138.  */
  139. #define    CLNT_ABORT(rh)    ((*(rh)->cl_ops->cl_abort)(rh))
  140. #define    clnt_abort(rh)    ((*(rh)->cl_ops->cl_abort)(rh))
  141.  
  142. /*
  143.  * struct rpc_err
  144.  * CLNT_GETERR(rh);
  145.  *     CLIENT *rh;
  146.  */
  147. #define    CLNT_GETERR(rh,errp)    ((*(rh)->cl_ops->cl_geterr)(rh, errp))
  148. #define    clnt_geterr(rh,errp)    ((*(rh)->cl_ops->cl_geterr)(rh, errp))
  149.  
  150.  
  151. /*
  152.  * bool_t
  153.  * CLNT_FREERES(rh, xres, resp);
  154.  *     CLIENT *rh;
  155.  *    xdrproc_t xres;
  156.  *    caddr_t resp;
  157.  */
  158. #define    CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
  159. #define    clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
  160.  
  161. /*
  162.  * bool_t
  163.  * CLNT_CONTROL(cl, request, info)
  164.  *      CLIENT *cl;
  165.  *      u_int request;
  166.  *      char *info;
  167.  */
  168. #define    CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
  169. #define    clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
  170.  
  171. /*
  172.  * control operations that apply to both udp and tcp transports
  173.  */
  174. #define CLSET_TIMEOUT       1   /* set timeout (timeval) */
  175. #define CLGET_TIMEOUT       2   /* get timeout (timeval) */
  176. #define CLGET_SERVER_ADDR   3   /* get server's address (sockaddr) */
  177. #define CLGET_SOCKET        6   /* get client's socket (int) */
  178. /*
  179.  * udp only control operations
  180.  */
  181. #define CLSET_RETRY_TIMEOUT 4   /* set retry timeout (timeval) */
  182. #define CLGET_RETRY_TIMEOUT 5   /* get retry timeout (timeval) */
  183.  
  184. /*
  185.  * void
  186.  * CLNT_DESTROY(rh);
  187.  *     CLIENT *rh;
  188.  */
  189. #define    CLNT_DESTROY(rh)    ((*(rh)->cl_ops->cl_destroy)(rh))
  190. #define    clnt_destroy(rh)    ((*(rh)->cl_ops->cl_destroy)(rh))
  191.  
  192.  
  193. /*
  194.  * RPCTEST is a test program which is accessable on every rpc
  195.  * transport/port.  It is used for testing, performance evaluation,
  196.  * and network administration.
  197.  */
  198.  
  199. #define RPCTEST_PROGRAM        ((u_long)1)
  200. #define RPCTEST_VERSION        ((u_long)1)
  201. #define RPCTEST_NULL_PROC    ((u_long)2)
  202. #define RPCTEST_NULL_BATCH_PROC    ((u_long)3)
  203.  
  204. /*
  205.  * By convention, procedure 0 takes null arguments and returns them
  206.  */
  207.  
  208. #define NULLPROC ((u_long)0)
  209.  
  210. /*
  211.  * Below are the client handle creation routines for the various
  212.  * implementations of client side rpc.  They can return NULL if a 
  213.  * creation failure occurs.
  214.  */
  215.  
  216. /*
  217.  * Memory based rpc (for speed check and testing)
  218.  * CLIENT *
  219.  * clntraw_create(prog, vers)
  220.  *    u_long prog;
  221.  *    u_long vers;
  222.  */
  223. extern CLIENT *clntraw_create();
  224.  
  225.  
  226. /*
  227.  * Generic client creation routine. Supported protocols are "udp" and "tcp"
  228.  */
  229. extern CLIENT *
  230. clnt_create(
  231.     char *host,     /* hostname */
  232.     u_long prog,    /* program number */
  233.     u_long vers,    /* version number */
  234.     char *prot);    /* protocol */
  235.  
  236. /*
  237.  * TCP based rpc
  238.  */
  239. extern CLIENT *
  240. clnttcp_create(
  241.     struct sockaddr_in *raddr,
  242.     u_long prog,
  243.     u_long version,
  244.     register int *sockp,
  245.     u_int sendsz,
  246.     u_int recvsz);
  247.  
  248.  
  249. /*
  250.  * UDP based rpc.
  251.  */
  252. extern CLIENT *
  253. clntudp_create(
  254.     struct sockaddr_in *raddr,
  255.     u_long program,
  256.     u_long version,
  257.     struct timeval wait,
  258.     int *sockp);
  259.  
  260. /*
  261.  * Same as above, but you specify max packet sizes.
  262.  */
  263. extern CLIENT *
  264. clntudp_bufcreate(
  265.     struct sockaddr_in *raddr,
  266.     u_long program,
  267.     u_long version,
  268.     struct timeval wait,
  269.     int *sockp,
  270.     u_int sendsz,
  271.     u_int recvsz);
  272.  
  273. /*
  274.  * Print why creation failed
  275.  */
  276. extern void clnt_pcreateerror(const char *msg);    /* stderr */
  277. extern char *clnt_spcreateerror(const char *msg);    /* string */
  278.  
  279. /*
  280.  * Like clnt_perror(), but is more verbose in its output
  281.  */ 
  282. extern void clnt_perrno(enum clnt_stat num);        /* stderr */
  283.  
  284. /*
  285.  * Print an English error message, given the client error code
  286.  */
  287. extern void clnt_perror(CLIENT *clnt, const char *msg);     /* stderr */
  288. extern char *clnt_sperror(CLIENT *clnt, const char *msg);    /* string */
  289. extern void clnt_syslog(CLIENT *clnt, const char *msg);
  290.  
  291. /* 
  292.  * If a creation fails, the following allows the user to figure out why.
  293.  */
  294. struct rpc_createerr {
  295.     enum clnt_stat cf_stat;
  296.     struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
  297. };
  298.  
  299. extern struct rpc_createerr rpc_createerr;
  300.  
  301. /*
  302.  * Copy error message to buffer.
  303.  */
  304. extern char *clnt_sperrno(enum clnt_stat num);        /* string */
  305.  
  306. #define UDPMSGSIZE    8800    /* rpc imposed limit on udp msg size */
  307. #define RPCSMALLMSGSIZE    400    /* a more reasonable packet size */
  308.  
  309. #endif /*!_CLNT_*/
  310.