vos/corelibs/vos/messageblock.hh

Go to the documentation of this file.

/*
    This file is part of the Virtual Object System of
    the Interreality project (http://interreality.org).

    Copyright (C) 2001-2003 Peter Amstutz

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA

    Peter Amstutz <tetron@interreality.org>
*/

#ifndef _MESSAGEBLOCK_HH_
#define _MESSAGEBLOCK_HH_

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

#include <iostream>
#include <deque>


namespace VOS
{
    class MessageBlock;
    class Message;

/**
    Stores some state information needed between calls to the Message parser, when
    a message has only been partially parsed.
    @internal
 */
struct parse_state_t
{
    MessageBlock* m;
    unsigned int chars_read;
    unsigned int expected_length;
    bool done;
    void* extra;
    int read_quoted;
    std::istream* input;
};

/**  @class MessageBlock messageblock.hh vos/corelibs/vos/messageblock.hh
 *
 * A message block is a list of messages which have been bundled
     together into a single block.  It is used for various purposes.
     One useful feature of a message block is that it is processed all
     at once: the first message will not be delivered until the entire
     message block has been received, parsed and queued.  This is be
     useful for supporting transactions.
 */
class VOS_API MessageBlock : public virtual RefCounted
{
private:
    deque<Message*> messages;
    int expected_length;
    string* formattedString;
    string parse_buffer;
    parse_state_t parsestate;
    string name;
public:
    MessageBlock();
    ~MessageBlock();

    /** Set the message block macro name, which can then be refered
        back to later in a message using &lt;include&gt;.  If this is blank, the message
        block will not be used as a macro template.
        @param s the name
    */
    void setName(const string& s);

    /** Get the macro name.
        @return the macro name
    */
    string getName();

    /** Add a message to the message block.
        @param n The position to insert into.  May be negative, in which case the position
        will be counted from the end.  To append to the end, use -1.
        @param m the message to insert
    */
    void insertMessage(int n, Message* m);

    /** Remove a message from the message block.
        @param n The position to remove.
    */
    void removeMessage(int n);

    /** Retrieve a message from this messageblock.
        @param n The desired position.  May be negative, in which case
        the position will be counted from the end.  The very
        last element can be accessed using -1.
        @return The message at the desired position, or 0 if the index is invalid.
        NOTE YOU MUST CALL release() WHEN DONE OR USE vRef.
    */
    Message* getMessage(int n);

    /** Convenience function returns the last message in this messageblock.
        @return The last message 0 if the message block is empty.
        NOTE YOU MUST CALL release() WHEN DONE OR USE vRef.
    */
    Message* lastMessage();

    /** Get the number of messages in the messageblock.
        @return the number of messages in the messageblock.
    */
    int numMessages();

    /** Get the XML-like textual representation of this messageblock,
        suitable for sending over the network.
     */
    const string& getString();

    /** Internal parsing function.  Update the current partial parse of this messageblock with new data.
        @param s the new data
        @return The number of bytes from the beginning of 's' which
        were read in.  However, 0 is special: rather than
        meaning that nothing was read in, this indicates that the
        ENTIRE string was read in, but more data is still expected.
    */
    int parseUpdate(const string& s);
};

/** Bison driver for XML parser. 
 * @internal
 */ 
int msgparse(void* lexer);

/** Bison callback for XML parser. 
 * @internal
 */
int msglex(char** lvalp, void* lexer);

/** Bison callback for XML parser. 
 * @internal */
void msgerror(char* blah);
}

#endif

---