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