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

/home/tetron/hack/vos/libs/vos/vos/vobjectevent.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 _VOBJECTEVENT_HH_
#define _VOBJECTEVENT_HH_

/** @file
    Defines ChildChangeListener, ParentChangeListener, and TypeChangeListener.
*/

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

#include <string>

namespace VOS
{
    class Vobject;
    class ChildChangeListener;
    class ParentChangeListener;
    class TypeChangeListener;

/** @class VobjectEvent vobjectevent.hh vos/vos/vobjectevent.hh
    @ingroup libvos

    This class describes an event changing the state of a Vobject.
    This event has either been requested to happen or has already
    happened, depending respectively on whether it is supplied as part
    of an access control callback or a listener notification callback.
    @note A VobjectEvent is a reference counted object.  This means
    that you may keep a reference to an event which has been passed to
    you if you increment its count with acquire() and/or use vRef<>.
 */
    class VOS_API VobjectEvent : public VUtil::RefCounted
{
public:
    typedef enum {TypeInsert, TypeRemove, ParentInsert, ParentRemove,
                  ChildInsert, ChildReplace, ChildRemove,
                  ReadChild, ReadParent, ReadType,
                  ChildrenListen, ParentListen, TypeListen,
                  ReadACL, AddToACL, RemoveFromACL, DeleteACL, SetDefaultPolicy} EventType;
private:
    EventType event;
    Vobject* initiator;
    Vobject* from;
    int position;
    std::string newstring; // used for both contextual name and new type events
    Vobject* newchild;
    Vobject* oldchild;
public:
    /** Construct a ReadChild, ReadParent, ChildInserted,
        ChildRemoved, ParentInserted or ParentRemoved event.

        @param et The type of event that occured
        @param init The object which caused this event to occur
        @param fromobj The parent object involved
        @param pos The position of the child object in question
        @param contextname The contextual name of the child object in question
        @param childobj The child object involved
     */
    VobjectEvent(EventType et, Vobject* init,
                 Vobject& fromobj, int pos, const std::string& contextname,
                 Vobject& childobj);

    /** Construct a ChildReplaced event.
        @param et The type of event that occured
        @param init The object which caused this event to occur
        @param fromobj The parent object
        @param pos The position of the child object in question
        @param contextname The contextual name of the child object in question
        @param newobj The new child at this position
        @param oldobj The old child at this position
     */
    VobjectEvent(EventType et, Vobject* init,
                 Vobject& fromobj, int pos, const std::string& contextname,
                 Vobject& newobj, Vobject& oldobj);

    /** Construct a ReadType, TypeInserted, TypeRemoved or RemoveACL event.
        @param et The type of event that occured
        @param init The object which caused this event to occur
        @param fromobj The parent object of this child change event
        @param str The newly added type string for Type events, or the ACL for RemoveACL event
    */
    VobjectEvent(EventType et, Vobject* init,
                 Vobject& fromobj, const std::string& str);

    /** Construct a ChildrenListen, ParentListen  TypeListen or ReadACL event
        @param et The type of event that occured
        @param requester The object which wants to start listening or do the read
        @param fromobj The object that will be listened to or read from
    */
    VobjectEvent(EventType et, Vobject* requester,
                 Vobject& fromobj);

    /** Construct an AddToACL or RemoveFromACL event
        @param et The type of event that occured
        @param requester The object which wants to make the change
        @param fromobj the object on which the security is changing
        @param acl the access control list to change
        @param aclmember The identity or group that will be added or removed from the ACL
    */
    VobjectEvent(EventType et, Vobject* requester,
                 Vobject& fromobj, const std::string& acl,
                 Vobject& aclmember);

    virtual ~VobjectEvent();

    /** @return What type of event this is. */
    EventType getEvent() { return event; }

    /** @return The object which requested or initiated this event.
        May be null.  For access control checks, this is the object
        which is requesting access.
     */
    VUtil::vRef<Vobject> getInitiator() { return VUtil::vRef<Vobject>(initiator, true); }

    /** @return The parent Vobject being changed.  Always a vaild
        object. */
    VUtil::vRef<Vobject> getParent() { return VUtil::vRef<Vobject>(from, true); }

    /** @return The Vobject which is changing state. Always a valid
        object.
    */
    VUtil::vRef<Vobject> getAffectedObject() { return VUtil::vRef<Vobject>(from, true); }

    /** @return The child Vobject which was affected on a ParentInsert
        or ParentRemove event, or the requested object to read on a
        ReadChild event.  Will be NULL for TypeInsert, TypeRemove and
        all Listen events. */
    VUtil::vRef<Vobject> getChild() { return VUtil::vRef<Vobject>(newchild, true); }

    /** @return The identity or group to be added or removed on a
        AddToACL or RemoveFromACL event.  */
    VUtil::vRef<Vobject> getACLMember() { return VUtil::vRef<Vobject>(newchild, true); }

    /** @return The child Vobject which was newly added on a
        ChildInsert or ChildReplace event.  Will be NULL for
        ChildRemove, TypeInsert, TypeRemove and all Read and Listen
        events. */
    VUtil::vRef<Vobject> getNewChild() { return VUtil::vRef<Vobject>(newchild, true); }

    /** @return The previous Vobject occupying this position.  Only
        valid for ChildRemove and ChildReplace events, NULL otherwise.
    */
    VUtil::vRef<Vobject> getOldChild() { return VUtil::vRef<Vobject>(oldchild, true); }

    /** @return The absolute position of the child Vobject in parent, or -1 if this is a
        TypeInserted or TypeRemoved event.*/
    int getPosition() { return position; }

    /** @return The contextual name of the child Vobject. */
    const std::string& getContextualName() { return newstring; }

    /** @return The added or removed type for type change events. */
    const std::string& getNewType() { return newstring; }
    /** @return The added or removed type for type change events. */
    const std::string& getType() { return newstring; }
    /** @return The added or removed type for type change events. */
    const std::string& getOldType() { return newstring; }

    /** @return The access control list being changed.. */
    const std::string& getAffectedACL() { return newstring; }

    void deliverTo(ChildChangeListener* ccl);

    void deliverTo(TypeChangeListener* ccl);

    void deliverTo(ParentChangeListener* ccl);
};

}

#endif