rpc.subproj/clnt.h

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