oncrpc/rpc/clnt.h

   1 /*********************************************************************
   2  * RPC for the Windows NT Operating System
   3  * 1993 by Martin F. Gergeleit
   4  * Users may use, copy or modify Sun RPC for the Windows NT Operating
   5  * System according to the Sun copyright below.
   6  *
   7  * RPC for the Windows NT Operating System COMES WITH ABSOLUTELY NO
   8  * WARRANTY, NOR WILL I BE LIABLE FOR ANY DAMAGES INCURRED FROM THE
   9  * USE OF. USE ENTIRELY AT YOUR OWN RISK!!!
  10  *********************************************************************/
  11
  12 /* @(#)clnt.h   2.1 88/07/29 4.0 RPCSRC; from 1.31 88/02/08 SMI*/
  13 /*
  14  * Sun RPC is a product of Sun Microsystems, Inc. and is provided for
  15  * unrestricted use provided that this legend is included on all tape
  16  * media and as a part of the software program in whole or part.  Users
  17  * may copy or modify Sun RPC without charge, but are not authorized
  18  * to license or distribute it to anyone else except as part of a product or
  19  * program developed by the user.
  20  *
  21  * SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE
  22  * WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
  23  * PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.
  24  *
  25  * Sun RPC is provided with no support and without any obligation on the
  26  * part of Sun Microsystems, Inc. to assist in its use, correction,
  27  * modification or enhancement.
  28  *
  29  * SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
  30  * INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY SUN RPC
  31  * OR ANY PART THEREOF.
  32  *
  33  * In no event will Sun Microsystems, Inc. be liable for any lost revenue
  34  * or profits or other special, indirect and consequential damages, even if
  35  * Sun has been advised of the possibility of such damages.
  36  *
  37  * Sun Microsystems, Inc.
  38  * 2550 Garcia Avenue
  39  * Mountain View, California  94043
  40  */
  41
  42 /*
  43  * clnt.h - Client side remote procedure call interface.
  44  *
  45  * Copyright (C) 1984, Sun Microsystems, Inc.
  46  */
  47
  48 #ifndef _CLNT_
  49 #define _CLNT_
  50
  51 #ifdef __cplusplus
  52 extern "C" {
  53 #define DOTS ...
  54 #else
  55 #define DOTS
  56 #endif
  57
  58 /*
  59  * Rpc calls return an enum clnt_stat.  This should be looked at more,
  60  * since each implementation is required to live with this (implementation
  61  * independent) list of errors.
  62  */
  63 enum clnt_stat {
  64         RPC_SUCCESS=0,                  /* call succeeded */
  65         /*
  66          * local errors
  67          */
  68         RPC_CANTENCODEARGS=1,           /* can't encode arguments */
  69         RPC_CANTDECODERES=2,            /* can't decode results */
  70         RPC_CANTSEND=3,                 /* failure in sending call */
  71         RPC_CANTRECV=4,                 /* failure in receiving result */
  72         RPC_TIMEDOUT=5,                 /* call timed out */
  73         /*
  74          * remote errors
  75          */
  76         RPC_VERSMISMATCH=6,             /* rpc versions not compatible */
  77         RPC_AUTHERROR=7,                /* authentication error */
  78         RPC_PROGUNAVAIL=8,              /* program not available */
  79         RPC_PROGVERSMISMATCH=9,         /* program version mismatched */
  80         RPC_PROCUNAVAIL=10,             /* procedure unavailable */
  81         RPC_CANTDECODEARGS=11,          /* decode arguments error */
  82         RPC_SYSTEMERROR=12,             /* generic "other problem" */
  83
  84         /*
  85          * callrpc & clnt_create errors
  86          */
  87         RPC_UNKNOWNHOST=13,             /* unknown host name */
  88         RPC_UNKNOWNPROTO=17,            /* unkown protocol */
  89
  90         /*
  91          * _ create errors
  92          */
  93         RPC_PMAPFAILURE=14,             /* the pmapper failed in its call */
  94         RPC_PROGNOTREGISTERED=15,       /* remote program is not registered */
  95         /*
  96          * unspecified error
  97          */
  98         RPC_FAILED=16
  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)(DOTS);       /* call remote procedure */
 135                 void            (*cl_abort)(DOTS);      /* abort a call */
 136                 void            (*cl_geterr)(DOTS);     /* get specific error code */
 137                 bool_t          (*cl_freeres)(DOTS); /* frees results */
 138                 void            (*cl_destroy)(DOTS);/* destroy this structure */
 139                 bool_t          (*cl_control)(DOTS);/* 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(DOTS);
 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*/DOTS); /*
 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(DOTS);
 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(DOTS);
 308 extern CLIENT *clntudp_bufcreate(DOTS);
 309
 310 /*
 311  * Print why creation failed
 312  */
 313 void clnt_pcreateerror(/* char *msg */DOTS);    /* stderr */
 314 char *clnt_spcreateerror(/* char *msg */DOTS);  /* string */
 315
 316 /*
 317  * Like clnt_perror(), but is more verbose in its output
 318  */
 319 void clnt_perrno(/* enum clnt_stat num */DOTS); /* stderr */
 320
 321 /*
 322  * Print an English error message, given the client error code
 323  */
 324 void clnt_perror(/* CLIENT *clnt, char *msg */DOTS);    /* stderr */
 325 char *clnt_sperror(/* CLIENT *clnt, char *msg */DOTS);  /* string */
 326
 327 /*
 328  * If a creation fails, the following allows the user to figure out why.
 329  */
 330 struct rpc_createerr_t {
 331         enum clnt_stat cf_stat;
 332         struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
 333 };
 334
 335 /*
 336 #ifdef WIN32
 337 #ifdef ONCRPCDLL
 338 extern struct rpc_createerr rpc_createerr;
 339 #else
 340 #ifdef __BORLANDC__
 341 extern __declspec(dllimport) struct rpc_createerr rpc_createerr;
 342 #else
 343 _declspec(dllimport) struct rpc_createerr rpc_createerr;
 344 #endif
 345 #endif
 346 #else
 347 extern struct rpc_createerr rpc_createerr;
 348 #endif
 349 */
 350 #define rpc_createerr (*_thr_rpc_createerr())
 351
 352 /*
 353  * Copy error message to buffer.
 354  */
 355 char *clnt_sperrno(/* enum clnt_stat num */DOTS);       /* string */
 356
 357
 358
 359 #define UDPMSGSIZE      8800    /* rpc imposed limit on udp msg size */
 360 #define RPCSMALLMSGSIZE 400     /* a more reasonable packet size */
 361
 362 #ifdef __cplusplus
 363 };
 364 #endif
 365
 366 #endif /*!_CLNT_*/