ONC+ RPC Developer's Guide

XDR Stream Implementation

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

XDR Object

The structure in the following code example defines the interface to an XDR stream.

Example 88  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 */
		bool_t (*x_control)();			/* change, retrieve client info */
		bool_t (*x_getint32)();       /* get int from stream */
 		bool_t (*x_putint32)();       /* put into stream */
 	} *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. The stream's interpretation is that the bytes in the buffer segment have been consumed. The routine can return NULL if it cannot return a buffer segment of the requested size.

The operations x_getbytes() and x_putbytes() routinely 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 with the same string in each case.)

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

The operations x_getint32() and x_putint32() receive and put int numbers from and to the data stream. These routines are responsible for translating the numbers between the system representation and the (standard) external representation. The UNIX primitives htonl() and ntohl() can be helpful in accomplishing this objective. The higher-level XDR implementation assumes that signed and unsigned 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.

The x_getint() and x_putint() functions make use of these operations. They have identical parameters:

bool_t
xxxint(xdrs, ip)
   XDR *xdrs;
   int32_t *ip;

The long version of these operations (x_getlong() and x_putlong()) also call x_getint32() and x_putint32(), ensuring that a 4-byte quantity is operated on, no matter what system the program is running on.

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