xdrbuf.h

Go to the documentation of this file.

/*
 * xdrbuf.h
 *
 * Copyright (c) 2008,2009 Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * Wrapper API to create and read/write XDR buffers for interprocess/network
 * communication.
 */

#ifndef WAVEPACKET_XDRBUF_H__
#define WAVEPACKET_XDRBUF_H__


// includes --------------------------------------------------------------------
#include "common/common.h"
#include "threadsafe/smart_ptr.h"


namespace xdrbuf {

// doxygen block

////////////////////////////////////////////////////////////////////////////////
///
/// \ingroup networking
/// \defgroup xdrbuf XDR Buffer APIs
///
/// \n
/// 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".
///
/// \b 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.
///
///\n
/// 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.
///
////////////////////////////////////////////////////////////////////////////////
/*@{*/


/// these are the types of data supported by packlets
enum ePackletType {
        ePacklet_Reserved       = 0,    ///< don't use this
        ePacklet_ParentBegin    = 1,    ///< packlet contains other packlets
        ePacklet_ParentEnd      = 2,    ///< end of parent packlet
        ePacklet_String         = 3,    ///< packlet contains a single string
        ePacklet_Floats         = 4,    ///< packlet contains list of floats
        ePacklet_Int32s         = 5,    ///< packlet contains list of int32s

        // must be last!
        ePacklet_Invalid        = 8
};



/// A name is a single character.
/// valid names are 'a' - 'z', '$', '*', '?', '!', '='
bool isValidPackletName(IN char a);



/// A PackletHeader describes a given packlet (what sort of data it is,
///     and how much data is there).
class PackletHeader {
public:
        // xdrbuf::PackletHeader class methods ---------------------------------

        /// return the (single-character) name for this packlet
        char getName(void) const throw();

        /// return the datatype contained in this packlet
        ePackletType getType(void) const throw();

        /// return count (count, \e not size!) , based on packlet type
        ///  - \b String: returns length of string (NOT counting null-terminator)
        ///  - \b Floats: returns count of floats
        ///  - \b Int32s:  returns count of longs
        int getDataCount(void) const throw();

protected:
        PackletHeader(void) throw();
        void setData(IN word_t d) { m_data = d; }

        word_t          m_data;
};




/// class for writing data to the network
class Output {
public:
        // virtual destructor --------------------------------------------------
        virtual ~Output(void) throw();

        // xdrbuf::Output class interface methods ------------------------------
        virtual void clear(void) = 0;
        virtual int getRemainingBytes(void) const throw() = 0;

        /// create (open) a parent packlet in the stream
        virtual void openPacklet(IN char name) = 0;

        /// close an open (parent) packlet
        virtual void closePacklet(IN char name) = 0;

        /// add a string packlet to the stream
        virtual void addStringPacklet(IN char name,
                                IN const char * s,
                                IN int length) = 0;

        /// add a float packlet (array of floats) to the stream
        virtual void addFloatPacklet(IN char name,
                                IN const float * data,
                                IN int nFloats) = 0;

        /// add an int32 packlet (array of int32_t's) to the stream
        virtual void addInt32Packlet(IN char name,
                                IN const int32_t * data,
                                IN int nInts) = 0;

        /// retrieve raw data from buffer (called after all streaming is done)
        virtual const byte_t * getData(void) throw() = 0;
        virtual int getDataBytes(void) const throw() = 0;

        // static factory methods ----------------------------------------------
        static smart_ptr<Output> create(IN int bytes);
};



/// class for reading data from the network
class Input {
public:
        // virtual destructor --------------------------------------------------
        virtual ~Input(void) throw();

        // xdrbuf::Input class interface methods -------------------------------

        /// provide stream reading object with the raw data to use.  \b 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 void reset(IN const byte_t * stream,
                                IN int bytes) = 0;

        /// have we read all data?
        virtual bool endOfStream(void) = 0;

        /// retrieves the next packlet header (fails if not at a packlet header)
        virtual PackletHeader getNextPackletHeader(void) = 0;

        /// read int32s (fails if you didn't just read an Int32 packlet header)
        virtual void readInt32s(OUT int32_t * buffer,
                                IN int count) = 0;

        /// read floats (fails if you didn't just read a float packlet header)
        virtual void readFloats(OUT float * buffer,
                                IN int count) = 0;

        /// read strings (fails if you didn't just read a string packlet header)
        virtual void readString(OUT char * buffer,
                                IN int length) = 0;

        // static factory methods ----------------------------------------------
        static smart_ptr<Input> create(void);
};



};      // xdrbuf namespace

/*@}*/  // end of documentation block

#endif  // WAVEPACKET_XDRBUF_H__