include/gssrpc/clnt.h

0001 /* @(#)clnt.h   2.1 88/07/29 4.0 RPCSRC; from 1.31 88/02/08 SMI*/
0002 /*
0003  * Copyright (c) 2010, Oracle America, Inc.
0004  *
0005  * All rights reserved.
0006  *
0007  * Redistribution and use in source and binary forms, with or without
0008  * modification, are permitted provided that the following conditions are met:
0009  *
0010  *     * Redistributions of source code must retain the above copyright
0011  *       notice, this list of conditions and the following disclaimer.
0012  *
0013  *     * Redistributions in binary form must reproduce the above copyright
0014  *       notice, this list of conditions and the following disclaimer in
0015  *       the documentation and/or other materials provided with the
0016  *       distribution.
0017  *
0018  *     * Neither the name of the "Oracle America, Inc." nor the names of
0019  *       its contributors may be used to endorse or promote products
0020  *       derived from this software without specific prior written permission.
0021  *
0022  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
0023  * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
0024  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
0025  * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
0026  * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
0027  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
0028  * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
0029  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
0030  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
0031  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
0032  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
0033  */
0034
0035 /*
0036  * clnt.h - Client side remote procedure call interface.
0037  */
0038
0039 #ifndef GSSRPC_CLNT_H
0040 #define GSSRPC_CLNT_H
0041
0042 GSSRPC__BEGIN_DECLS
0043 /*
0044  * Rpc calls return an enum clnt_stat.  This should be looked at more,
0045  * since each implementation is required to live with this (implementation
0046  * independent) list of errors.
0047  */
0048 enum clnt_stat {
0049     RPC_SUCCESS=0,          /* call succeeded */
0050     /*
0051      * local errors
0052      */
0053     RPC_CANTENCODEARGS=1,       /* can't encode arguments */
0054     RPC_CANTDECODERES=2,        /* can't decode results */
0055     RPC_CANTSEND=3,         /* failure in sending call */
0056     RPC_CANTRECV=4,         /* failure in receiving result */
0057     RPC_TIMEDOUT=5,         /* call timed out */
0058     /*
0059      * remote errors
0060      */
0061     RPC_VERSMISMATCH=6,     /* rpc versions not compatible */
0062     RPC_AUTHERROR=7,        /* authentication error */
0063     RPC_PROGUNAVAIL=8,      /* program not available */
0064     RPC_PROGVERSMISMATCH=9,     /* program version mismatched */
0065     RPC_PROCUNAVAIL=10,     /* procedure unavailable */
0066     RPC_CANTDECODEARGS=11,      /* decode arguments error */
0067     RPC_SYSTEMERROR=12,     /* generic "other problem" */
0068
0069     /*
0070      * callrpc & clnt_create errors
0071      */
0072     RPC_UNKNOWNHOST=13,     /* unknown host name */
0073     RPC_UNKNOWNPROTO=17,        /* unknown protocol */
0074
0075     /*
0076      * _ create errors
0077      */
0078     RPC_PMAPFAILURE=14,     /* the pmapper failed in its call */
0079     RPC_PROGNOTREGISTERED=15,   /* remote program is not registered */
0080     /*
0081      * unspecified error
0082      */
0083     RPC_FAILED=16
0084 };
0085
0086
0087 /*
0088  * Error info.
0089  */
0090 struct rpc_err {
0091     enum clnt_stat re_status;
0092     union {
0093         int RE_errno;       /* realated system error */
0094         enum auth_stat RE_why;  /* why the auth error occurred */
0095         struct {
0096             rpcvers_t low;  /* lowest version supported */
0097             rpcvers_t high; /* highest version supported */
0098         } RE_vers;
0099         struct {        /* maybe meaningful if RPC_FAILED */
0100             int32_t s1;
0101             int32_t s2;
0102         } RE_lb;        /* life boot & debugging only */
0103     } ru;
0104 #define re_errno    ru.RE_errno
0105 #define re_why      ru.RE_why
0106 #define re_vers     ru.RE_vers
0107 #define re_lb       ru.RE_lb
0108 };
0109
0110
0111 /*
0112  * Client rpc handle.
0113  * Created by individual implementations, see e.g. rpc_udp.c.
0114  * Client is responsible for initializing auth, see e.g. auth_none.c.
0115  */
0116 typedef struct CLIENT {
0117     AUTH    *cl_auth;           /* authenticator */
0118     struct clnt_ops {
0119         /* call remote procedure */
0120         enum clnt_stat  (*cl_call)(struct CLIENT *,
0121                        rpcproc_t, xdrproc_t, void *,
0122                        xdrproc_t, void *,
0123                        struct timeval);
0124         /* abort a call */
0125         void        (*cl_abort)(struct CLIENT *);
0126         /* get specific error code */
0127         void        (*cl_geterr)(struct CLIENT *,
0128                          struct rpc_err *);
0129         /* frees results */
0130         bool_t      (*cl_freeres)(struct CLIENT *,
0131                           xdrproc_t, void *);
0132         /* destroy this structure */
0133         void        (*cl_destroy)(struct CLIENT *);
0134         /* the ioctl() of rpc */
0135         /* XXX CITI makes 2nd arg take u_int */
0136         bool_t          (*cl_control)(struct CLIENT *, int,
0137                           void *);
0138     } *cl_ops;
0139     void            *cl_private;    /* private stuff */
0140 } CLIENT;
0141
0142
0143 /*
0144  * client side rpc interface ops
0145  *
0146  * Parameter types are:
0147  *
0148  */
0149
0150 /*
0151  * enum clnt_stat
0152  * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
0153  *  CLIENT *rh;
0154  *  rpcproc_t proc;
0155  *  xdrproc_t xargs;
0156  *  caddr_t argsp;
0157  *  xdrproc_t xres;
0158  *  caddr_t resp;
0159  *  struct timeval timeout;
0160  */
0161 #define CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs) \
0162     ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
0163 #define clnt_call(rh, proc, xargs, argsp, xres, resp, secs) \
0164     ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
0165
0166 /*
0167  * void
0168  * CLNT_ABORT(rh);
0169  *  CLIENT *rh;
0170  */
0171 #define CLNT_ABORT(rh)  ((*(rh)->cl_ops->cl_abort)(rh))
0172 #define clnt_abort(rh)  ((*(rh)->cl_ops->cl_abort)(rh))
0173
0174 /*
0175  * struct rpc_err
0176  * CLNT_GETERR(rh);
0177  *  CLIENT *rh;
0178  */
0179 #define CLNT_GETERR(rh,errp)    ((*(rh)->cl_ops->cl_geterr)(rh, errp))
0180 #define clnt_geterr(rh,errp)    ((*(rh)->cl_ops->cl_geterr)(rh, errp))
0181
0182
0183 /*
0184  * bool_t
0185  * CLNT_FREERES(rh, xres, resp);
0186  *  CLIENT *rh;
0187  *  xdrproc_t xres;
0188  *  caddr_t resp;
0189  */
0190 #define CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
0191 #define clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
0192
0193 /*
0194  * bool_t
0195  * CLNT_CONTROL(cl, request, info)
0196  *      CLIENT *cl;
0197  *      u_int request;
0198  *      char *info;
0199  */
0200 #define CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
0201 #define clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
0202
0203 /*
0204  * control operations that apply to both udp and tcp transports
0205  */
0206 #define CLSET_TIMEOUT       1   /* set timeout (timeval) */
0207 #define CLGET_TIMEOUT       2   /* get timeout (timeval) */
0208 #define CLGET_SERVER_ADDR   3   /* get server's address (sockaddr) */
0209 /*
0210  * udp only control operations
0211  */
0212 #define CLSET_RETRY_TIMEOUT 4   /* set retry timeout (timeval) */
0213 #define CLGET_RETRY_TIMEOUT 5   /* get retry timeout (timeval) */
0214 /*
0215  * new control operations
0216  */
0217 #define CLGET_LOCAL_ADDR    6   /* get local address (sockaddr, getsockname)*/
0218
0219 /*
0220  * void
0221  * CLNT_DESTROY(rh);
0222  *  CLIENT *rh;
0223  */
0224 #define CLNT_DESTROY(rh)    ((*(rh)->cl_ops->cl_destroy)(rh))
0225 #define clnt_destroy(rh)    ((*(rh)->cl_ops->cl_destroy)(rh))
0226
0227
0228 /*
0229  * RPCTEST is a test program which is accessible on every rpc
0230  * transport/port.  It is used for testing, performance evaluation,
0231  * and network administration.
0232  */
0233
0234 #define RPCTEST_PROGRAM     ((rpcprog_t)1)
0235 #define RPCTEST_VERSION     ((rpcvers_t)1)
0236 #define RPCTEST_NULL_PROC   ((rpcproc_t)2)
0237 #define RPCTEST_NULL_BATCH_PROC ((rpcproc_t)3)
0238
0239 /*
0240  * By convention, procedure 0 takes null arguments and returns them
0241  */
0242
0243 #define NULLPROC ((rpcproc_t)0)
0244
0245 /*
0246  * Below are the client handle creation routines for the various
0247  * implementations of client side rpc.  They can return NULL if a
0248  * creation failure occurs.
0249  */
0250
0251 /*
0252  * Memory based rpc (for speed check and testing)
0253  * CLIENT *
0254  * clntraw_create(prog, vers)
0255  *  rpcprog_t prog;
0256  *  rpcvers_t vers;
0257  */
0258 extern CLIENT *clntraw_create(rpcprog_t, rpcvers_t);
0259
0260 /*
0261  * Generic client creation routine. Supported protocols are "udp" and "tcp"
0262  */
0263 extern CLIENT *clnt_create(char *, rpcprog_t, rpcvers_t, char *);
0264
0265
0266 /*
0267  * TCP based rpc
0268  * CLIENT *
0269  * clnttcp_create(raddr, prog, vers, sockp, sendsz, recvsz)
0270  *  struct sockaddr_in *raddr;
0271  *  rpcprog_t prog;
0272  *  rpcvers_t version;
0273  *  int *sockp;
0274  *  u_int sendsz;
0275  *  u_int recvsz;
0276  */
0277 extern CLIENT *clnttcp_create(struct sockaddr_in *, rpcprog_t, rpcvers_t,
0278                   int *, u_int, u_int);
0279
0280 /*
0281  * UDP based rpc.
0282  * CLIENT *
0283  * clntudp_create(raddr, program, version, wait, sockp)
0284  *  struct sockaddr_in *raddr;
0285  *  rpcprog_t program;
0286  *  rpcvers_t version;
0287  *  struct timeval wait;
0288  *  int *sockp;
0289  *
0290  * Same as above, but you specify max packet sizes.
0291  * CLIENT *
0292  * clntudp_bufcreate(raddr, program, version, wait, sockp, sendsz, recvsz)
0293  *  struct sockaddr_in *raddr;
0294  *  rpcprog_t program;
0295  *  rpcvers_t version;
0296  *  struct timeval wait;
0297  *  int *sockp;
0298  *  u_int sendsz;
0299  *  u_int recvsz;
0300  */
0301 extern CLIENT *clntudp_create(struct sockaddr_in *, rpcprog_t,
0302                   rpcvers_t, struct timeval, int *);
0303 extern CLIENT *clntudp_bufcreate(struct sockaddr_in *, rpcprog_t,
0304                  rpcvers_t, struct timeval, int *,
0305                  u_int, u_int);
0306
0307 /*
0308  * Print why creation failed
0309  */
0310 void clnt_pcreateerror(char *); /* stderr */
0311 char *clnt_spcreateerror(char *);   /* string */
0312
0313 /*
0314  * Like clnt_perror(), but is more verbose in its output
0315  */
0316 void clnt_perrno(enum clnt_stat);   /* stderr */
0317
0318 /*
0319  * Print an English error message, given the client error code
0320  */
0321 void clnt_perror(CLIENT *, char *);     /* stderr */
0322 char *clnt_sperror(CLIENT *, char *);   /* string */
0323
0324 /*
0325  * If a creation fails, the following allows the user to figure out why.
0326  */
0327 struct rpc_createerr {
0328     enum clnt_stat cf_stat;
0329     struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
0330 };
0331
0332 extern struct rpc_createerr rpc_createerr;
0333
0334
0335
0336 /*
0337  * Copy error message to buffer.
0338  */
0339 char *clnt_sperrno(enum clnt_stat num); /* string */
0340
0341 #define UDPMSGSIZE  8800    /* rpc imposed limit on udp msg size */
0342 #define RPCSMALLMSGSIZE 400 /* a more reasonable packet size */
0343
0344 GSSRPC__END_DECLS
0345
0346 #endif /* !defined(GSSRPC_CLNT_H) */