[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 Communications Programming Concepts

XDR Non-Filter Primitives

The eXternal Data Representation (XDR) nonfilter primitives are used to create, manipulate, implement, and destroy XDR data streams. These primitives allow programmers to destroy a data stream (freeing its private structure) for example, or change a data stream position.

Creating and Using XDR Data Streams

XDR data streams are obtained by calling creation subroutines that take arguments specifically designed to the properties of the stream. There are existing XDR data streams for serializing or deserializing data in standard input and output streams, memory streams, and record streams.

Note: Remote Procedure Call (RPC) clients do not have to create XDR streams because the RPC system creates and passes these streams to the client.

The types of data streams include standard I/O streams, memory streams, and record streams.

Standard I/O Streams

XDR data streams serialize and deserialize standard input and output by calling the standard I/O creation subroutine to initialize the XDR data stream pointed to by the xdrs parameter.

The XDR library includes the following subroutine for standard I/O data streams:

xdrstdio_create Initializes the XDR data stream pointed to by the xdrs parameter.

Memory Streams

XDR data streams serialize and deserialize data from memory by calling the XDR memory creation subroutine to initialize in local memory the XDR stream pointed to by the xdrs parameter. In RPC, the User Datagram Protocol (UDP) Internet Protocol (IP) implementation uses this subroutine to build entire call-and-reply messages in memory before sending a message to the recipient.

The XDR library includes the following subroutine for memory data streams:

xdrmem_create Initializes in local memory the XDR stream pointed to by the xdrs parameter.

Record Streams

Record streams are XDR streams built on top of record fragments, which are built on TCP/IP streams. TCP/IP is a connection protocol for transporting large streams of data at one time, instead of transporting a single data packet at a time.

Record streams are primarily used to make connections between remote procedure calls and TCP. They can also be used to stream data into or out of normal files.

XDR provides the following subroutines for use with record streams:

xdrrec_create Provides an XDR stream that can contain long sequences of records.
xdrrec_endofrecord Causes the current outgoing data to be marked as a record.
xdrrec_eof Checks the buffer for an input stream that identifies the end of file (EOF).
xdrrec_skiprecord Causes the position of an input stream to move to the beginning of the next record.

Manipulating an XDR Data Stream

XDR provides the following subroutines for describing and changing data stream position:

xdr_getpos Returns an unsigned integer that describes the current position of the data stream.
xdr_setpos Changes the current position of the data stream.

Implementing an XDR Data Stream

Programmers can create and implement XDR data streams. The following example shows the abstract data types (XDR handle) required. The example contains operations being applied to the stream, an operation vector for the implementation, and two private fields for use by the implementation.

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)  ();
           boot_t  (*x_putlong)  ();
           boot_t  (*x_getbytes) ();
           boot_t  (*x_putbytes) ();
           u_int   (*x_getpostn) ();
           boot_t  (*x_setpostn) ();
           caddr_t (*x_inline)   ();
           VOID    (*x_destroy)  ();
       } *XOp;
       caddr_t x_public;
       caddr_t x_private;
       caddr_t x_base;
       int     x_handy;
} XDR;

The following parameters are pointers to XDR stream manipulation subroutines:

x_destroy Frees private data structures.
x_getbytes Gets bytes from the data stream.
x_getlong Gets long integer values from the data stream.
x_getpostn Returns stream offset.
x_inline Points to internal data buffer, which can be used for any purpose.
x_putbytes Puts bytes into the data stream.
x_putlong Puts long integer values into the data stream.
x_setpostn Repositions offset.
XOp Specifies the current operation being performed on the stream. This field is important to the XDR primitives. However, the stream's implementation does not depend on the value of this parameter.

The following fields are specific to a stream's implementation:

x_base Contains position information in the data stream that is private to the user implementation.
x_handy Contains extra information, as necessary.
x_public Specifies user data that is private to the stream's implementation and is not used by the XDR primitive.
x_private Points to the private data.

Destroying an XDR Data Stream

The following subroutine destroys a specific XDR data stream:

xdr_destroy Destroys the XDR data stream pointed to by the xdrs parameter, freeing the private data structures allocated to the stream.

The use of the XDR data stream handle is undefined after it is destroyed.


[ Previous | Next | Contents | Glossary | Home | Search ]