interreality.org [VOS]
[Home] [About]
[Screenshots]
 [Download]
[News]
 [Community]
[Documentation] [Manual]
[Bugs & Requests] [Wiki]
VOS::Vobject

VOS::Vobject Class Reference
[libvos]

#include <vos/vos/vobject.hh>

Inheritance diagram for VOS::Vobject:

VUtil::RefCounted VOS::MetaObject VOS::VobjectBase A3DL::Actor A3DL::Light A3DL::Material A3DL::Object3D A3DL::Portal A3DL::RemoteActionListener A3DL::Sector A3DL::Texture A3DL::Viewpoint Creature Hello VOS::Avatar VOS::Factory VOS::Group VOS::Hypercard VOS::Identity VOS::IrcBridge VOS::IrcClient VOS::LocalPasswordAuth VOS::LocalSearch VOS::LocalVobject VOS::LogLevelCtrl VOS::Metadata VOS::Property VOS::RemoteListener VOS::RemotePasswordAuth VOS::RemotePropertyListener VOS::RemoteSearch VOS::Services VOS::Talkative VOS::VersionedVobject VOS::VOSPlugin VOS::Site List of all members.

Detailed Description

This is the abstract class that defines the basic API common to all virtual objects.

Whether the object is local or remote, you should be able to use all the methods in this API (provided you have proper permissions).

Definition at line 124 of file vobject.hh.

Public Member Functions

Static Public Member Functions

Member Function Documentation

virtual void VOS::Vobject::addChildListener ( ChildChangeListener *  cl,
bool  refresh = true 
) [pure virtual]

Adds some object callback to be notified when the child list changes.

The

Parameters:
cl The listener object.
refresh if true, will queue up notification callbacks on the listener fully describing the current state.

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual void VOS::Vobject::addFlag ( const std::string &  flag  )  [pure virtual]

Add a flag string.

Useful when doing recursive tree walks, to avoid cycles. This is local-only, it is not shared with other sites in any way.

Parameters:
flag the flag string

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual void VOS::Vobject::addParentListener ( ParentChangeListener *  pl,
bool  refresh = true 
) [pure virtual]

Adds some object callback to be notified when the parent set changes.

Parameters:
pl the listener object
refresh if true, will queue up notification callbacks on the listener fully describing the current state.

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual void VOS::Vobject::addToACL ( const std::string &  ACLname,
Group *  grp 
) [pure virtual]

Add a group to an access control list (ACL).

If this group exists in another ACL, it will be removed from that ACL first.

Parameters:
ACLname the name of the ACL. This is a comma-separated list of the access control policies to apply for each domain. For example "core:read-only,property:accept-all". Order does not matter (it will be sorted) but this access control list name is distict from just "core:read-only"!
grp the Group to add

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual void VOS::Vobject::addToACL ( const std::string &  ACLname,
Identity *  id 
) [pure virtual]

Add an identity to an access control list (ACL).

If this identity exists in another ACL, it will be removed from that ACL first.

Parameters:
ACLname the name of the ACL. This is a comma-separated list of the access control policies to apply for each domain. For example "core:read-only,property:accept-all". Order does not matter (it will be sorted) but this access control list name is distict from just "core:read-only"!
id the Identity to add

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual void VOS::Vobject::addType ( const std::string &  s  )  [pure virtual]

Adds a new type to this object's type set.

This only changes the stored set of type name std::strings and does not necessarily affect the actual code behind the object. See the Local Site class for information about extending the actual functionality of an existing meta objects.

Parameters:
s the type std::string

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual void VOS::Vobject::addTypeListener ( TypeChangeListener *  tl,
bool  refresh = true 
) [pure virtual]

Adds some object callback to be notified when the type set changes.

Parameters:
tl the listener object.
refresh if true, will queue up notification callbacks on the listener fully describing the current state.

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual bool VOS::Vobject::checkFlag ( const std::string &  flag  )  [pure virtual]

Check the flag std::string.

Parameters:
flag the flag std::string
Returns:
whether the flag std::string is set

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual void VOS::Vobject::deleteACL ( const std::string &  policies  )  [pure virtual]

Completely delete an ACL.

Parameters:
policies the name of the ACL. This is a comma-separated list of the access control policies to apply for each domain. For example "core:read-only,property:accept-all". Order does not matter (it will be sorted) but this access control list name is distict from just "core:read-only"!

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual VUtil::vRef<VOS::ParentChildRelation> VOS::Vobject::findChild ( int  pos  )  [pure virtual]

Get the child at a certain position.

This searchs for a single parent-child relation in the immediate child list of this object. See setChild() for more information about the possible numerical values of positions.

Parameters:
pos the child position
Returns:
the ParentChildRelation structure representing the relation of this parent and the requested child.
Exceptions:
NoSuchObjectError if the path is illegal
AccessControlError if a remote site reported the user is not allowed that information

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual VUtil::vRef<VOS::ParentChildRelation> VOS::Vobject::findChild ( const std::string &  path  )  [pure virtual]

Fetch a child.

This searchs for a single parent-child relation in the immediate child list of this object. It is distinguished from findObject in that it returns the full parent-child relation structure, and that it only accepts two forms of input: the child name, or the position in the child list. See setChild() for more information about the possible numerical values of positions. If there are multiple children with the same name, the one with the lowest position is returned.

Parameters:
path either the child name or the position as a string
Returns:
the ParentChildRelation structure representing the relation of this parent and the requested child.
Exceptions:
NoSuchObjectError if the path is illegal
AccessControlError if a remote site reported the user is not allowed that information

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual VUtil::vRef<VOS::Vobject> VOS::Vobject::findObject ( const std::string &  path  )  [pure virtual]

Follows some path to find the Vobject.

Unlike findObjectFromRoot(), if the path does not start with "vop://" the path will be intepreted relative to this object. For example, "foo/bar" will find the first child object named "foo" of this object, then the first child named "bar" of "foo" object and return that. If there is a leading slash, the path is relative to the object's site, so "/foo/bar" means to find the Vobject with site name "foo", then find the first child of that object "bar" and return that. Instead of using child names, one may use the position by prefixing a hash mark to the numerical position. So "\#0" refers to the first child of this object, "\#1" to the second etc. If this is larger than the number of children, an exception will be raised. See setChild() for more information about the possible numerical values of positions.

Parameters:
path the path to the object we want to find
Returns:
the object, if found.
Exceptions:
NoSuchSiteError The DNS lookup for the site failed, the site is not listening on the expected port, site peering failed, for whatever other reason the site could not be contacted. Only thrown if there is a site specified in the path.)
NoSuchObjectError if that object path does not exist on the site
BadURLError if there is a syntax error in the supplied URL
AccessControlError if a remote site reported that the user is not allowed that information

Implemented in VOS::MetaObject, and VOS::VobjectBase.

static VUtil::vRef<VOS::Vobject> VOS::Vobject::findObjectFromRoot ( const std::string &  path  )  [static]

Searchs and returns some object, given a rooted path (that is, in the form "vop://site:port/child1/child2/etc").

See findObject() for more information about paths.

Parameters:
path the path to the object we want to find
Returns:
the object, if found.
Exceptions:
NoSuchSiteError The DNS lookup for the site failed, the site is not listening on the expected port, site peering failed, for whatever other reason the site could not be contacted.
NoSuchObjectError if that object path does not exist on the site
BadURLError if there is a syntax error in the supplied URL
AccessControlError if a remote site reported that the user is not allowed that information

virtual VUtil::vRef<VOS::ParentChildRelation> VOS::Vobject::findParent ( Vobject *  parent  )  [pure virtual]

Find a parent.

This tests to see if the supplied Vobject is a parent of this Vobject.

Parameters:
parent the parent object
Returns:
the parent-child relation.
Exceptions:
NoSuchObjectError if the object is NOT a parent
AccessControlError if a remote site reported the user is not allowed that information

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual ACLIterator VOS::Vobject::getAllACLs (  )  [pure virtual]

Returns:
all access control lists (ACL) that have been set.

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual StringIterator VOS::Vobject::getAvailablePolicies ( const std::string &  domain  )  [pure virtual]

Returns:
all policies in a particular policy domain that are available for use.

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual ChildListIterator VOS::Vobject::getChildren ( int  start = 0,
int  end = -1 
) [pure virtual]

Get the children of this Vobject.

Permits fetching a "slice" of a child list by specifying starting and ending positions.

Parameters:
start the position of the first child to return (inclusive)
end the position of th elast child to return (inclusive)
Returns:
an Iterator over a list of parent-child relations

Implemented in VOS::MetaObject, and VOS::VobjectBase.

Referenced by listChildren().

virtual std::string VOS::Vobject::getDefaultPolicy ( const std::string &  domain = ""  )  [pure virtual]

Get the policy that is applied by default if the requester's identity or groups were not found in any ACL.

This is also the policy applied to anonymous users (users with no identity.)

Parameters:
domain the policy domain you are interested in. If blank, returns a comma-separated list of the policy in each domain.

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual ParentSetIterator VOS::Vobject::getParents (  )  [pure virtual]

Get the set of parent-child relationships in which this object is the child.

Returns:
a set of parent-child relations

Implemented in VOS::MetaObject, and VOS::VobjectBase.

Referenced by listParents().

virtual StringIterator VOS::Vobject::getPolicy ( const std::string &  domain,
Identity *  id 
) [pure virtual]

Do an access control lookup; for some identity requesting access, this will return the appropriate policy in some domain based on the current access control lists.

Access control lookup works like this:

  1. Check each ACL to see if it lists this Identity. If so, we use that ACL's policy.
  2. Otherwise, check each ACL for groups that this Identity belongs to. If the Identity is a member of several Groups that are in different ACLs, then return the policy for each relevant ACL. The caller should check *every* policy to determine pass or fail -- this is up to the caller, but commonly in VOS code if any policy grants permission then permission is given. This means that groups can be used to add permissions, but not take them away! Design you access control scheme accordingly (and make the default permissions as restrictive as possible).
  3. Otherwise, because neither the Identity nor any Group it is a member of appear in any ACL, the default access control is returned.

Parameters:
domain the policy domain of interest
id the identity requesting access

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual VUtil::vRef<VOS::Site> VOS::Vobject::getSite (  )  const [pure virtual]

Returns:
the site this object resides on.

Implemented in VOS::MetaObject, VOS::Site, and VOS::VobjectBase.

Referenced by VOS::VobjectBase::getAccessControlsFor().

virtual const std::string& VOS::Vobject::getSiteName (  )  const [pure virtual]

Returns:
the site name of this object.

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual TypeSetIterator VOS::Vobject::getTypes (  )  [pure virtual]

Returns:
a set of type names for the types supported by this object.

Implemented in VOS::MetaObject, and VOS::VobjectBase.

Referenced by listTypes().

virtual const VUtil::URL& VOS::Vobject::getURL (  )  const [pure virtual]

Returns:
the URL path as a URL object

Implemented in VOS::MetaObject, and VOS::VobjectBase.

Referenced by listChildren().

virtual std::string VOS::Vobject::getURLstr (  )  [inline, virtual]

Returns:
the URL path (in the form "proto://site/name")

Definition at line 137 of file vobject.hh.

Referenced by listParents(), listTypes(), and main().

virtual VUtil::vRef<VobjectBase> VOS::Vobject::getVobjectBase (  )  [pure virtual]

Returns:
the VobjectBase object that actually implements this Vobject

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual void VOS::Vobject::insertChild ( int  position,
const std::string &  contextual_name,
Vobject *  child 
) [pure virtual]

Insert a child at some position with a new object.

If the position is positive, the object is inserted such that it now occupies that position, and all objects starting from the previous occupant of that position onward are moved up one. If the position in negative, the object is similarly inserted so that it now occupies that position. For example, position -1 will append the object to the end of the list, position -2 will insert the object in the second-to-last position, etc. See setChild() for more discussion on positions.

Parameters:
position the position
contextual_name This is the name, specific to this parent-child relation, used for refering to this object by path.
child the child object, in question
Exceptions:
AccessControl if this is a remote object and the remote site has denied the requsted action

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual bool VOS::Vobject::isLocal (  )  [pure virtual]

Returns:
true if this object is local, false if not

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual bool VOS::Vobject::isRemote (  )  [pure virtual]

Returns:
true if this object is remote, false if not

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual int VOS::Vobject::numChildren (  )  [pure virtual]

Returns:
the number of children that this Vobject has. This is more efficient than calling getChildren().size() because if this is a remote object it does not actually fetch the children.

Implemented in VOS::MetaObject, and VOS::VobjectBase.

bool VOS::Vobject::operator!= ( Vobject &  v  )  const

Provide our own comparison function for objects which are logically equivilent in terms of the Vobject system.

Parameters:
v the object to compare with this object
Returns:
false if these objects are equivalent, otherwise true.

bool VOS::Vobject::operator== ( Vobject &  v  )  const

Provide our own comparison function for objects which are logically equivilent in terms of the Vobject system.

Parameters:
v the object to compare this to
Returns:
true if these objects are equivalent, else false.

virtual void VOS::Vobject::removeChild ( ParentChildRelation *  pcr,
bool  strict = true 
) [pure virtual]

Remove the child at some position.

See setChild() for more information on positions.

Parameters:
pcr ParentChildRelation object describing the child entry to remove.
strict Should the position in the supplied parent child relation be strictly followed? If strict is false, then if the parent-child entry at the supplied position does NOT match the contextual name and/or child object, but there is exactly one other entry in the child list which does match the contextual name and child we want to remove, then that entry will be removed instead. If strict is true, an AccessControlError is raised in this situation.
Exceptions:
AccessControl if this is a remote object and the remote site has denied the requsted action

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual void VOS::Vobject::removeChildListener ( ChildChangeListener *  cl  )  [pure virtual]

Removes an object callback, previously added with addChildListener().

Parameters:
cl the listener object

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual void VOS::Vobject::removeFlag ( const std::string &  flag  )  [pure virtual]

Remove a flag string.

Parameters:
flag the flag string

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual void VOS::Vobject::removeFromACL ( const std::string &  ACLname,
Group *  grp 
) [pure virtual]

Remove a Group from an access control list (ACL).

The ACL will be deleted when the last member is removed.

Parameters:
ACLname the name of the ACL. This is a comma-separated list of the access control policies to apply for each domain. For example "core:read-only,property:accept-all". Order does not matter (it will be sorted) but this access control list name is distict from just "core:read-only"!
grp the Group to add

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual void VOS::Vobject::removeFromACL ( const std::string &  ACLname,
Identity *  id 
) [pure virtual]

Remove an Identity from an access control list (ACL).

The ACL will be deleted when the last member is removed.

Parameters:
ACLname the name of the ACL. This is a comma-separated list of the access control policies to apply for each domain. For example "core:read-only,property:accept-all". Order does not matter (it will be sorted) but this access control list name is distict from just "core:read-only"!
id the Identity to add

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual void VOS::Vobject::removeParentListener ( ParentChangeListener *  pl  )  [pure virtual]

Removes an object callback, previously added with addParentListener().

Parameters:
pl the listener object

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual void VOS::Vobject::removeType ( const std::string &  s  )  [pure virtual]

Remove a type from the type set.

Parameters:
s the type std::string

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual void VOS::Vobject::removeTypeListener ( TypeChangeListener *  tl  )  [pure virtual]

Removes an object callback, previously added with addTypeListener().

Parameters:
tl the listener object

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual void VOS::Vobject::saveState ( MessageBlock &  output,
std::set< std::string > &  types,
bool  portable 
) [pure virtual]

Create a message block which, when run, will recreate any non-VOS state related to this vobject (such as property values).

In other words, it should not emit anything related to parent-child relationships, but is rather is a hook for other arbitrary state information, encoded as messages.

Note:
Save-state routines ought to work for saving remote objects as well, based on available state. Also, only the method and the message fields themselves should be used. "To", "from", "nonce" and others will be ignored.
Parameters:
output messages should be appended to this message block
types the type set that should be output for this vobject
portable If true, generate a "portable" state. This means that all the data required to restore state should be embedded in the message. If false, fully recreating the state may rely on external resources such as files or databases.

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual void VOS::Vobject::sendMessage ( MessageBlock *  m  )  [pure virtual]

Delivers a block of messages to the object.

This may trigger immediate processing of the message if the object is local.

Parameters:
m A pointer to the message which is being sent.

Implemented in VOS::MetaObject, VOS::Site, and VOS::VobjectBase.

virtual void VOS::Vobject::sendMessage ( Message *  m  )  [pure virtual]

Delivers a message to the object.

This may trigger immediate processing of the message if the object is local.

Parameters:
m A pointer to the message which is being sent.

Implemented in VOS::MetaObject, VOS::Site, and VOS::VobjectBase.

virtual void VOS::Vobject::sendUpdateMessage ( Message *  m  )  [pure virtual]

Delivers an update message to this object -- only meaningful if this is a remote object.

Update messages are special in that they are sent by the remote site to update our local cache.

Parameters:
m A pointer to the message which is being sent.

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual void VOS::Vobject::setChild ( int  position,
const std::string &  contextual_name,
Vobject *  child 
) [pure virtual]

Replace an entry in the child list with a new entry.

This can be used to change the child, the contextual name, or both.

Note:
On positions: if a position is zero or positive, its meaning is as you would expect, expressing the offset into an array of children. However, if the position is negative, it expresses the offset from the end of the list. This means for a list of length n, -1 is the last item in the list (equal to position n - 1) and -n is the first item (equal to positive position 0). This position notation is used in setChild() findObject(), findObjectFromRoot(), insertChild(), and removeChild(); it should also be available with any methods who make use of the previously-mentioned methods.
Parameters:
position the position
contextual_name This is the name, specific to this parent-child relation, used for refering to this object by path.
child the child object, in question
Exceptions:
AccessControl if this is a remote object and the remote site has denied the requsted action

Implemented in VOS::MetaObject, and VOS::VobjectBase.

virtual void VOS::Vobject::setDefaultPolicy ( const std::string &  policy  )  [pure virtual]

Set the default policy.

Parameters:
policy the policy. This only affects the domains listed. For example, if your current default policy is "core:read-only,property:accept-all" and you call setDefaultPolicy("property:read-only") the resulting default policy will be "core:read-only,property:read-only".

Implemented in VOS::MetaObject, and VOS::VobjectBase.

The documentation for this class was generated from the following file: