XDR Stream Implementation

This section provides the abstract data types needed to implement new instances of XDR streams.

The XDR Object

The structure in Example A-13defines the interface to an XDR stream.

Example A-13 XDR Stream Interface Example

enum xdr_op {XDR_ENCODE=0, XDR_DECODE=1, XDR_FREE=2};

typedef struct {
	enum xdr_op x_op;
	struct xdr_ops {
 		bool_t (*x_getlong)();       /* get long from stream */
 		bool_t (*x_putlong)();       /* put long to stream */
 		bool_t (*x_getbytes)();      /* get bytes from stream */
 		bool_t (*x_putbytes)();      /* put bytes to stream */
 		u_int (*x_getpostn)();       /* return stream offset */
 		bool_t (*x_setpostn)();      /* reposition offset */
 		caddr_t (*x_inline)();       /* ptr to buffered data */
 		VOID (*x_destroy)();         /* free private area */
 	} *x_ops;
 	caddr_t x_public;                /* users' data */
 	caddr_t x_private;               /* pointer to private data */
 	caddr_t x_base;                  /* private for position info */
 	int		 x_handy;                 /* extra private word */
 } XDR;

The x_op field is the current operation being performed on the stream. This field is important to the XDR primitives, but should not affect a stream's implementation. That is, a stream's implementation should not depend on this value. The fields x_private, x_base, and x_handy are private to the particular stream's implementation. The field x_public is for the XDR client and should never be used by the XDR stream implementations or the XDR primitives. x_getpostn(), x_setpostn(), and x_destroy() are macros for accessing operations. The operation x_inline() has two parameters: an XDR *, and an unsigned integer, which is a byte count. The routine returns a pointer to a piece of the stream's internal buffer. The caller can then use the buffer segment for any purpose. From the stream's point of view, the bytes in the buffer segment have been consumed. The routine may return NULL if it cannot return a buffer segment of the requested size. (The x_inline() routine is used to squeeze cycles, and the resulting buffer is not data portable. Users are cautioned against using this feature.)

The operations x_getbytes() and x_putbytes() blindly get and put sequences of bytes from or to the underlying stream; they return TRUE if they are successful, and FALSE otherwise. The routines have identical parameters (replace xxx):

bool_t
xxxbytes(xdrs, buf, bytecount)
   XDR *xdrs;
   char *buf;
   u_int bytecount;

The operations x_getlong() and x_putlong() receive and put long numbers from and to the data stream. It is the responsibility of these routines to translate the numbers between the machine representation and the (standard) external representation. The UNIX primitives htonl() and ntohl() can be helpful in accomplishing this. The higher-level XDR implementation assumes that signed and unsigned long integers contain the same number of bits, and that nonnegative integers have the same bit representations as unsigned integers. The routines return TRUE if they succeed, and FALSE otherwise.

They have identical parameters:

bool_t
xxxlong(xdrs, lp)
   XDR *xdrs;
   long *lp;

Implementors of new XDR streams must make an XDR structure (with new operation routines) available to clients, using some kind of create routine.