rpc.subproj/clnt.h

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