vos/metaobjects/misc/cod.hh

Go to the documentation of this file.

#ifndef _COD_HH_
#define _COD_HH_

#include <vos/corelibs/vos/vos.hh>

#ifdef HAVE_STDINT_H
# include <stdint.h>
#else
# ifdef HAVE_INTTYPES_H
#  include <inttypes.h>
# else
   typedef unsigned char uint8_t;
   typedef unsigned short int uint16_t;
   typedef unsigned long int uint32_t;
# endif
#endif

#if defined(_WIN32) && defined(_MSC_VER)
# ifdef MISC_EXPORTS
#  define MISC_API __declspec(dllexport)
# else
#  define MISC_API __declspec(dllimport)
# endif
#else
# define MISC_API
#endif

/** COD stands for Compact Object Description.  It is a binary file
    format for saving and loading Vobjects, and (in the form of the
    RemoteCOD subclass) is also used for efficient batch downloads of
    the state of many remote vobjects. */
class MISC_API COD
{
public:
    /** An entry in the COD Vobject table */
    struct Entry
    {
        /** The Vobject itself. */
        Vobject* vobject;

        /** The type strings to save. */
        set<string> types;

        /** A list of messages which, when replayed, will restore the state
            of this Vobject. */
        MessageBlock* mb;

        /** For Remote CODs: the position of this object on the
            @em remote site. */
        int pos;

        /** Should this vobject's child table be written out? */
        bool savechildren;
    };

protected:
    struct PCR
    {
        string context;
        string child;
    };

    iostream* f;
    LocalSite& ls;

    map<string, Entry*> vobjectTable;
    deque<Entry*> vobjectorder;

    unsigned int offset;
    unsigned int buffersize;
    unsigned char* buffer;

public:
    class eof : public runtime_error {
    public:
        eof() : runtime_error("COD end of file") { };
    };


protected:
    void write(const char* data, unsigned int size);
    void write(const unsigned char* data, unsigned int size);

    void read(char* data, unsigned int size);
    void read(unsigned char* data, unsigned int size);

    virtual int writeObjectDesc(Entry* v, bool doWrite = true);
    virtual int writeObjectChildren(Vobject* v, bool doWrite = true);

    virtual string readStr();
    virtual unsigned short int readShort();
    virtual unsigned long readLong();
    virtual void readObjectDesc(string& name, long& pos, deque<string>& types, MessageBlock& mb);
    virtual void readObjectChildren(string& parent, deque<PCR>& children);
    virtual bool checkCOD();

public:

    /** Constructor. Does not initialize with an iostream, so you will
        have to supply a buffer when you call readCOD or writeCOD.
        @param ls The local site any new vobjects will be created on.
     */
    COD(LocalSite& ls);

    /** Constructor.
        @param io the io stream to read from or write to
        @param ls The local site any new vobjects will be created on.
     */
    COD(iostream& io, LocalSite& ls);

    /** Destructor. */
    virtual ~COD();

    /** Write the current COD to the initialized iostream. */
    virtual void writeCOD(bool gzipped = true);

    /** Write the current COD to a buffer.  The buffer is malloc()'d
        by writeCOD and returned via the supplied parameters.
        @param buffer the data buffer holding the COD data.  You
        should free() this when you're done.
        @param size the size of the buffer
    */
    virtual void writeCOD(unsigned char** buffer, unsigned int* size, bool gzipped = true);

    /** Read a COD from the initialized iostream */
    virtual void readCOD();

    /** Read the COD from the supplied data buffer.
        @param buffer the source data
        @param size the length of the data
    */
    virtual void readCOD(unsigned char* buffer, unsigned int size);

    /** Computes the output size of the COD
        @return the number of bytes needed to store this COD
    */
    virtual int computeSize();

    /** Change the iostream to use. */
    virtual void setStream(iostream& io);

    /** Add a Vobject to this COD.
        @param v the Vobject
        @param portable passed to Vobject::saveState -- should this
        COD save site- or configuration-specific information (possibly
        making for a smaller COD) or embed all necessary data?
        @param saveChildren should the child list be saved in this COD?
        @return the position of this entry in the COD's vobject table
        @note This will use Vobject::saveState to get additional details
    */
    virtual int addVobject(Vobject* v, bool portable, bool saveChildren);

    /** Add a Vobject to this COD.  This uses the supplied values,
        overriding the information stored in the Vobject itself.  It does not
        call Vobject::saveState()
        @param v the Vobject
        @param types the type strings to be saved
        @param mb a message block of messages used to restore the
        state of this Vobject
        @param saveChildren should the child list be saved in this COD?
        @return the position of this entry in the COD's vobject table
    */
    virtual int addVobject(Vobject* v, const set<string>& types, MessageBlock* mb, bool saveChildren);

    /** Add a Vobject to this COD.  This uses the supplied values,
        overriding the information stored in the Vobject itself.  It does not
        call Vobject::saveState()
        @param v the Vobject
        @param types the type strings to be saved
        @param mb a message block of messages used to restore the
        state of this Vobject
        @param saveChildren should the child list be saved in this COD?
        @return the position of this entry in the COD's vobject table
    */
    virtual int addVobject(Vobject* v, const deque<string>& types, MessageBlock* mb, bool saveChildren);

    /** Number of Vobjects in the COD Vobject table.
        @return the table size
    */
    virtual int numVobjects();

    /** Get the Vobject from the COD Vobject table by site name.
        @param name the site name
        @return the entry, or NULL if invalid
    */
    virtual Entry* getVobject(const string& name);

    /** Get the Vobject by position in the COD Vobject table.
        @param pos the position
        @return the entry, or NULL if invalid
     */
    virtual Entry* getVobject(int pos);

    /** Remove a Vobject from the COD Vobject table.
        @param name the site name
    */
    virtual void removeVobject(const string& name);

    /** Remove a Vobject from the COD Vobject table.
        @param pos the position in the COD Vobject table
    */
    virtual void removeVobject(int pos);

    /** Clear the COD Vobject table. */
    virtual void clear();

    /** Get the default local site.
        @return the local site NOTE you should assign this to a vRef<>
        or call release when you're done! */
    virtual LocalSite& getLocalSite();

    /** A utility function which writes some variables to the supplied
        buffer, following the format string.  The values are written
        in network byte order (big-endian).  The format string
        supports the following data types:

        'c': a char, or single byte

        's': a short, or 16 bit integer

        'l': a long, or 32 bit integer

        'S': a string.  This must actually be passed in as two values,
        first the length (a 16 bit unsigned integer) and then a char*
        to the actual character data.  The string is packed using a
        leading 16 bit length followed by the string data.

        'f': a 32-bit IEEE floating point number

        @param buf the buffer to write to
        @param maxsize the maximum size of the buffer, to avoid overflows
        @param fmt the format string
        @param ... the values to be written to the buffer
        @return the number of bytes written to the buffer, which will
        always be <= maxsize
        @note Here's an example of using pack:
        @code
char c = 'Q';
short int s = 42;
long int l = 999999;
char* S = "Foo Bar Baz";
float f = 3.21;
char buffer[256];

int length = pack(buffer, sizeof(buffer), "cslSf", c, s, l, strlen(S), S, f);
        @endcode
    */
    static int pack(uint8_t *buf, int maxsize, char *fmt, ...);

    /** A utility function that reads some values from a packed data
        buffer.  It is symmetric to the unpack() function.  The only
        major difference being that pointers to variables are
        passed in to which the unpacked values will be assigned.
        @param buf the buffer to read from
        @param the maximum size of the buffer, to avoid overruns
        @param fmt the format string
        @param ... pointers to variables to store the unpacked contents
        @return the number of bytes read
        @note Here's an example of using unpack:
        @code
char* buffer = getSomeData();
int buffersize = getSomeDataLength();

char c;
short int s, strsize;
long int l;
char* S;
float f;

int length = unpack(buffer, buffersize, "cslSf", &c, &s, &l, &strsize, &S, &f);
        @endcode
     */
    static int unpack(const uint8_t *buf, int maxsize, char *fmt, ...);

    static void gzipUncompress(unsigned char** dest, unsigned int* destlen, const unsigned char* source, unsigned int srclen);
    static void gzipCompress(unsigned char** dest, unsigned int* destlen, const unsigned char* source, unsigned int srclen);
};

/** The contents of a remote COD represent live objects on a remote
    site, rather than a save state which is to be loaded locally.  In
    particular, this means that the objects are created and messages
    delivered as updates to RemoteVobjects.
*/
class RemoteCOD : public COD
{
protected:
    RemoteSite& rs;

public:
    /** Constructor. Does not initialize with an iostream, so you will
        have to supply a buffer when you call readCOD or writeCOD.
        @param ls Our local site
        @param rs The remote site the objects are associated with
     */
    RemoteCOD(LocalSite& ls, RemoteSite& rs);

    /** Constructor.
        @param io the io stream to read from or write to
        @param ls Our local site
        @param rs The remote site the objects are associated with
     */
    RemoteCOD(iostream& io, LocalSite& ls, RemoteSite& rs);

    /** Destructor */
    virtual ~RemoteCOD();

    /** @return the remote site this objects are associated with */
    virtual RemoteSite& getRemoteSite();

    /** Read the remote COD from the supplied iostream */
    virtual void readCOD();

    /** Read the remote COD from the supplied buffer
        @param buffer a data buffer with the COD contents
        @param size the size of the buffer
    */
    virtual void readCOD(unsigned char* buffer, unsigned int size)
        { COD::readCOD(buffer, size); }
};

#endif

---