home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 15 / 15.iso / s / s053 / 8.ddi / usr / include / rpc / clnt.h < prev    next >
Encoding:
C/C++ Source or Header  |  1990-12-08  |  11.3 KB  |  422 lines
  1. /*    Copyright (c) 1990 UNIX System Laboratories, Inc.    */
  2. /*    Copyright (c) 1984, 1986, 1987, 1988, 1989, 1990 AT&T    */
  3. /*      All Rights Reserved      */
  4.  
  5. /*    THIS IS UNPUBLISHED PROPRIETARY SOURCE CODE OF         */
  6. /*    UNIX System Laboratories, Inc.                         */
  7. /*    The copyright notice above does not evidence any       */
  8. /*    actual or intended publication of such source code.    */
  9.  
  10. #ident    "@(#)/usr/include/rpc/clnt.h.sl 1.1 4.0 12/08/90 40319 AT&T-USL"
  11.  
  12. /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  13. *    PROPRIETARY NOTICE (Combined)
  14. *
  15. * This source code is unpublished proprietary information
  16. * constituting, or derived under license from AT&T's UNIX(r) System V.
  17. * In addition, portions of such source code were derived from Berkeley
  18. * 4.3 BSD under license from the Regents of the University of
  19. * California.
  20. *
  21. *
  22. *
  23. *    Copyright Notice 
  24. *
  25. * Notice of copyright on this source code product does not indicate 
  26. *  publication.
  27. *
  28. *    (c) 1986,1987,1988.1989  Sun Microsystems, Inc
  29. *    (c) 1983,1984,1985,1986,1987,1988,1989  AT&T.
  30. *          All rights reserved.
  31. */
  32.  
  33. /*
  34.  * clnt.h - Client side remote procedure call interface.
  35.  *
  36.  */
  37.  
  38. #ifndef _RPC_CLNT_H
  39. #define _RPC_CLNT_H
  40.  
  41. #include <rpc/rpc_com.h>
  42. /*
  43.  * rpc calls return an enum clnt_stat.  This should be looked at more,
  44.  * since each implementation is required to live with this (implementation
  45.  * independent) list of errors.
  46.  */
  47. enum clnt_stat {
  48.     RPC_SUCCESS=0,            /* call succeeded */
  49.     /*
  50.      * local errors
  51.      */
  52.     RPC_CANTENCODEARGS=1,        /* can't encode arguments */
  53.     RPC_CANTDECODERES=2,        /* can't decode results */
  54.     RPC_CANTSEND=3,            /* failure in sending call */
  55.     RPC_CANTRECV=4,            /* failure in receiving result */
  56.     RPC_TIMEDOUT=5,            /* call timed out */
  57.     RPC_INTR=18,            /* call interrupted */
  58.     RPC_UDERROR=23,            /* recv got uderr indication */
  59.     /*
  60.      * remote errors
  61.      */
  62.     RPC_VERSMISMATCH=6,        /* rpc versions not compatible */
  63.     RPC_AUTHERROR=7,        /* authentication error */
  64.     RPC_PROGUNAVAIL=8,        /* program not available */
  65.     RPC_PROGVERSMISMATCH=9,        /* program version mismatched */
  66.     RPC_PROCUNAVAIL=10,        /* procedure unavailable */
  67.     RPC_CANTDECODEARGS=11,        /* decode arguments error */
  68.     RPC_SYSTEMERROR=12,        /* generic "other problem" */
  69.  
  70.     /*
  71.      * rpc_call & clnt_create errors
  72.      */
  73.     RPC_UNKNOWNHOST=13,        /* unknown host name */
  74.     RPC_UNKNOWNPROTO=17,        /* unknown protocol */
  75.     RPC_UNKNOWNADDR=19,        /* Remote address unknown */
  76.     RPC_NOBROADCAST=21,        /* Broadcasting not supported */
  77.  
  78.     /*
  79.      * rpcbind errors
  80.      */
  81.     RPC_RPCBFAILURE=14,        /* the pmapper failed in its call */
  82. #define RPC_PMAPFAILURE RPC_RPCBFAILURE
  83.     RPC_PROGNOTREGISTERED=15,    /* remote program is not registered */
  84.     RPC_N2AXLATEFAILURE=22,        /* Name to address translation failed */
  85.     /*
  86.      * Misc error in the TLI library
  87.      */
  88.     RPC_TLIERROR=20,
  89.     /*
  90.      * unspecified error
  91.      */
  92.     RPC_FAILED=16
  93. };
  94.  
  95.  
  96. /*
  97.  * Error info.
  98.  */
  99. struct rpc_err {
  100.     enum clnt_stat re_status;
  101.     union {
  102.         struct {
  103.             int errno;    /* related system error */
  104.             int t_errno;    /* related tli error number */
  105.         } RE_err;
  106.         enum auth_stat RE_why;    /* why the auth error occurred */
  107.         struct {
  108.             u_long low;    /* lowest verion supported */
  109.             u_long high;    /* highest verion supported */
  110.         } RE_vers;
  111.         struct {        /* maybe meaningful if RPC_FAILED */
  112.             long s1;
  113.             long s2;
  114.         } RE_lb;        /* life boot & debugging only */
  115.     } ru;
  116. #define    re_errno    ru.RE_err.errno
  117. #define    re_terrno    ru.RE_err.t_errno
  118. #define    re_why        ru.RE_why
  119. #define    re_vers        ru.RE_vers
  120. #define    re_lb        ru.RE_lb
  121. };
  122.  
  123.  
  124. /*
  125.  * Client rpc handle.
  126.  * Created by individual implementations
  127.  * Client is responsible for initializing auth, see e.g. auth_none.c.
  128.  */
  129. typedef struct {
  130.     AUTH    *cl_auth;            /* authenticator */
  131.     struct clnt_ops {
  132.         enum clnt_stat    (*cl_call)();    /* call remote procedure */
  133.         void        (*cl_abort)();    /* abort a call */
  134.         void        (*cl_geterr)();    /* get specific error code */
  135.         bool_t        (*cl_freeres)();/* frees results */
  136.         void        (*cl_destroy)();/* destroy this structure */
  137.         bool_t        (*cl_control)();/* the ioctl() of rpc */
  138.     } *cl_ops;
  139.     caddr_t            cl_private;    /* private stuff */
  140. #ifndef _KERNEL
  141.     char            *cl_netid;    /* network token */
  142.     char            *cl_tp;        /* device name */
  143. #endif
  144. } CLIENT;
  145.  
  146.  
  147. /*
  148.  * Timers used for the pseudo-transport protocol when using datagrams
  149.  */
  150. struct rpc_timers {
  151.     u_short        rt_srtt;    /* smoothed round-trip time */
  152.     u_short        rt_deviate;    /* estimated deviation */
  153.     u_long        rt_rtxcur;    /* current (backed-off) rto */
  154. };
  155.  
  156. /*
  157.  * Feedback values used for possible congestion and rate control
  158.  */
  159. #define    FEEDBACK_REXMIT1    1    /* first retransmit */
  160. #define    FEEDBACK_OK        2    /* no retransmits */
  161.  
  162. #define    RPCSMALLMSGSIZE    400    /* a more reasonable packet size */
  163.  
  164. #define    KNC_STRSIZE    128    /* maximum length of knetconfig strings */
  165. struct knetconfig {
  166.     unsigned long    knc_semantics;    /* token name */
  167.     char        *knc_protofmly;    /* protocol family */
  168.     char        *knc_proto;    /* protocol */
  169.     dev_t        knc_rdev;    /* device id */
  170.     unsigned long    knc_unused[8];
  171. };
  172.  
  173. /*
  174.  * client side rpc interface ops
  175.  */
  176.  
  177. /*
  178.  * enum clnt_stat
  179.  * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
  180.  *     CLIENT *rh;
  181.  *    u_long proc;
  182.  *    xdrproc_t xargs;
  183.  *    caddr_t argsp;
  184.  *    xdrproc_t xres;
  185.  *    caddr_t resp;
  186.  *    struct timeval timeout;
  187.  */
  188. #define    CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs)    \
  189.     ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
  190. #define    clnt_call(rh, proc, xargs, argsp, xres, resp, secs)    \
  191.     ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
  192.  
  193. /*
  194.  * void
  195.  * CLNT_ABORT(rh);
  196.  *     CLIENT *rh;
  197.  */
  198. #define    CLNT_ABORT(rh)    ((*(rh)->cl_ops->cl_abort)(rh))
  199. #define    clnt_abort(rh)    ((*(rh)->cl_ops->cl_abort)(rh))
  200.  
  201. /*
  202.  * struct rpc_err
  203.  * CLNT_GETERR(rh);
  204.  *     CLIENT *rh;
  205.  */
  206. #define    CLNT_GETERR(rh, errp)    ((*(rh)->cl_ops->cl_geterr)(rh, errp))
  207. #define    clnt_geterr(rh, errp)    ((*(rh)->cl_ops->cl_geterr)(rh, errp))
  208.  
  209. /*
  210.  * bool_t
  211.  * CLNT_FREERES(rh, xres, resp);
  212.  *     CLIENT *rh;
  213.  *    xdrproc_t xres;
  214.  *    caddr_t resp;
  215.  */
  216. #define    CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
  217. #define    clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
  218.  
  219. /*
  220.  * bool_t
  221.  * CLNT_CONTROL(cl, request, info)
  222.  *    CLIENT *cl;
  223.  *    u_int request;
  224.  *    char *info;
  225.  */
  226. #define    CLNT_CONTROL(cl, rq, in) ((*(cl)->cl_ops->cl_control)(cl, rq, in))
  227. #define    clnt_control(cl, rq, in) ((*(cl)->cl_ops->cl_control)(cl, rq, in))
  228.  
  229.  
  230. /*
  231.  * control operations that apply to all transports
  232.  */
  233. #define    CLSET_TIMEOUT        1    /* set timeout (timeval) */
  234. #define    CLGET_TIMEOUT        2    /* get timeout (timeval) */
  235. #define    CLGET_SERVER_ADDR    3    /* get server's address (sockaddr) */
  236. #define    CLGET_FD        6    /* get connections file descriptor */
  237. #define    CLGET_SVC_ADDR        7    /* get server's address (netbuf) */
  238. #define    CLSET_FD_CLOSE        8    /* close fd while clnt_destroy */
  239. #define    CLSET_FD_NCLOSE        9    /* Do not close fd while clnt_destroy */
  240. /*
  241.  * Connectionless only control operations
  242.  */
  243. #define    CLSET_RETRY_TIMEOUT 4   /* set retry timeout (timeval) */
  244. #define    CLGET_RETRY_TIMEOUT 5   /* get retry timeout (timeval) */
  245.  
  246. /*
  247.  * void
  248.  * CLNT_DESTROY(rh);
  249.  *     CLIENT *rh;
  250.  */
  251. #define    CLNT_DESTROY(rh)    ((*(rh)->cl_ops->cl_destroy)(rh))
  252. #define    clnt_destroy(rh)    ((*(rh)->cl_ops->cl_destroy)(rh))
  253.  
  254.  
  255. /*
  256.  * RPCTEST is a test program which is accessable on every rpc
  257.  * transport/port.  It is used for testing, performance evaluation,
  258.  * and network administration.
  259.  */
  260.  
  261. #define    RPCTEST_PROGRAM        ((u_long)1)
  262. #define    RPCTEST_VERSION        ((u_long)1)
  263. #define    RPCTEST_NULL_PROC    ((u_long)2)
  264. #define    RPCTEST_NULL_BATCH_PROC    ((u_long)3)
  265.  
  266. /*
  267.  * By convention, procedure 0 takes null arguments and returns them
  268.  */
  269.  
  270. #define    NULLPROC ((u_long)0)
  271.  
  272. /*
  273.  * Below are the client handle creation routines for the various
  274.  * implementations of client side rpc.  They can return NULL if a
  275.  * creation failure occurs.
  276.  */
  277.  
  278. #ifndef _KERNEL
  279. /*
  280.  * Generic client creation routine. Supported protocols are which belong
  281.  * to the nettype name space
  282.  */
  283. extern CLIENT *
  284. clnt_create(/*hostname, prog, vers, nettype*/); /*
  285.     char *hostname;            -- hostname
  286.     u_long prog;            -- program number
  287.     u_long vers;            -- version number
  288.     char *nettype;            -- network type
  289. */
  290.  
  291. /*
  292.  * Generic client creation routine. It takes a netconfig structure
  293.  * instead of nettype
  294.  */
  295. extern CLIENT *
  296. clnt_tp_create(/*hostname, prog, vers, netconf*/); /*
  297.     char *hostname;            -- hostname
  298.     u_long prog;            -- program number
  299.     u_long vers;            -- version number
  300.     struct netconfig *netconf;     -- network config structure
  301. */
  302.  
  303. /*
  304.  * Generic TLI create routine
  305.  */
  306. extern CLIENT *
  307. clnt_tli_create(/*fd, netconf, svcaddr, prog, vers, sendsz, recvsz*/); /*
  308.     register int fd;        -- fd
  309.     struct netconfig *nconf;    -- netconfig structure
  310.     struct netbuf *svcaddr;        -- servers address
  311.     u_long prog;            -- program number
  312.     u_long vers;            -- version number
  313.     u_int sendsz;            -- send size
  314.     u_int recvsz;            -- recv size
  315. */
  316.  
  317. /*
  318.  * Low level clnt create routine for connectionful transports, e.g. tcp.
  319.  */
  320. extern CLIENT *
  321. clnt_vc_create(/*fd, svcaddr, prog, vers, sendsz, recvsz*/); /*
  322.     int fd;                -- open file descriptor
  323.     struct netbuf *svcaddr;        -- servers address
  324.     u_long prog;            -- program number
  325.     u_long vers;            -- version number
  326.     u_int sendsz;            -- buffer recv size
  327.     u_int recvsz;            -- buffer send size
  328. */
  329.  
  330. /*
  331.  * Low level clnt create routine for connectionless transports, e.g. udp.
  332.  */
  333. extern CLIENT *
  334. clnt_dg_create(/*fd, svcaddr, program, version, sendsz, recvsz*/); /*
  335.     int fd;                -- open file descriptor
  336.     struct netbuf *svcaddr;        -- servers address
  337.     u_long program;            -- program number
  338.     u_long version;            -- version number
  339.     u_int sendsz;            -- buffer recv size
  340.     u_int recvsz;            -- buffer send size
  341. */
  342.  
  343. /*
  344.  * Memory based rpc (for speed check and testing)
  345.  * CLIENT *
  346.  * clnt_raw_create(prog, vers)
  347.  *    u_long prog;            -- program number
  348.  *    u_long vers;            -- version number
  349.  */
  350. extern CLIENT *clnt_raw_create();
  351.  
  352.  
  353. /*
  354.  * Print why creation failed
  355.  */
  356. void clnt_pcreateerror(/* char *msg */);    /* stderr */
  357. char *clnt_spcreateerror(/* char *msg */);    /* string */
  358.  
  359. /*
  360.  * Like clnt_perror(), but is more verbose in its output
  361.  */
  362. void clnt_perrno(/* enum clnt_stat num */);    /* stderr */
  363.  
  364. /*
  365.  * Print an error message, given the client error code
  366.  */
  367. void clnt_perror(/* CLIENT *clnt, char *msg */);     /* stderr */
  368. char *clnt_sperror(/* CLIENT *clnt, char *msg */);    /* string */
  369.  
  370. /*
  371.  * If a creation fails, the following allows the user to figure out why.
  372.  */
  373. struct rpc_createerr {
  374.     enum clnt_stat cf_stat;
  375.     struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
  376. };
  377.  
  378. extern struct rpc_createerr rpc_createerr;
  379.  
  380. /*
  381.  * The simplified interface:
  382.  * enum clnt_stat
  383.  * rpc_call(host, prognum, versnum, procnum, inproc, in, outproc, out, nettype)
  384.  *    char *host;
  385.  *    u_long prognum, versnum, procnum;
  386.  *    xdrproc_t inproc, outproc;
  387.  *    char *in, *out;
  388.  *    char *nettype;
  389.  */
  390. extern enum clnt_stat rpc_call();
  391.  
  392. /*
  393.  * RPC broadcast interface
  394.  * extern enum clnt_stat
  395.  * rpc_broadcast(prog, vers, proc, xargs, argsp, xresults, resultsp,
  396.  *            eachresult, nettype)
  397.  *    u_long        prog;        -- program number
  398.  *    u_long        vers;        -- version number
  399.  *    u_long        proc;        -- procedure number
  400.  *    xdrproc_t    xargs;        -- xdr routine for args
  401.  *    caddr_t        argsp;        -- pointer to args
  402.  *    xdrproc_t    xresults;    -- xdr routine for results
  403.  *    caddr_t        resultsp;    -- pointer to results
  404.  *    resultproc_t    eachresult;    -- call with each result obtained
  405.  *    char        *nettype;    -- Transport type
  406.  */
  407. extern enum clnt_stat rpc_broadcast();
  408.  
  409. #endif /* !KERNEL */
  410.  
  411. /*
  412.  * Copy error message to buffer.
  413.  */
  414. char *clnt_sperrno(/* enum clnt_stat num */);    /* string */
  415.  
  416. #ifdef PORTMAP
  417. /* For backword compatibility */
  418. #include <rpc/clnt_soc.h>
  419. #endif
  420.  
  421. #endif /* !_RPC_CLNT_H */
  422.