Developing distributed applications using ONC RPC and XDR

XDR streams implementation

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

The XDR object

The following structure defines the interface to an XDR stream:

   enum xdr_op { XDR_ENCODE = 0, XDR_DECODE = 1, XDR_FREE = 2 };
   
   typedef struct {
      enum	xdr_op x_op;   / operation; fast additional param /
      struct	xdr_ops {
      	bool_t	(x_getlong)();    / get a long from underlying stream /
      	bool_t	(x_putlong)();    / put a long to " /
      	bool_t	(x_getbytes)();   / get some bytes from " /
      	bool_t	(x_putbytes)();   / put some bytes to " /
      	uint	(x_getpostn)();   / returns byte offset from beginning /
      	bool_t	(x_setpostn)();   / repositions position in stream /
      	caddr_t	(x_inline)();     / buf ptr to buffered data /
      	VOID	(x_destroy)();    / free privates of this xdr_stream /
      }	x_ops;
      caddr_t	x_public;    / users' data /
      caddr_t	x_private;   / pointer to private data /
      caddr_t	x_base;      / private used 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 the implementation of a stream. That is, the implementation of a stream 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.

Macros for accessing operations x_getpostn(), x_setpostn(), and x_destroy() were defined in the section ``Non-filter primitives''. The operation x_inline() takes 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 point of view of the stream, the bytes in the buffer segment have been consumed or put.

The routine may return NULL if it cannot return a buffer segment of the requested size. (The x_inline routine is for cycle squeezers. Use of the resulting buffer is not data-portable. Programmers are encouraged not to use 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;
           uint 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 system primitives htonl() and ntohl() can be helpful in accomplishing this. The section ``XDR standard'' defines the standard representation of numbers. The higher-level XDR implementation assumes that signed and unsigned long integers contain the same number of bits, and that non-negative 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.