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