vos/metaobjects/property/property.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, 2002 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>
    Additions by Reed Hedges <reed@zerohour.net> marked with initials "rh" and date.
*/
#ifndef _PROPERTY_HH_
#define _PROPERTY_HH_

#include <typeinfo>
#include <set>
#include <assert.h>

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


#if defined(_WIN32) && defined(_MSC_VER)
# ifdef PROPERTY_EXPORTS
#  define PROPERTY_API __declspec(dllexport)
# else
#  define PROPERTY_API __declspec(dllimport)
# endif
#else
# define PROPERTY_API
#endif

#include "propertylistener.hh"

class PropertyAccessControl;

/** @class Property property.hh vos/metaobjects/property/property.hh
 *
 *  Property stores data of any type and size.  The Property classes
 *  store this data in two forms: decoded and raw. The raw data is the
 *  data as it exists within the %VOS system. This data may be decoded
 *  according to its datatype before being read out of this class
 *  (then cached). The read(), getLength(), and getDataType() methods
 *  are for the decoded data and final (usually, MIME) type. The
 *  readRaw(), getRawLength() and getRawDataType() methods are for the
 *  raw data. Data is decoded using the TypeChain class. 
 */
class PROPERTY_API Property : public virtual MetaObject, public ObjectExciseListener
{
protected:
// these ought to be private... but converting the
// code would be kinda annoying at this point
    string raw_data;
    string raw_datatype;
    int raw_length;
    string data;
    string datatype;
    int data_length;
    bool decoded;

    Property(MetaObject* superobject);

    Property(MetaObject* superobject, const string& d, const string& dt);

    typedef map<PropertyListener*, PropertyListener*, PropertyListenerSiteWrapper::Cmp> PropertyListenerMap;

    PropertyListenerMap propertyListeners;

    /** write contents of s to a file named filename. */
    static void writeStringToFile(const string& s, const string& filename);

    /** Decodes data if need be */
    virtual void checkDecoded() ;

public:

    /** @name Read and write property data */
    // @{

    /** Get length (bytes) of decoded data. */
    virtual int getLength() ;

    /** Read decoded data into target, possibly performing decode if necesary
     * @see read(string, int, int)
     */
    virtual void read(string& target) ;

    /** Read a substring of decoded data into target, possibly performing decode if necesary
     * @param target    Place data in this string
     * @param start     Byte offset to start reading
     * @param length    Number of bytes to read. If this parameter is -1, read
     *                  until the end of the data.
     */
    virtual void read(string& target, int start, int length) ;

    /** Return decoded data, possibly performing decode if necesary
     * @see read(string, int int)
     */
    virtual string read();

    /** Return substring of decoded data, possibly performing decode if necesary        @see read(string, int int)
     */
    virtual string read(int start, int length) ;

    /** Get length (bytes) of undecoded, raw data. */
    virtual int getRawLength();

    /** Read raw, undecoded data into target. */
    virtual void readRaw(string& target);

    /** Read substring of raw data into target.
        This is the fundamental method which the other
        read() methods are based on, so you only have to override this.
        @param target   The data is copied into this string.
        @param start    Offset (bytes) from which to start reading.
        @param length   Number of bytes to read. If this is -1, read until the end of the data.
     */
    virtual void readRaw(string& target, int start, int length);

    /** Return raw, undecoded data */
    virtual string readRaw();

    /** Return substring of raw, undecoded data */
    virtual string readRaw(int start, int length);

    /** Download property and call notifyPropertyReplaced when done. */
    virtual void asyncRead();

    /** Download property and call notifyPropertyWrite when done. */
    virtual void asyncRead(int start, int length);

    /** Write newdata into property value, starting at byte position start */
    virtual void write(int start, const string& newdata);

    /** Completely change the value and type of data stored in this property.
        @param newdata New data.
        @param newtype The type of the new datatype. If no type identifier was supplied, the previous one is kept.  NOTE: the initial datatype (set by the constructor) is "?" which is (or should be) an invalid value for any application.
    */
    virtual void replace(const string& newdata, const string& newtype = "?");

    /** Return type of decoded data (usually a MIME type) */
    virtual const string getDataType() ;

    /** Return type of raw, undeocded data (a typechain string) */
    virtual const string getRawDataType();

    //@}



    /** @name Utility functions. Use these static methods to help get and
        set subproperties of objects. */
    // @{

    /** Set a subproperty, creating it if necesary named 'propname' of 'on', to 'propval'
     *  @param on   Object to set a subproperty on
     *  @param propname Name of the property to set
     *  @param propval  New value of the property
     *  @param proptype New type for property
     *  @param pac  Property access control to add to the object it it had to be created (If property exists, this argument is ignored)
     */
    static void Property::setProperty(Vobject& on,
                                      const string& propname,
                                      const string& propval,
                                      const string& valtype,
                                      PropertyAccessControl* pac)
        throw (AccessControlError, TypeChain::DecodeError, RemoteError);

    /** Set a subproperty on an object, returning relation between object and property.
     *  @param on   Object to set a subproperty on
     *  @param propname Name of the property to set
     *  @param propval  New value of the property
     *  @param proptype New type for property
     *  @param pac  Property access control to add to the object it it had to be created (If property exists, this argument is ignored)
     *  @return object expressing relation between the object and the property
     */
    static Vobject::ParentChildRelation& Property::setPropertyWithReturn(Vobject& on,
                                                                         const string& propname,
                                                                         const string& propval,
                                                                         const string& valtype,
                                                                         PropertyAccessControl* pac,
                                                                         bool letErrorThrough = false)
        throw (AccessControlError, TypeChain::DecodeError, RemoteError);

    /** Set a subproperty, creating it if necesary named 'propname' of 'on', to 'propval'
     *  @param on   Object to set a subproperty on
     *  @param propname Name of the property to set
     *  @param propval  New value of the property
     *  @param pac  Property access control to add to the object it it had to be created (If property exists, this argument is ignored)
     */
    static void Property::setProperty(Vobject& on,
                                      const string& propname,
                                      double propval,
                                      PropertyAccessControl* pac)
        throw (AccessControlError, TypeChain::DecodeError, RemoteError);

    /** Set a subproperty on an object, returning relation between object and property.
     *  @param on   Object to set a subproperty on
     *  @param propname Name of the property to set
     *  @param propval  New value of the property
     *  @param pac  Property access control to add to the object it it had to be created (If property exists, this argument is ignored)
     *  @return object expressing relation between the object and the property
     *
     *  @todo move these into a specialized class from which MetaObjecs 
     *  using properties can inherit.
     */
    static Vobject::ParentChildRelation& Property::setPropertyWithReturn(
        Vobject& on, const string& propname, double propval,
        PropertyAccessControl* pac)
            throw (AccessControlError, TypeChain::DecodeError, RemoteError);

    static string getProperty(Vobject& on, const string& name);

    static string getProperty(Vobject& on, const string& name, const string& defaultVal);


    static int getIntProperty(Vobject& on, const string& name);

    static int getIntProperty(Vobject& on, const string& name, int defaultVal);

    static int getIntProperty(Vobject& on, const string& name, int lowerLimit,
        int upperLimit);

    static int getIntProperty(Vobject& on, const string& name, int defaultVal,
        int lowerLimit, int upperLimit);

    static void setIntProperty(Vobject& on, const string& name, int val,
        PropertyAccessControl* ac);

    static void setIntProperty(Vobject& on, const string& name, int val,
        int lowerLimit, int upperLimit, PropertyAccessControl* ac);



    static double Property::getFloatProperty(Vobject& on, const string& name,
        double lowLim, double upLim) ;

    static double Property::getFloatProperty(Vobject& on, const string& name,
        double defaultVal, double lowerLimit, double upperLimit) ;

    static double Property::getFloatProperty(Vobject& on, const string& name,
        double defaultVal) ;

    static double Property::getFloatProperty(Vobject& on, const string& name) ;

    static void setFloatProperty(Vobject& on, const string& name, double val,
        double lowerLimit, double upperLimit, PropertyAccessControl* ac);

    static void setFloatProperty(Vobject& on, const string& name, double val,
        PropertyAccessControl* ac);



    static void setBoolProperty(Vobject& on, const string& name, bool val,
        PropertyAccessControl* ac);

    static bool Property::getBoolProperty(Vobject& on, const string& name);

    static bool Property::getBoolProperty(Vobject& on, const string& name,
        bool defaultVal);



    static void setFloatVectorProperty(Vobject& on, const string& name, vector<double> v, PropertyAccessControl* ac);

    /** Parse contents of property named 'name' into a vector of doubles */
    static vector<double> getFloatVectorProperty(Vobject& on, const string& name);

    //@}

    /** Add a new property listener to this property. This listener's methods
     * will be called when the property is modified.
     * @see PropertyListener
     * @param pl    The new property listener. If it is also a RefCounted
     * object, references will be acquired correctly.
     */
    virtual void addPropertyListener(PropertyListener* pl, bool refresh = true);

    /** Remove the property listener 'pl' from this property.
     * @param pl    Listener to remove. If it is also a RefCounted object,
     * references will be released correctly.
     */
    virtual void removePropertyListener(PropertyListener* pl);

     /**
     * @deprecated use writeToFile
     */
    static void Property::writeToFile(Property* p, const string& filename, int offset=0, int length=-1) {
        p->writeToFile(filename, offset, length);
    }

    /** Write decoded property value of p to a file named filename. if offset and length are supplied, write substring.
     * @throw runtime_error if there is an error opening or writing to the file.
     */
    void Property::writeToFile(const string& filename, int offset = 0, int length = -1);

    /**
     *  @deprecated use writeRawToFile.
     */
    static void Property::writeRawToFile(Property* p, const string& filename, int offset=0, int length=-1) {
        p->writeRawToFile(filename, offset, length);
    }

    /** Write raw, undecoded property data to file
     * @throw runtime_error on error opening or writing to file
     * @return return code from fwrite(). */
    void Property::writeRawToFile(const string& filename, int offset = 0, int length = 1);

    /** Read data from file into this property.
     * @param filename  Name of file to read from.
     * @param type      New datatype for this property. If empty ("") or
     *                  omitted, then the existing datatype will be used.
     * @throw runtime_error On error opening or reading from file.
     */
    void Property::readFromFile(const string& filename, const string& type = "");

    /** Register property type with factory */
    static void registerExtenders();

    /** Return MetaObject type, "property" */
    virtual const string getType();

    virtual void notifyObjectExcise(RefCounted* object);
    virtual void doExcise();
    virtual void doSaveState(MessageBlock& output, set<string>& types, bool portable);
};

class LocalProperty;

typedef PropertyAccessControl* (*PropertyAccessControlFactory)(const string& type, LocalProperty* lv);

/** @class PropertyAccessControl property.hh vos/metaobjects/property/property.hh
 *  Use subclasses of PropertyAccessControl to implement various access control
 *  policies on property reads and writes.
 */
class PROPERTY_API PropertyAccessControl
{
private:
    struct AssignAC
    {
        PropertyAccessControl* ac;
        PropertyAccessControlFactory fac;
    };
    static map<string, AssignAC> policies;

public:
    /** AccessControl callback to check if a given Vobject is
        permitted to read a section of this property.
        @param event the requested read
    */
    virtual bool checkReadPermission(PropertyEvent& event, string& message) = 0;

    /** AccessControl callback to check if a given Vobject is
        permitted to change this property.
        @param event the requested change
    */
    virtual bool checkChangePermission(PropertyEvent& event, string& message) = 0;

    /** Get a short string describing this policy. */
    virtual const string getPolicyName() = 0;

    /** Add a new access control policy.  This policy will be
        available as whatever name is returned by ac->getPolicyName().
        @param ac The policy object.
    */
    static void addPolicy(PropertyAccessControl* ac);

    /** Add a new access control policy.  The difference between this
        and the other addPolicy method is that a policy factory
        creates a new policy object each time getPolicy() is called,
        whereas otherwise the same policy object will be returned each
        time.  This is useful if you want to write an access control
        policy bound to a specific object that keeps some state about that
        object.
        @param name The policy name.  This should be the same as the name
        returned by getPolicyName() for the factory-created objects.
        @param ac The policy factory.
    */
    static void addPolicyFactory(const string& name, PropertyAccessControlFactory ac);

    /** Get the requested policy given the name and LocalVobject.
        @param name The policy name, registered at some point using addPolicy()
        @param lv The LocalProperty this policy will be added to
        (doesn't actually add it, but a policy factory may want to
        know what object it is being added to)
        @return the policy object, or NULL if there is no registered policy with that name
    */
    static PropertyAccessControl* getPolicy(const string& name, LocalProperty* lv);

    /** Remove policy with the given name.
        @param name policy name
    */
    static void removePolicy(const string& name);
};

/** @class NoPropertyAccessControl property.hh vos/metaobjects/property/property.hh
 * Access control policy for properties that always says yes. */
class PROPERTY_API NoPropertyAccessControl : public PropertyAccessControl
{
public:
    static NoPropertyAccessControl static_;

    virtual const string getPolicyName()
        { return "insecure"; }

    virtual bool checkReadPermission(PropertyEvent& event, string& message)
        { return true; };
    virtual bool checkChangePermission(PropertyEvent& event, string& message)
        { return true; };
};

/** @class ReadOnlyPropertyAccessControl property.hh vos/metaobjects/property/property.hh
 * Access control policy for properties permits unlimited reads but denies 
 * allwrites and replaces. */
class PROPERTY_API ReadOnlyPropertyAccessControl : public PropertyAccessControl
{
public:
    static ReadOnlyPropertyAccessControl static_;

    virtual const string getPolicyName()
        { return "readonly"; }

    virtual bool checkReadPermission(PropertyEvent& event, string& message)
        { return true; };
    virtual bool checkChangePermission(PropertyEvent& event, string& message)
        { message = "This property is read-only."; return false; };
};

class LocalProperty;

class PROPERTY_API PropertySecurityInitializer
{
public:
    virtual void initializePropertyAccessControl(LocalProperty* p, Vobject& requester) = 0;
};

class PROPERTY_API DoNothingPropertySecurityInitializer : public PropertySecurityInitializer
{
public:
    static DoNothingPropertySecurityInitializer static_;
    virtual void initializePropertyAccessControl(LocalProperty* p, Vobject& requester);
};


/** @class LocalProperty property.hh vos/metaobjects/property/property.hh
 * Local version of property */
class PROPERTY_API LocalProperty : public virtual Property
{
protected:
    deque<PropertyAccessControl*> accesscontrols;
    static PropertySecurityInitializer* securitycallback;

    void getLengthHandler(Message* m);
    void readHandler(Message* m);
    void writeHandler(Message* m);
    void replaceHandler(Message* m);
    void startListeningHandler(Message* m);
    void stopListeningHandler(Message* m);
public:
    LocalProperty(MetaObject* superobject);
    LocalProperty(MetaObject* superobject, const string& d, const string& dt = "?");
    virtual ~LocalProperty();
    static MetaObject* new_LocalProperty(MetaObject* superobject, const string& type);
    static void setSecurityCallback(PropertySecurityInitializer*);
    virtual void write(Vobject& initiator, int start, const string& newdata);
    virtual void write(int start, const string& newdata);
    virtual void replace(Vobject& initiator, const string& newdata,
                         const string& newtype = "?");
    virtual void replace(const string& newdata, const string& newtype = "?");
    virtual void addPropertyListener(PropertyListener* pl, bool refresh = true);
    /** Insert a new policy into the access policy list.  The access
        policy list is traversed from beginning to end, calling each
        access control policy in order until either a policy returns
        false (deny) or the end of the list is reached.  If access is
        denied, list traversal immediately stops and the requested
        action is denied.  If the end of the list is reached without a
        denial, the requested action is permitted.

        @param pos The position to be inserted into.  As with most
        other parts of %VOS, a positive value counts from the beginning
        and a negative value counts from the end.  In particular, a
        position of 0 will insert at the head of the list, making it
        the the first policy to be consulted.  A position of -1 will
        insert at the end of the list, making it the last policy to be
        consulted.

        @param ac the access control policy
    */
    virtual void insertPropertyAccessControl(int pos, PropertyAccessControl* ac);

    /** Add a named policy.
        @see VobjectAccessControl::getPolicy
        @see VobjectAccessControl::addPolicy
    */
    virtual void insertPropertyAccessControl(int pos, const string& policyname);

    /** Remove the access policy at the specified position.
        @param pos the position of the policy in the policy list
        @see insertAccessControl */
    virtual void removePropertyAccessControl(int pos);

    /** Remove all instances of the specified access policy from the
        policy list.
        @param m the access control policy to remove
        @see insertAccessControl */
    virtual void removePropertyAccessControl(PropertyAccessControl* m);

    /** Remove all policies matching this name.
        @see VobjectAccessControl::addPolicy
        @see VobjectAccessControl::getPolicy
    */
    virtual void removePropertyAccessControl(const string& policyname);

    /** @return the current access control policy list.
        @see insertAccessControl */
    virtual const deque<PropertyAccessControl*>& getPropertyAccessControls();

    /** Traverse the access policy list and determine whether to allow
        this event
        @param e the event to permit
        @return true if the event is permitted, false to deny this event
     */
    virtual bool validatePropertyAccess(PropertyEvent& e, string& message);

    virtual void initializeSecurity(Vobject& requester);
    virtual const string getSource() { return data; }

    /** Set a default access control policy. */
    virtual void initialize() {
        insertPropertyAccessControl(-1, &NoPropertyAccessControl::static_);
    }
};


/** @class RemoteProperty property.hh vos/metaobjects/property/property.hh
* Remote version of property; sends messages over network to Local object. */
class PROPERTY_API RemoteProperty : public virtual Property
{
private:
    void lengthUpdateHandler(Message* m);
    void writeUpdateHandler(Message* m);
    void replaceUpdateHandler(Message* m);
    void startListeningReplyHandler(Message* m);

protected:
    int offset;
    virtual void checkDecoded() ;
    bool first_read;                // indicates that no read message has been sent yet

public:
    RemoteProperty(MetaObject* superobject);
    static MetaObject* new_RemoteProperty(MetaObject* superobject, const string& type);
    virtual void read(string& target, int start, int length) ;
    virtual void readRaw(string& target, int start, int length);
    virtual void asyncRead();
    virtual void asyncRead(int start, int length);
    virtual int getLength() ;
    virtual int getRawLength();
    virtual const string getRawDataType();
    virtual void write(int start, const string& newdata);
    virtual void clearCache();
    virtual void replace(const string& newdata, const string& newtype = "?");
    virtual void addPropertyListener(PropertyListener* pl, bool refresh = true);
    virtual void removePropertyListener(PropertyListener* pl);
};





#endif

---