Classes | Enumerations | Enumerator | Functions | Variables

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 (word_t d)
virtual void xdrbuf::Output::clear (void)=0
virtual int xdrbuf::Output::getRemainingBytes (void) const =0 throw ()
virtual void xdrbuf::Output::openPacklet (char name)=0
 create (open) a parent packlet in the stream
virtual void xdrbuf::Output::closePacklet (char name)=0
 close an open (parent) packlet
virtual void xdrbuf::Output::addStringPacklet (char name, const char *s, int length)=0
 add a string packlet to the stream
virtual void xdrbuf::Output::addFloatPacklet (char name, const float *data, int nFloats)=0
 add a float packlet (array of floats) to the stream
virtual void xdrbuf::Output::addInt32Packlet (char name, const int32_t *data, int nInts)=0
 add an int32 packlet (array of int32_t's) to the stream
virtual const byte_txdrbuf::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 (const byte_t *stream, 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 (int32_t *buffer, int count)=0
 read int32s (fails if you didn't just read an Int32 packlet header)
virtual void xdrbuf::Input::readFloats (float *buffer, int count)=0
 read floats (fails if you didn't just read a float packlet header)
virtual void xdrbuf::Input::readString (char *buffer, 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 (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 (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

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 ( 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 ( 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 ( char  name  )  [pure virtual, inherited]

create (open) a parent packlet in the stream

virtual void xdrbuf::Output::closePacklet ( char  name  )  [pure virtual, inherited]

close an open (parent) packlet

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

add a string packlet to the stream

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

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

virtual void xdrbuf::Output::addInt32Packlet ( char  name,
const int32_t *  data,
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 ( int  bytes  )  [static, inherited]

Definition at line 775 of file xdrbuf.cpp.

virtual void xdrbuf::Input::reset ( const byte_t stream,
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 ( int32_t *  buffer,
int  count 
) [pure virtual, inherited]

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

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

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

virtual void xdrbuf::Input::readString ( char *  buffer,
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.