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