QSDK 1.1 Documentation
Main Page | Modules | Class Hierarchy | Alphabetical List | Compound List | File List | Compound Members | File Members | Related Pages

Q::Object Struct Reference
[QServer]

Generic object for persistent data. More...

#include <Q/q.h>

Inheritance diagram for Q::Object:

Q::ObjectBase Q::Animation Q::AnimationBundle Q::AudioEffect Q::Bitmap Q::Clip Q::Clump Q::Concept Q::Environment Q::Font Q::FxClass Q::FxClassSequence Q::Geom Q::Group Q::Instance Q::KnowledgeSlice Q::Shader Q::SimpleSound Q::TextureEffect Q::Zone List of all members.

Public Types

enum  residencyAdvice {
  discard = 1,
  hold,
  acquire
}
enum  residencyQualification {
  now = 1,
  soon,
  later
}

Public Member Functions

 Object ()
 Object (const Object &obj)
 ~Object ()
Utils::Result destroy ()
Utils::Result adviseResidency (residencyAdvice, residencyQualification, ResidencyListener *=0)
bool resident (bool deep=false)
ObjectIterator assets () const
Utils::Result addAsset (const Object &obj) const
Utils::Result removeAsset (const Object &obj) const
ObjectIterator loadAssets () const
Utils::Result addLoadAsset (const Object &obj) const
Utils::Result removeLoadAsset (const Object &obj) const
Utils::UID uid () const
size_t diskSize () const
size_t memorySize () const
Text name () const
bool rename (const char *newname)
unsigned int generation () const
bool isPersistent () const
Utils::Result duplicate (Database)
Utils::Result relocate (Database)

Static Public Member Functions

Object find (const Utils::UID &uid)
Object find (const char *name, const Concept &type)
Object find (const char *name, const ClassType &type)

Detailed Description

Generic object for persistent data.

Generic object. Provides the machinery for working with persistent objects.

Typically new references to persistent objects are created by using a constructor in the relevant derived class which takes the name of the persistent object. New objects are created by using the static create method of the derived class. If a name is given to create, the new object will be persistent, otherwise it will only exist for the current session.

Member Enumeration Documentation

enum Q::Object::residencyAdvice
 

This enumerated type is used to supply hints to the object database via Object::adviseResidency.

Enumeration values:
discard  If the object is currently resident in memory, unload it.
hold  Acquire the object if it is not currently in memory, then hold it in memory.
acquire  If the object is not currently resident, then load it.

enum Q::Object::residencyQualification
 

This enumerated type is used to qualify the call to Object::adviseResidency by specifying when the required operation should be performed.

Enumeration values:
now  The change in object residency should happen now, i.e. before the call to Object::adviseResidency returns.
soon  The change in residency should happen as soon as possible but not necessarily before the call to Object::adviseResidency returns.
later  Similar to soon but lower priority, scheduling it to be done after background loading but before luxury assets.

Constructor & Destructor Documentation

Q::Object::Object (   ) 
 

Create a null object reference.

Q::Object::Object (  const Object &  obj  ) 
 

Create a reference to an existing object.

Q::Object::~Object (   ) 
 

Destroy the object reference. If the reference is to a non-persistent object, the object will be deleted if this was the last reference. If the object was persistent, then the object may be removed from memory and will be loaded from the database on the next reference.

Member Function Documentation

Utils::Result Q::Object::addAsset (  const Object &  obj  )  const
 

Add obj to the list of lifetime dependancies for this object.

Utils::Result Q::Object::addLoadAsset (  const Object &  obj  )  const
 

Add obj to the list of load dependancies for this object.

Utils::Result Q::Object::adviseResidency (  residencyAdvice  ,
residencyQualification  ,
ResidencyListener *  = 0
) 
 

This method can be used by an application to supply hints to the object database as to whether the object should be loaded into memory or unloaded from memory. See the description of residencyAdvice and residencyQualification above for more details. If a valid ResidencyListener is provided, it will be notified when the object becomes resident. Return EBadObject if the object is not valid, otherwise Utils::Success.

Note:
There is an unexpected side effect when using this method to load Group objects. Because of internal restrictions, when a Group is loaded, or used to start preparation of creating renderable asset (for example), not only does the load logic flow to the children of the Group, but also to its siblings. Therefore, if the Group has been newly parented to a Zone root, the whole of that Zone heirarchy will be traversed to process any residency requests.

ObjectIterator Q::Object::assets (   )  const
 

Return the lifetime assets associated with the object. These objects are grouped together with the object in the persistent storage and are pre-loaded at the same time as the object for efficient streaming. If the object is loaded via a Clump then these assets are held in memory for the lifetime of the Object.

Reimplemented in Q::Clump.

Utils::Result Q::Object::destroy (   ) 
 

Destroy an object. Persistent objects become light for the remainder of the session after this operation. They will be removed from memory once the last reference is dropped.

If the object is persistent, an attempt is made to remove it from its database. Persistent removal requires database readModifyCreate permission (see Database::open). If permission is not granted, the object will become light but the database image will remain in file. This case is indicated by returning Utils::Failure, otherwise Utils::Success is returned.

If the object is invalid, EBadObject is returned.

Reimplemented in Q::Concept, Q::Clip, and Q::Group.

size_t Q::Object::diskSize (   )  const
 

Return the physical object disk size in bytes.

Utils::Result Q::Object::duplicate (  Database   ) 
 

Make a copy of the object in the designated database. Duplicate the concept of this object and any knowledge sourced from the originating database. The duplicate has the same OID as the original.

Return Utils::Success if successful. Otherwise, return WObjectPresent if an object with the same ID is already present in the destination database (this is a warning because it is assumed to be the same object). Return WClipPresent if a clip of the same name is present (also assumed to be the same clip). Return WNameConflict if the object was copied but not its concept due to another object already with a concept of the same name. Return Utils::InvalidArgument if the object is invalid or there was some other unknown problem copying the object.

Object Q::Object::find (  const char *  name,
const ClassType &  type
)  [static]
 

Search the database for an object with the given name and type. If the object does not exist or the type is not valid, a null reference is returned.

Object Q::Object::find (  const char *  name,
const Concept &  type
)  [static]
 

Search the database for an object with the given name and type. If the object does not exist or the concept is not valid, a null reference is returned.

Object Q::Object::find (  const Utils::UID &  uid  )  [static]
 

Search the database for an object with the given unique identifier and return a reference to that object if it exists. If the object does not exist, a null reference is returned.

unsigned int Q::Object::generation (   )  const
 

Return the generation number of this object. The generation number is incremented each time the object is modified.

bool Q::Object::isPersistent (   )  const
 

Returns true if this object is persisted in a Q file (and hence has a name).

ObjectIterator Q::Object::loadAssets (   )  const
 

Return the load assets associated with the object. These objects are grouped together with the object in the persistent storage and are pre-loaded at the same time as the object for efficient streaming. If the object is loaded via a Clump then these assets are loaded with the object and then released.

size_t Q::Object::memorySize (   )  const
 

Return the in-memory size (bytes).

Note:
If it is not currently resident, the object will be loaded into memory.

Text Q::Object::name (   )  const
 

Return the name of the object referenced by this reference. If the object is not persistent, an empty string is returned.

Reimplemented in Q::Concept.

Utils::Result Q::Object::relocate (  Database   ) 
 

Transplant this object into the given database retaining the original OID.

See also:
duplicate()

Utils::Result Q::Object::removeAsset (  const Object &  obj  )  const
 

Remove obj from the list of lifetime dependancies for this object.

Utils::Result Q::Object::removeLoadAsset (  const Object &  obj  )  const
 

Remove obj from the list of load dependancies for this object.

bool Q::Object::rename (  const char *  newname  ) 
 

Change the name of the persistent object.

bool Q::Object::resident (  bool  deep = false  ) 
 

Return true if the object is currently resident in memory. The value of deep is currently ignored.

Utils::UID Q::Object::uid (   )  const
 

Return a unique identifier for the underlying object if it is valid, otherwise return the null UID.

Return to QSDK documentation Contents page. Contact details for support, information and fault-reporting.
Qube Software Limited © 2000-2004