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

/home/tetron/hack/vos/libs/vos/vos/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 
    Additions by Reed Hedges marked with initials "rh" and date.
*/
#ifndef _PROPERTY_HH_
#define _PROPERTY_HH_

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

#include <vos/vos/vos.hh>

namespace VOS {
    class PropertyAccessControl;
    class PropertyListener;
    class PropertyEvent;

/** @class Property property.hh vos/metaobjects/property/property.hh
 *  @ingroup libmetaobject_property
 *
 *  Property stores data of any type and size.
 */
class VOS_API Property : public MetaObject
{
private:
    Message::Priority priority;

protected:
    Property(VobjectBase* superobject);

public:

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

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

    /** 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(std::string& target, int start, int length) = 0;

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

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

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

    /** 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 std::string& newdata, const std::string& newtype = "?") = 0;

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

    /** Set/get this property, converting from/to non-string types.
        For information on formatted replace and read see snprintf and
        scanf in the standard C library.
    */
    //@{
    void replace(const char* format, size_t maxlen, ...);
    void replace(const char* format, const char* type, size_t maxlen, ...);
    void replace(const char* str);
    void read(const char* format, ...);
    void replace(bool b);
    void replace(int i);
    void replace(float x);
    void replace(float x, float y);
    void replace(float x, float y, float z);
    void replace(float x, float y, float z, float r);
    void replace(double x);
    void replace(double x, double y);
    void replace(double x, double y, double z);
    void replace(double x, double y, double z, double r);
    void read(int& i);
    void read(bool& i);
    void read(double& x);
    void read(double& x, double& y);
    void read(double& x, double& y, double& z);
    void read(double& x, double& y, double& z, double& r);
    void read(float& x);
    void read(float& x, float& y);
    void read(float& x, float& y, float& z);
    void read(float& x, float& y, float& z, float& r);
    void read(std::vector<float>& vec);
    void read(std::vector<int>& vec);
    void replace(std::vector<float>& vec);
    void replace(std::vector<int>& vec);
    //@}

    /** Set/Get a subproperty on an object, returning relation between object and property.
        For information on formatted setProperty and getProperty see snprintf and
        scanf in the standard C library.
     *  @param on   Object to set a subproperty on
     *  @param propname Name of the property to set
     *  @param type  Datatype of the new value.
     *  @param fmt Format string (printf()-style)
     *  @param maxlen Maximum buffer size for formatting property value and
     *  replacing (using snprintf()).
     *  @return object expressing relation between the object and the property
     */
    //@{
    static VUtil::vRef<ParentChildRelation> setProperty(Vobject& on,
             const std::string& propname, const std::string& type,
            const char* fmt, size_t maxlen, ...);
    static VUtil::vRef<ParentChildRelation> setProperty(Vobject& on,
             const std::string& propname, const std::string& type,
            const std::string& pac, const char* fmt, size_t maxlen, ...);
    static VUtil::vRef<ParentChildRelation> getProperty(Vobject& on,
             const std::string& propname, const char* fmt, ...);

    static VUtil::vRef<ParentChildRelation> setProperty(Vobject& on,
                                                 const std::string& propname,
                                                 const std::string& propval,
                                                 const std::string& valtype,
                                                 const std::string& pac = "",
                                                 bool letErrorThrough = false);

    static VUtil::vRef<ParentChildRelation> setProperty(Vobject& base,
                                                        const std::string& propname,
                                                        bool b,
                                                        const std::string& pac = "");

    static VUtil::vRef<ParentChildRelation> setProperty(Vobject& base,
                                                        const std::string& propname,
                                                        int i,
                                                        const std::string& pac = "");

    static VUtil::vRef<ParentChildRelation> setProperty(Vobject& base,
                                                        const std::string& propname,
                                                        double x,
                                                        const std::string& pac = "");

    static VUtil::vRef<ParentChildRelation> setProperty(Vobject& base,
                                                        const std::string& propname,
                                                        double x, double y,
                                                        const std::string& pac = "");

    static VUtil::vRef<ParentChildRelation> setProperty(Vobject& base,
                                                        const std::string& name,
                                                        int x, int y,
                                                        const std::string& pac = "");

    static VUtil::vRef<ParentChildRelation> setProperty(Vobject& base,
                                                        const std::string& propname,
                                                        double x, double y, double z,
                                                        const std::string& pac = "");

    static VUtil::vRef<ParentChildRelation> setProperty(Vobject& base,
                                                        const std::string& propname,
                                                        double x, double y, double z, double r,
                                                        const std::string& pac = "");

    static VUtil::vRef<ParentChildRelation> getProperty(Vobject& base,
                                                        const std::string& propname,
                                                        std::string& data,
                                                        std::string& datatype);

    static VUtil::vRef<ParentChildRelation> getProperty(Vobject& base,
                                                        const std::string& propname,
                                                        int& i);

    static VUtil::vRef<ParentChildRelation> getProperty(Vobject& base,
                                                        const std::string& propname,
                                                        bool& i);

    static VUtil::vRef<ParentChildRelation> getProperty(Vobject& base,
                                                        const std::string& propname,
                                                        double& x);

    static VUtil::vRef<ParentChildRelation> getProperty(Vobject& base,
                                                        const std::string& propname,
                                                        double& x, double& y);

    static VUtil::vRef<ParentChildRelation> getProperty(Vobject& base,
                                                        const std::string& propname,
                                                        double& x, double& y, double& z);

    static VUtil::vRef<ParentChildRelation> getProperty(Vobject& base,
                                                        const std::string& propname,
                                                        double& x, double& y, double& z, double& r);

    static VUtil::vRef<ParentChildRelation> getProperty(Vobject& base,
                                                        const std::string& propname,
                                                        float& x);

    static VUtil::vRef<ParentChildRelation> getProperty(Vobject& base,
                                                        const std::string& propname,
                                                        float& x, float& y);

    static VUtil::vRef<ParentChildRelation> getProperty(Vobject& base,
                                                        const std::string& name,
                                                        int& x, int& y);

    static VUtil::vRef<ParentChildRelation> getProperty(Vobject& base,
                                                        const std::string& propname,
                                                        float& x, float& y, float& z);

    static VUtil::vRef<ParentChildRelation> getProperty(Vobject& base,
                                                        const std::string& propname,
                                                        float& x, float& y, float& z, float& r);

    //@}

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

    /** 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.
     * @param refresh  ?? If supplied, determines whether listener is
     * immediately notified ??
     */
    virtual void addPropertyListener(PropertyListener* pl, bool refresh = true) = 0;

    /** 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) = 0;

    /** Write property value to a file.
     * If offset and length are supplied, write substring.
     * @param filename  Name of file to open and write to. Any previous contents
     *                  will be replaced.
     * @param offset    If supplied, beginning of substring to write from
     *                  property value.
     * @param length    If supplied, length of substring to write from property
     *                  value.
     * @throw runtime_error if there is an error opening or writing to the file.
     */
    void writeToFile(const std::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 readFromFile(const std::string& filename, const std::string& type = "");

    /** Return MetaObject type, "property" */
    virtual const std::string getVOSType() = 0;

    virtual void doSaveState(MessageBlock& output, std::set<std::string>& types, bool portable);

    /** Specify if this property should be cached locally.  Only
        meaningful for remote properties.  This means that we become a
        listener of the remote property and receive updates.  Calls to
        read() will be serviced using the cached values for the
        property and will not go out to the network.
        @param b If true, use cache.  If false, the property will not
        be cached (unless it is being listened to by another part of the program.)
     */
    virtual void cacheProperty(bool b);
};

/** @class PropertyAccessControl property.hh vos/metaobjects/property/property.hh
 *  Use subclasses of PropertyAccessControl to implement various access control
 *  policies on property reads and writes.
 *  @ingroup libmetaobject_property
 */
class VOS_API PropertyAccessControl
{
public:
    virtual ~PropertyAccessControl() { }

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

    /** AccessControl callback to check if a given Vobject is
        permitted to change this property.
        @param event the requested change event
        @param message Will be set to contain a message describing reason for a failure.
    */
    virtual bool checkChangePermission(PropertyEvent& event, std::string& message) = 0;

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

extern VOS_API PolicyDomain<PropertyAccessControl> PropertyAccessControlPolicies;

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

    virtual ~AcceptAllPropertyAccessControl() { }

    virtual const std::string getPolicyName()
        { return "property:accept-all"; }

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

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

    virtual ~ReadOnlyPropertyAccessControl() { }

    virtual const std::string getPolicyName()
        { return "property:read-only"; }

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

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

    virtual ~DenyAllPropertyAccessControl() { }

    virtual const std::string getPolicyName()
        { return "property:deny-all"; }

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

}

#ifndef VOS_EXPORTS
IMPORT_METAOBJECT_FACTORIES(DefaultPropertyACs)
IMPORT_METAOBJECT_FACTORIES(BasicLocalProperty)
IMPORT_METAOBJECT_FACTORIES(RemoteProperty)
#endif


#endif