XDR Buffer APIs [Networking Libraries]

Objects and APIs to help manage XDR streams. More...

Collaboration diagram for XDR Buffer APIs:

Classes
class	xdrbuf::PackletHeader
	A PackletHeader describes a given packlet (what sort of data it is, and how much data is there). More...
class	xdrbuf::Output
	class for writing data to the network More...
class	xdrbuf::Input
	class for reading data from the network More...
Enumerations
enum	xdrbuf::ePackletType {   xdrbuf::ePacklet_Reserved = 0,   xdrbuf::ePacklet_ParentBegin = 1,   xdrbuf::ePacklet_ParentEnd = 2,   xdrbuf::ePacklet_String = 3,   xdrbuf::ePacklet_Floats = 4,   xdrbuf::ePacklet_Int32s = 5,   xdrbuf::ePacklet_Invalid = 8 }
	these are the types of data supported by packlets More...
Functions
	xdrbuf::PackletHeader::PackletHeader (void) throw ()
void	xdrbuf::PackletHeader::setData (IN word_t d)
virtual void	xdrbuf::Output::clear (void)=0
virtual int	xdrbuf::Output::getRemainingBytes (void) const =0 throw ()
virtual void	xdrbuf::Output::openPacklet (IN char name)=0
	create (open) a parent packlet in the stream
virtual void	xdrbuf::Output::closePacklet (IN char name)=0
	close an open (parent) packlet
virtual void	xdrbuf::Output::addStringPacklet (IN char name, IN const char *s, IN int length)=0
	add a string packlet to the stream
virtual void	xdrbuf::Output::addFloatPacklet (IN char name, IN const float *data, IN int nFloats)=0
	add a float packlet (array of floats) to the stream
virtual void	xdrbuf::Output::addInt32Packlet (IN char name, IN const int32_t *data, IN int nInts)=0
	add an int32 packlet (array of int32_t's) to the stream
virtual const byte_t *	xdrbuf::Output::getData (void)=0 throw ()
	retrieve raw data from buffer (called after all streaming is done)
virtual int	xdrbuf::Output::getDataBytes (void) const =0 throw ()
virtual void	xdrbuf::Input::reset (IN const byte_t *stream, IN int bytes)=0
	provide stream reading object with the raw data to use.
virtual bool	xdrbuf::Input::endOfStream (void)=0
	have we read all data?
virtual PackletHeader	xdrbuf::Input::getNextPackletHeader (void)=0
	retrieves the next packlet header (fails if not at a packlet header)
virtual void	xdrbuf::Input::readInt32s (OUT int32_t *buffer, IN int count)=0
	read int32s (fails if you didn't just read an Int32 packlet header)
virtual void	xdrbuf::Input::readFloats (OUT float *buffer, IN int count)=0
	read floats (fails if you didn't just read a float packlet header)
virtual void	xdrbuf::Input::readString (OUT char *buffer, IN int length)=0
	read strings (fails if you didn't just read a string packlet header)
Variables
word_t	xdrbuf::PackletHeader::m_data
bool	xdrbuf::isValidPackletName (IN char a)
	A name is a single character.
ePackletType	xdrbuf::PackletHeader::getType (void) const throw ()
	return the datatype contained in this packlet
int	xdrbuf::PackletHeader::getDataCount (void) const throw ()
	return count (count, not size!) , based on packlet type String: returns length of string (NOT counting null-terminator) Floats: returns count of floats Int32s: returns count of longs
static smart_ptr< Output >	xdrbuf::Output::create (IN int bytes)
static smart_ptr< Input >	xdrbuf::Input::create (void)
virtual	xdrbuf::Output::~Output (void) throw ()

---

Detailed Description

Objects and APIs to help manage XDR streams.

XDR is used to ensure that data can be passed between hosts on a network transparently, even if the hardware uses different byte ordering (little- vs big-endian).

For information on XDR, see http://en.wikipedia.org/wiki/External_Data_Representation , or, on Unix systems, type "man xdr".

Update: Actually, this library no longer depends on XDR! I found that XDR has very poor support on Windows at least. So I dropped it. Wire encoding is handled by the basic socket methods htonl(), ntohl(), etc.

The fact that this library no longer uses XDR doesn't impact callers: they were already insulated. But it does mean that "xdrbuf" is already a legacy name... For now, I'll keep referring to "XDR streams" to describe the series of bytes sent and received across the network.

What this library attempts to do is add a simple, self-describing layer on top of basic XDR streams.

The organizing unit is called a "packlet", because it is a small packet of data. You can think of packlets as something like XML tags. Packlets can contain simple data (like leaf XML nodes), or they can contain other packlets (parent XML nodes).

XML tags are fairly feature-rich, but packlets are designed to be very simple and small. A packlet header is only 2 bytes, which keeps overhead down.

Use the xdrbuf::Output object to construct XDR streams containing packlets. If you use that interface, you are guaranteed a well-formed packlet stream.

Once you receive an XDR stream (created with the xdrbuf::Output interface), use the xdrbuf::Input object to decode it. The Input object will use the encoded packlet information to verify that access to the raw XDR stream is syntactically correct.

---

Enumeration Type Documentation

enum xdrbuf::ePackletType

these are the types of data supported by packlets

Enumerator:

ePacklet_Reserved	don't use this
ePacklet_ParentBegin	packlet contains other packlets
ePacklet_ParentEnd	end of parent packlet
ePacklet_String	packlet contains a single string
ePacklet_Floats	packlet contains list of floats
ePacklet_Int32s	packlet contains list of int32s
ePacklet_Invalid

Definition at line 97 of file xdrbuf.h.

---

Function Documentation

bool xdrbuf::isValidPackletName

(

IN char

a

)

A name is a single character.

valid names are 'a' - 'z', '$', '*', '?', '!', '='

ePackletType xdrbuf::PackletHeader::getType

(

void

)

const throw () [inherited]

return the datatype contained in this packlet

Definition at line 731 of file xdrbuf.cpp.

int xdrbuf::PackletHeader::getDataCount

(

void

)

const throw () [inherited]

return count (count, not size!) , based on packlet type

• String: returns length of string (NOT counting null-terminator)
• Floats: returns count of floats
• Int32s: returns count of longs

Definition at line 758 of file xdrbuf.cpp.

xdrbuf::PackletHeader::PackletHeader

(

void

)

throw () [protected, inherited]

void xdrbuf::PackletHeader::setData

(

IN word_t

d

)

[inline, protected, inherited]

Definition at line 137 of file xdrbuf.h.

virtual void xdrbuf::Output::clear

(

void

)

[pure virtual, inherited]

virtual int xdrbuf::Output::getRemainingBytes

(

void

)

const throw () [pure virtual, inherited]

virtual void xdrbuf::Output::openPacklet

(

IN char

name

)

[pure virtual, inherited]

create (open) a parent packlet in the stream

virtual void xdrbuf::Output::closePacklet

(

IN char

name

)

[pure virtual, inherited]

close an open (parent) packlet

virtual void xdrbuf::Output::addStringPacklet	(	IN char	name,
		IN const char *	s,
		IN int	length
	)			[pure virtual, inherited]

add a string packlet to the stream

virtual void xdrbuf::Output::addFloatPacklet	(	IN char	name,
		IN const float *	data,
		IN int	nFloats
	)			[pure virtual, inherited]

add a float packlet (array of floats) to the stream

virtual void xdrbuf::Output::addInt32Packlet	(	IN char	name,
		IN const int32_t *	data,
		IN int	nInts
	)			[pure virtual, inherited]

add an int32 packlet (array of int32_t's) to the stream

virtual const byte_t* xdrbuf::Output::getData

(

void

)

throw () [pure virtual, inherited]

retrieve raw data from buffer (called after all streaming is done)

virtual int xdrbuf::Output::getDataBytes

(

void

)

const throw () [pure virtual, inherited]

smart_ptr< Output > xdrbuf::Output::create

(

IN int

bytes

)

[static, inherited]

Definition at line 775 of file xdrbuf.cpp.

virtual void xdrbuf::Input::reset	(	IN const byte_t *	stream,
		IN int	bytes
	)			[pure virtual, inherited]

provide stream reading object with the raw data to use.

WARNING: the Input class does not make a copy of the input buffer! The caller needs to ensure that the input buffer lives as long as the Input object.

virtual bool xdrbuf::Input::endOfStream

(

void

)

[pure virtual, inherited]

have we read all data?

virtual PackletHeader xdrbuf::Input::getNextPackletHeader

(

void

)

[pure virtual, inherited]

retrieves the next packlet header (fails if not at a packlet header)

virtual void xdrbuf::Input::readInt32s	(	OUT int32_t *	buffer,
		IN int	count
	)			[pure virtual, inherited]

read int32s (fails if you didn't just read an Int32 packlet header)

virtual void xdrbuf::Input::readFloats	(	OUT float *	buffer,
		IN int	count
	)			[pure virtual, inherited]

read floats (fails if you didn't just read a float packlet header)

virtual void xdrbuf::Input::readString	(	OUT char *	buffer,
		IN int	length
	)			[pure virtual, inherited]

read strings (fails if you didn't just read a string packlet header)

smart_ptr< Input > xdrbuf::Input::create

(

void

)

[static, inherited]

Definition at line 793 of file xdrbuf.cpp.

xdrbuf::Output::~Output

(

void

)

throw () [virtual, inherited]

Definition at line 42 of file xdrbuf.cpp.

---

Variable Documentation

word_t xdrbuf::PackletHeader::m_data [protected, inherited]

Definition at line 139 of file xdrbuf.h.