rpc.subproj/xdr.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: @(#)xdr.h 1.19 87/04/22 SMI
  54  *      from: @(#)xdr.h 2.2 88/07/29 4.0 RPCSRC
  55  *      $Id: xdr.h,v 1.3 2003/06/23 17:24:59 majka Exp $
  56  */
  57
  58 /*
  59  * xdr.h, External Data Representation Serialization Routines.
  60  *
  61  * Copyright (C) 1984, Sun Microsystems, Inc.
  62  */
  63
  64 #ifndef _RPC_XDR_H
  65 #define _RPC_XDR_H
  66 #include <sys/cdefs.h>
  67
  68 /*
  69  * XDR provides a conventional way for converting between C data
  70  * types and an external bit-string representation.  Library supplied
  71  * routines provide for the conversion on built-in C data types.  These
  72  * routines and utility routines defined here are used to help implement
  73  * a type encode/decode routine for each user-defined type.
  74  *
  75  * Each data type provides a single procedure which takes two arguments:
  76  *
  77  *      bool_t
  78  *      xdrproc(xdrs, argresp)
  79  *              XDR *xdrs;
  80  *              <type> *argresp;
  81  *
  82  * xdrs is an instance of a XDR handle, to which or from which the data
  83  * type is to be converted.  argresp is a pointer to the structure to be
  84  * converted.  The XDR handle contains an operation field which indicates
  85  * which of the operations (ENCODE, DECODE * or FREE) is to be performed.
  86  *
  87  * XDR_DECODE may allocate space if the pointer argresp is null.  This
  88  * data can be freed with the XDR_FREE operation.
  89  *
  90  * We write only one procedure per data type to make it easy
  91  * to keep the encode and decode procedures for a data type consistent.
  92  * In many cases the same code performs all operations on a user defined type,
  93  * because all the hard work is done in the component type routines.
  94  * decode as a series of calls on the nested data types.
  95  */
  96
  97 /*
  98  * Xdr operations.  XDR_ENCODE causes the type to be encoded into the
  99  * stream.  XDR_DECODE causes the type to be extracted from the stream.
 100  * XDR_FREE can be used to release the space allocated by an XDR_DECODE
 101  * request.
 102  */
 103 enum xdr_op {
 104         XDR_ENCODE=0,
 105         XDR_DECODE=1,
 106         XDR_FREE=2
 107 };
 108
 109 /*
 110  * This is the number of bytes per unit of external data.
 111  */
 112 #define BYTES_PER_XDR_UNIT      (4)
 113 #define RNDUP(x)  ((((x) + BYTES_PER_XDR_UNIT - 1) / BYTES_PER_XDR_UNIT) \
 114                     * BYTES_PER_XDR_UNIT)
 115
 116 /*
 117  * A xdrproc_t exists for each data type which is to be encoded or decoded.
 118  *
 119  * The second argument to the xdrproc_t is a pointer to an opaque pointer.
 120  * The opaque pointer generally points to a structure of the data type
 121  * to be decoded.  If this pointer is 0, then the type routines should
 122  * allocate dynamic storage of the appropriate size and return it.
 123  * bool_t       (*xdrproc_t)(XDR *, caddr_t *);
 124  */
 125 typedef bool_t (*xdrproc_t)();
 126
 127 /*
 128  * The XDR handle.
 129  * Contains operation which is being applied to the stream,
 130  * an operations vector for the paticular implementation (e.g. see xdr_mem.c),
 131  * and two private fields for the use of the particular impelementation.
 132  */
 133 typedef struct __rpc_xdr {
 134         enum xdr_op     x_op;           /* operation; fast additional param */
 135         struct xdr_ops {
 136                 bool_t (*x_getlong)(struct __rpc_xdr *, long *);
 137                 bool_t (*x_putlong)(struct __rpc_xdr *, long *);
 138                 bool_t (*x_getbytes)(struct __rpc_xdr *, caddr_t, u_int);
 139                 bool_t (*x_putbytes)(struct __rpc_xdr *, caddr_t, u_int);
 140                 u_int (*x_getpostn)(struct __rpc_xdr *);
 141                 bool_t (*x_setpostn)(struct __rpc_xdr *, u_int);
 142                 long *(*x_inline)(struct __rpc_xdr *, u_int);
 143                 void (*x_destroy)(struct __rpc_xdr *);
 144         } *x_ops;
 145         caddr_t x_public;   /* users' data */
 146         caddr_t x_private;  /* pointer to private data */
 147         caddr_t x_base;    /* private used for position info */
 148         int x_handy;    /* extra private word */
 149 } XDR;
 150
 151 /*
 152  * Operations defined on a XDR handle
 153  *
 154  * XDR          *xdrs;
 155  * long         *longp;
 156  * caddr_t       addr;
 157  * u_int         len;
 158  * u_int         pos;
 159  */
 160 #define XDR_GETLONG(xdrs, longp)                        \
 161         (*(xdrs)->x_ops->x_getlong)(xdrs, longp)
 162 #define xdr_getlong(xdrs, longp)                        \
 163         (*(xdrs)->x_ops->x_getlong)(xdrs, longp)
 164
 165 #define XDR_PUTLONG(xdrs, longp)                        \
 166         (*(xdrs)->x_ops->x_putlong)(xdrs, longp)
 167 #define xdr_putlong(xdrs, longp)                        \
 168         (*(xdrs)->x_ops->x_putlong)(xdrs, longp)
 169
 170 #define XDR_GETBYTES(xdrs, addr, len)                   \
 171         (*(xdrs)->x_ops->x_getbytes)(xdrs, addr, len)
 172 #define xdr_getbytes(xdrs, addr, len)                   \
 173         (*(xdrs)->x_ops->x_getbytes)(xdrs, addr, len)
 174
 175 #define XDR_PUTBYTES(xdrs, addr, len)                   \
 176         (*(xdrs)->x_ops->x_putbytes)(xdrs, addr, len)
 177 #define xdr_putbytes(xdrs, addr, len)                   \
 178         (*(xdrs)->x_ops->x_putbytes)(xdrs, addr, len)
 179
 180 #define XDR_GETPOS(xdrs)                                \
 181         (*(xdrs)->x_ops->x_getpostn)(xdrs)
 182 #define xdr_getpos(xdrs)                                \
 183         (*(xdrs)->x_ops->x_getpostn)(xdrs)
 184
 185 #define XDR_SETPOS(xdrs, pos)                           \
 186         (*(xdrs)->x_ops->x_setpostn)(xdrs, pos)
 187 #define xdr_setpos(xdrs, pos)                           \
 188         (*(xdrs)->x_ops->x_setpostn)(xdrs, pos)
 189
 190 #define XDR_INLINE(xdrs, len)                           \
 191         (*(xdrs)->x_ops->x_inline)(xdrs, len)
 192 #define xdr_inline(xdrs, len)                           \
 193         (*(xdrs)->x_ops->x_inline)(xdrs, len)
 194
 195 #define XDR_DESTROY(xdrs) \
 196     if (xdrs) \
 197         if ((xdrs)->x_ops) \
 198             if ((xdrs)->x_ops->x_destroy) \
 199                 (*(xdrs)->x_ops->x_destroy)(xdrs)
 200 #define xdr_destroy(xdrs) \
 201     if (xdrs) \
 202         if ((xdrs)->x_ops) \
 203             if ((xdrs)->x_ops->x_destroy) \
 204                 (*(xdrs)->x_ops->x_destroy)(xdrs)
 205
 206 /*
 207  * Support struct for discriminated unions.
 208  * You create an array of xdrdiscrim structures, terminated with
 209  * a entry with a null procedure pointer.  The xdr_union routine gets
 210  * the discriminant value and then searches the array of structures
 211  * for a matching value.  If a match is found the associated xdr routine
 212  * is called to handle that part of the union.  If there is
 213  * no match, then a default routine may be called.
 214  * If there is no match and no default routine it is an error.
 215  */
 216 #define NULL_xdrproc_t ((xdrproc_t)0)
 217 struct xdr_discrim {
 218         int     value;
 219         xdrproc_t proc;
 220 };
 221
 222 /*
 223  * In-line routines for fast encode/decode of primitve data types.
 224  * Caveat emptor: these use single memory cycles to get the
 225  * data from the underlying buffer, and will fail to operate
 226  * properly if the data is not aligned.  The standard way to use these
 227  * is to say:
 228  *      if ((buf = XDR_INLINE(xdrs, count)) == NULL)
 229  *              return (FALSE);
 230  *      <<< macro calls >>>
 231  * where ``count'' is the number of bytes of data occupied
 232  * by the primitive data types.
 233  *
 234  * N.B. and frozen for all time: each data type here uses 4 bytes
 235  * of external representation.
 236  */
 237 #define IXDR_GET_LONG(buf)              ((long)ntohl((u_long)*(buf)++))
 238 #define IXDR_PUT_LONG(buf, v)           (*(buf)++ = (long)htonl((u_long)v))
 239
 240 #define IXDR_GET_BOOL(buf)              ((bool_t)IXDR_GET_LONG(buf))
 241 #define IXDR_GET_ENUM(buf, t)           ((t)IXDR_GET_LONG(buf))
 242 #define IXDR_GET_U_LONG(buf)            ((u_long)IXDR_GET_LONG(buf))
 243 #define IXDR_GET_SHORT(buf)             ((short)IXDR_GET_LONG(buf))
 244 #define IXDR_GET_U_SHORT(buf)           ((u_short)IXDR_GET_LONG(buf))
 245
 246 #define IXDR_PUT_BOOL(buf, v)           IXDR_PUT_LONG((buf), ((long)(v)))
 247 #define IXDR_PUT_ENUM(buf, v)           IXDR_PUT_LONG((buf), ((long)(v)))
 248 #define IXDR_PUT_U_LONG(buf, v)         IXDR_PUT_LONG((buf), ((long)(v)))
 249 #define IXDR_PUT_SHORT(buf, v)          IXDR_PUT_LONG((buf), ((long)(v)))
 250 #define IXDR_PUT_U_SHORT(buf, v)        IXDR_PUT_LONG((buf), ((long)(v)))
 251
 252 /*
 253  * These are the "generic" xdr routines.
 254  */
 255 __BEGIN_DECLS
 256 extern bool_t   xdr_void        __P((void));
 257 extern bool_t   xdr_int         __P((XDR *, int *));
 258 extern bool_t   xdr_u_int       __P((XDR *, u_int *));
 259 extern bool_t   xdr_long        __P((XDR *, long *));
 260 extern bool_t   xdr_u_long      __P((XDR *, u_long *));
 261 extern bool_t   xdr_short       __P((XDR *, short *));
 262 extern bool_t   xdr_u_short     __P((XDR *, u_short *));
 263 extern bool_t   xdr_bool        __P((XDR *, bool_t *));
 264 extern bool_t   xdr_enum        __P((XDR *, enum_t *));
 265 extern bool_t   xdr_array       __P((XDR *, char **, u_int *, u_int, u_int, xdrproc_t));
 266 extern bool_t   xdr_bytes       __P((XDR *, char **, u_int *, u_int));
 267 extern bool_t   xdr_opaque      __P((XDR *, caddr_t, u_int));
 268 extern bool_t   xdr_string      __P((XDR *, char **, u_int));
 269 extern bool_t   xdr_union       __P((XDR *, enum_t *, char *, struct xdr_discrim *, xdrproc_t));
 270 extern bool_t   xdr_char        __P((XDR *, char *));
 271 extern bool_t   xdr_u_char      __P((XDR *, u_char *));
 272 extern bool_t   xdr_vector      __P((XDR *, char *, u_int, u_int, xdrproc_t));
 273 extern bool_t   xdr_float       __P((XDR *, float *));
 274 extern bool_t   xdr_double      __P((XDR *, double *));
 275 extern bool_t   xdr_reference   __P((XDR *, caddr_t *, u_int, xdrproc_t));
 276 extern bool_t   xdr_pointer     __P((XDR *, caddr_t *, u_int, xdrproc_t));
 277 extern bool_t   xdr_wrapstring  __P((XDR *, char **));
 278 extern void     xdr_free        __P((xdrproc_t, void *));
 279 __END_DECLS
 280
 281 /*
 282  * Common opaque bytes objects used by many rpc protocols;
 283  * declared here due to commonality.
 284  */
 285 #define MAX_NETOBJ_SZ 1024
 286 struct netobj {
 287         u_int   n_len;
 288         char    *n_bytes;
 289 };
 290 typedef struct netobj netobj;
 291 extern bool_t   xdr_netobj();
 292
 293 /*
 294  * These are the public routines for the various implementations of
 295  * xdr streams.
 296  */
 297 __BEGIN_DECLS
 298 /* XDR using memory buffers */
 299 extern void   xdrmem_create     __P((XDR *, void *, u_int, enum xdr_op));
 300
 301 #ifdef _STDIO_H_
 302 /* XDR using stdio library */
 303 extern void   xdrstdio_create   __P((XDR *, FILE *, enum xdr_op));
 304 #endif
 305
 306 /* XDR pseudo records for tcp */
 307 extern void   xdrrec_create     __P((XDR *, u_int, u_int, char *, int (*)(), int (*)()));
 308
 309 /* make end of xdr record */
 310 extern bool_t xdrrec_endofrecord __P((XDR *, int));
 311
 312 /* move to beginning of next record */
 313 extern bool_t xdrrec_skiprecord __P((XDR *));
 314
 315 /* true if no more input */
 316 extern bool_t xdrrec_eof        __P((XDR *));
 317 __END_DECLS
 318
 319 #endif /* !_RPC_XDR_H */