git.mutantstargoat.com Git - oftp/blob - libs/watt32/rpc/clnt.h

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