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