[Home]	[About]
[Screenshots]	[Download]
[News]	[Community]
[Documentation]	[Manual]
[Bugs & Requests]	[Wiki]

/home/tetron/hack/vos/libs/vos/vos/message.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 <http://www.interreality.org>
*/
#ifndef _MESSAGE_HH_
#define _MESSAGE_HH_

#include <stdexcept>
#include <string>
#include <deque>
#include <iostream>

#include <vos/vos/vosdefs.hh>
#include <vos/vutil/refcount.hh>
#include <vos/vos/site.hh>

/** @file
    Defines Message.
*/

namespace VOS
{
    class Site;
    class MessageContext;
    class Vobject;

    /** @class NoSuchFieldError message.hh vos/vos/message.hh
        @ingroup libvos
        Thrown when getField() is passed an out-of-range parameter
    */
    class VOS_API NoSuchFieldError : public std::runtime_error {
    public:
        NoSuchFieldError(const std::string& s) : std::runtime_error(s) { };
        static const char* errorCode() { return "400"; }
    };

    /**
     */
    struct VOS_API SendingCompletedCallback
    {
        virtual ~SendingCompletedCallback() { }
        virtual void notifySendingCompleted(VOS::Message* m) = 0;
    };

    /** @class MsgField message.hh vos/vos/message.hh
        @ingroup libvos
        A key-value field pair used to store the fields of a Message
    */
    class VOS_API MsgField : public VUtil::RefCounted {
    public:
        MsgField(const std::string& k, const std::string v, bool q) : key(k), value(v), quoted(q) { };
        std::string key; /**< the key or tag for this field */
        std::string value; /**< the value of this field */
        bool quoted;

        const std::string &getKey()
            { return key; }
        const std::string &getValue()
            { return value; }

        bool operator==(const MsgField &otherfield) const
            {
                return (this->key == otherfield.key
                        && this->value == otherfield.value
                        && this->quoted == otherfield.quoted);
            }
        bool operator!=(const MsgField &otherfield) const
            { return !operator==( otherfield ); }
    };

/** @class Message message.hh vos/vos/message.hh
    @ingroup libvos

    This class handles storing, generating and parsing of the messages
    that are sent between virtual objects.
 */
class VOS_API Message : public VUtil::RefCounted
{
public:
    enum Priority { Normal, LowLatency, Bulk };
private:
    mutable boost::mutex message_mutex;

    std::string type;
    std::string to;
    std::string from;
    std::string method;
    uint32_t nonce;
    std::string timestamp;

    VUtil::vRef<Site> source_site;
    mutable std::string* formattedString;
    std::deque< VUtil::vRef<MsgField> > fields;

    std::string* (*format_func)(const std::string& type,
                                const std::string& to,
                                const std::string& from,
                                const std::string& method,
                                uint32_t nonce,
                                const std::string& timestamp,
                                const std::deque< VUtil::vRef<MsgField> >& fields,
                                bool withLength);

    Priority priority;
    SendingCompletedCallback* sendComplete;

public:
    /** Create a new message. */
    Message();

    /** Initialize this message.  Will set the message type as
        "message", set the "to" field to v->getURLstr(), set
        the method field with the supplied method, and optionally
        generate a random value for the nonce field.
        @param v used to set the "to" field
        @param method used to set the "method" field
        @param withnonce if true, generate a random string for the nonce field
    */
    Message(Vobject* v, const std::string& method, bool withnonce,
            Priority priority = Normal);

    /** Initialize this message as a reply to a message.  Will set the
        message type as "update", set "to" using
        in_reply_to->getFrom(), set "from" using v->getURLstr(), and
        set the nonce using in_reply_to->getNonce(), and set the
        method to the supplied.
        @param v used to initialize the "from" fields
        @param in_reply_to used to initalize the "to" and "nonce" fields
        @param method used to initialize the "method" field
    */
    Message(Vobject* v, Message* in_reply_to, const std::string& method,
            Priority priority = Normal);

    /** Copy a message. */
    Message(Message& m);

    /** Destroy this message. */
    ~Message();

    /** Set what type of message this is.  You probably want it to be either
        "message" or "update".
        @param s the types
    */
    void setType(const std::string& s);

    /** Set whom this message is intended for.  This should probably
        be the URL std::string of the object to which the message is destined.
        @param s the to field
    */
    void setTo(const std::string& s);

    /** Set whom this message is sent by.  This should probably
        be the URL std::string of the object which is generating this message.
        @param s the from field
    */
    void setFrom(const std::string& s);

    /** Set the method action this message is expressing.
        @param s the method field
    */
    void setMethod(const std::string& s);

    /** Set the nonce field.  The nonce is used to match a match a
        reply against a request (because the reply bears the same
        nonce as the originating message.)
        @param s the nonce field
    */
    void setNonce(uint32_t n);

    /** Set the timestamp (optional, useful for applications, not
        actually used by VOS core).
        @param s the timestamp field
    */
    void setTimestamp(const std::string& s);

    /** Set the source site.  This is not a field in the message
        itself, but rather is used to set the site originating this
        message (that is to say, which socket the message was received
        on.)  This is compared against the "from" field to provide a
        simple filter against really obvious spoofing.  You do not
        need to set this if you are creating a new message to be sent;
        rather it is set for messages received from the network.
        @param source_site the source site
    */
    void setSourceSite(Site* source_site);

    /** @return the type field.  setType() has a bit more information about this field. */
    std::string getType() const;

    /** Get the to field.
        @return the to field  setTo() has a bit more information about this field. */
    std::string getTo() const;

    /** Get the from field.
        @return the from field  setFrom() has a bit more information about this field. */
    std::string getFrom() const;

    /** Get the method field.
        @return the method field  setMethod() has a bit more information about this field. */
    std::string getMethod() const;

    /** Get the nonce field.
        @return the nonce field  setNonce() has a bit more information about this field. */
    uint32_t getNonce() const;

    /** Get the timestamp field.
        @return the timestamp field  setTimestamp() has a bit more information about this field. */
    std::string getTimestamp() const;

    /** Get whether there is anything in the to field.
        @return if there is a to field  setTo() has a bit more information about this field. */
    bool hasTo() const;

    /** Get whether there is anything in the from field.
        @return if there is a from field  setFrom() has a bit more information about this field. */
    bool hasFrom() const;

    /** Get whether there is anything in the method field.
        @return if there is a method field  setMethod() has a bit more information about this field. */
    bool hasMethod() const;

    /** Get whether there is anything in the nonce field.
        @return if there is a nonce field  setNonce() has a bit more information about this field. */
    bool hasNonce() const;

    /** Get whether there is anything in the timestamp field.
        @return if there is a timestamp field  setTimestamp() has a bit more information about this field. */
    bool hasTimestamp() const;

    /** Get the source site.  This is the site that actually generated
        this message.  MAY BE ZERO IF THE MESSAGE WAS GENERATED
        LOCALLY.  If so, you'll need to do the following to determine
        the source site:
        Site::findSite(URL(themsg.getFrom()).getHostAndPort())
        @return the source site
    */
    VUtil::vRef<Site> getSourceSite() const;

    /** Get the number of ordinary fields.
        @return the number of ordinary fields in this message */
    int numFields() const;

    /** Have the message fill in the nonce field with a random nonce. */
    void generateNonce();

    bool hasField(const std::string& key) const;

    /** Get the first field which matches the supplied key.  Note that
        this field list is SEPARATE from the type/to/from/method/nonce
        fields.
        @param key the tag to match
        @return the first instance of a field which matchs that tag
        @throw NoSuchFieldError if the field is not found
    */
    VUtil::vRef<MsgField> getField(const std::string& key) const;

    /** Get the first field which matches the supplied key.  Note that
        this field list is SEPARATE from the type/to/from/method/nonce
        fields.
        @param n the field at position n, where n is the array offset from 0.
        @return the first instance of a field which matchs that tag
        @throw NoSuchFieldError if the field is not found
    */
    VUtil::vRef<MsgField> getField(int n) const;

    /** Insert a new field.
        @note On positions: if a position is zero or positive, its
        meaning is as you would expect, expressing the offset into an
        array of fields.  However, if the position is negative, it
        expresses the offset from the end of the list.  This means for
        a list of length m, -1 is the last item in the list (equal to
        position position m - 1) and -m is the first item (equal to
        positive position 0).  If the position is positive, the field
        is inserted such that it now occupies that position, and all
        fields starting from the previous occupant of that position
        onward are moved up one.  If the position in negative, the
        field is similarly inserted so that it now occupies that
        position.  For example, position -1 will append the field to
        the end of the list, position -2 will insert the field in the
        second-to-last position, etc.
        @param n the position, as explained above
        @param key the key (or tag) to associate the value with
        @param val the value of this field
        @param quoted not really used and should be removed...
    */
    void insertField(int n, const std::string& key, const std::string& val, bool quoted = false);

    /** Insert a new field.
        @copydoc insertField(int n, const std::string& key, const std::string& val, bool quoted = false)
        @param n the position, as explained above
        @param key the key (or tag) to associate the value with
        @param val the value of this field
    */
    void insertField(int n, const std::string& key, double val);

    /** Insert a new field.
        @param n the position, as explained above
        @param key the key (or tag) to associate the value with
        @param val the value of this field
    */
    void insertField(int n, const std::string& key, int val);

    /** Insert a new field.
        @param n the position, as explained above
        @param key the key (or tag) to associate the value with
        @param val the value of this field
    */
    void insertField(int n, const std::string& key, unsigned int val);

    /** Append a new field.
        @param key the key (or tag) to associate the value with
        @param val the value of this field
        @param quoted not used and should be removed...
     */
    inline void appendField(const std::string& key, const std::string& val, bool quoted = false)
        { insertField(-1, key, val, quoted); }

    /** Append a new field.
        @param key the key (or tag) to associate the value with
        @param val the value of this field
     */
    inline void appendField(const std::string& key, double val)
        { insertField(-1, key, val); }

    /** Append a new field.
        @param key the key (or tag) to associate the value with
        @param val the value of this field
     */
    inline void appendField(const std::string& key, int val)
        { insertField(-1, key, val); }

    /** Remove an existing field at some position.  See insertField()
        for details about the legal numerical values of the position.
        @param n the position
    */
    void removeField(int n);

    /** Remove the first instance of a field with the supplied key.
        @param s the key of the field to remove
    */
    void removeField(const std::string& s);

    /** Clear all the fields of this message added with insertField()
        or appendField().
    */
    void clearFields();

#ifndef SWIG
    /** Set the function which converts this message structure into a
        string.  End users don't need to call this, as it is set to
        the default when the message is constructed.
        @note The more object-oriented way of doing this would be to
        create a function object type.  This interface may change.
    */
    void setFormatFunc(std::string* (*func)(const std::string& type,
                                            const std::string& to,
                                            const std::string& from,
                                            const std::string& method,
                                            uint32_t nonce,
                                            const std::string& timestamp,
                                            const std::deque< VUtil::vRef<MsgField> >& fields,
                                            bool withLength));
#endif

    /** Get the message formatted with the function supplied
        in setFormatFunc().
        @return the formatted std::string
    */
    const std::string& getFormattedString(bool withLength = true) const;

    void setPriority(Priority p) { priority = p; }
    Priority getPriority() { return priority; }

    void setSendingCompletedCallback(SendingCompletedCallback* scc);
    SendingCompletedCallback* getSendingCompletedCallback();

    friend class msgFlexLexer;
};

#ifndef SWIG
/** Converts a message into an XML format message */
std::string* xmlFormatting(const std::string& type,
                           const std::string& to,
                           const std::string& from,
                           const std::string& method,
                           uint32_t nonce,
                           const std::string& timestamp,
                           const std::deque< VUtil::vRef<MsgField> >& fields,
                           bool withLength);

std::string* binaryFormatting(const std::string& type,
                                   const std::string& to,
                                   const std::string& from,
                                   const std::string& method,
                                   uint32_t nonce,
                                   const std::string& timestamp,
                                   const std::deque< VUtil::vRef<MsgField> >& fields,
                                   bool withLength);
#endif

}

#endif