AAF Object Manager Documentation

Utility functions including error handling, obtaining information about the host computer, wide character string manipulation, property path manipulation and accessing disk files with wide character names.

Author

Tim Bingham - tjb - (Avid Technology, Inc.)

ANAME

define ANAME( name)

Define a name only when assertions are enabled. Use to avoid compiler warnings.

Defined in: OMAssertions.h

Parameters

name: The name to (conditionally) define.

ASSERT

define ASSERT( name, expression)

Assert (when enabled with OM_ENABLE_DEBUG) that the condition described by name and expression is true. An invocation of this macro must be preceeded by an invocation of the TRACE macro.

Defined in: OMAssertions.h

Parameters

name: The name of the condition. The condition name is a description of the condition that makes sense from the internal point of view (that of someone reading the source text). The name comprises a portion of the message that is printed if the condition is violated. The message that is printed makes sense from the external point of view.
expression: The condition expression. The expression should be free of side effects.

concatenateWideString

wchar_t* concatenateWideString(wchar_t* destination, const wchar_t* source, const size_t length)

Concatenate wide character strings. Same as strncat(), but for wide characters. Append up to length characters from source to the end of destination. If the null character that terminates source is encountered before length characters have been copied, then the null character is copied but no more. If no null character appears among the first length characters of source, then the first length characters are copied and a null character is supplied to terminate destination, that is, length + 1 characters in all are written.

Defined in: OMUtilities.h

Return Value

The resulting wide character string.

Parameters

destination: The destination buffer.
source: The wide character string to copy.
length: The number of characters to copy.

copyWideString

wchar_t* copyWideString(wchar_t* destination, const wchar_t* source, const size_t length)

Copy a wide character string. Same as strncpy(), but for wide characters. Exactly length characters are always written to the destination buffer. The destination buffer must be at least length characters in size. If the buffer is too small this error is not detected. If length is greater than the length of source then then destination is padded with nulls and destination will be properly null terminated. If length is less than the length of source only length characters will be copied and destination will not be properly null terminated. If the source and destination wide character strings overlap this error is not detected,.

Defined in: OMUtilities.h

Return Value

The resulting wide character string.

Parameters

destination: The destination buffer.
source: The wide character string to copy.
length: The number of characters to copy.

endl

OMOStream& endl(OMOStream& s)

OMOStream end of line manipulator.

Defined in: OMOStream.cpp

Return Value

The modified OMOStream

Parameters

s: The OMOStream in which to inset the new line.

Global Variables

OMOStream omlog: Global OMOStream for Object Manager logging. Debug use only.

Developer Notes

If your platform doesn't have iostream.h you'll need to implement the following functions differently.

endl

OMOStream& endl(OMOStream& s)

OMOStream end of line manipulator.

Defined in: OMOStream.h

Return Value

The modified OMOStream.

Parameters

s: The OMOStream in which to inset the new line.

Global Variables

extern OMOStream omlog: Global OMOStream for Object Manager logging. Debug use only.

finalizeObjectManager

void finalizeObjectManager(void)

Finalize the Object Manager.

Defined in: OMObjectManager.h

FORALL

define FORALL( index, elementCount, expression)

Universal quantifier. Evaluate expression for all elements, 0 .. elementCount of a collection. Use index as the name of the index. The expression is most usefully one of the assertion macros such as PRECONDITION, POSTCONDITION or ASSERT.

Defined in: OMAssertions.h

Parameters

index: The index name.
elementCount: The number of elements in the collection.
expression: The expression to evaluate for each element.

FOREACH

define FOREACH( index, start, elementCount, expression)

Evaluate expression for each element, start .. elementCount of a collection. Use index as the name of the index. The expression is most usefully one of the assertion macros such as PRECONDITION, POSTCONDITION or ASSERT.

Defined in: OMAssertions.h

Parameters

index: The index name.
start: The starting index.
elementCount: The number of elements.
expression: The expression to evaluate for each element.

hostByteOrder

OMByteOrder hostByteOrder(void)

Get the byte order used on the host computer.

Defined in: OMUtilities.h

Return Value

The host byte order.

IMPLIES

define IMPLIES( a, b)

Boolean implication - use IMPLIES in construction of other assertions. Read 'IMPLIES(a, b)' as 'a => b', or 'a implies b'. 'ASSERT("...", IMPLIES(a, b))' is the expression form of 'if (a) ASSERT("...", b)'. However, IMPLIES() hides the 'if' statement so that it can be 'compiled away'.

Defined in: OMAssertions.h

Parameters

a: An expression.
b: An expression.

initializeObjectManager

void initializeObjectManager(void)

Initialize the Object Manager.

Defined in: OMObjectManager.h

INVARIANT

define INVARIANT(void)

Assert (when enabled with OM_ENABLE_DEBUG) that the invariant for the class of the current object is true.

Defined in: OMAssertions.h

lengthOfWideString

size_t lengthOfWideString(const wchar_t* string)

The length of the wide character string string in characters excluding the terminating null character. Same as strlen(), but for wide characters.

Defined in: OMUtilities.h

Return Value

The wide character string length in characters.

Parameters

string: The wide character string.

NNAME

define NNAME( name)

Never define a name. Use to avoid compiler warnings.

Defined in: OMAssertions.h

Parameters

name: The name not to define.

OBSOLETE

define OBSOLETE( newRoutineName)

Print a message (when enabled with OM_ENABLE_DEBUG and OM_ENABLE_OBSOLETE) indicating that the current routine is obsolete and that newRoutineName should be used instead. OBSOLETE is provided to aid clients in migrating from one Object Manager version to the next. Routines are made obsolete before they are removed.

Defined in: OMAssertions.h

Parameters

newRoutineName: The name of the routine that should be called instead.

obsolete

void obsolete(const char* routineName, const char* newRoutineName)

Output a message indicating that the routineName is obsolete and that newRoutineName should be used instead

Defined in: OMAssertions.h

Parameters

routineName: The name of the obsolete routine.
newRoutineName: The name of the routine that should be called instead.

OLD

define OLD( name)

Retrieve the value of a variable or expression saved on entry to a routine with SAVE or with SAVE_EXPRESSION. For use in postconditions.

Defined in: OMAssertions.h

Parameters

name: The name of the saved variable or expression.

OMAssertionViolation class

OMAssertionViolation class OMAssertionViolation

Object Manager assertion violation. An instance of this class is thrown when an assertion violation occurs.

Defined in: OMAssertions.h

OMBuiltinPropertyDefinition class

OMBuiltinPropertyDefinition class OMBuiltinPropertyDefinition

Definitions of persistent properties supported by the Object Manager.

Defined in: OMPropertyDefinition.h

Author

Tim Bingham - tjb - (Avid Technology, Inc.)

Developer Notes

This is a temporary class and will be merged into OMPropertyDefinition. This will require changes to code in Object Manager clients.

Class Members

Public members.

OMBuiltinPropertyDefinition(const OMType* type, const wchar_t* name, const OMPropertyId propertyId, const bool isOptional): Constructor.
~OMBuiltinPropertyDefinition(void): Destructor.
virtual const OMType* type(void) const: The type of the OMProperty defined by this OMBuiltinPropertyDefinition.
virtual const wchar_t* name(void) const: The name of the OMProperty defined by this OMBuiltinPropertyDefinition.
virtual OMPropertyId localIdentification(void) const: The locally unique identification of the OMProperty defined by this OMBuiltinPropertyDefinition.
virtual bool isOptional(void) const: Is the OMProperty defined by this OMBuiltinPropertyDefinition optional?

Class Members

Private members.

OMBuiltinPropertyDefinition::isOptional

bool OMBuiltinPropertyDefinition::isOptional(void)

Is the OMProperty defined by this OMBuiltinPropertyDefinition optional?

Defined in: OMPropertyDefinition.cpp

Back to OMBuiltinPropertyDefinition

OMBuiltinPropertyDefinition::localIdentification

OMPropertyId OMBuiltinPropertyDefinition::localIdentification(void)

The locally unique identification of the OMProperty defined by this OMBuiltinPropertyDefinition.

Defined in: OMPropertyDefinition.cpp

Back to OMBuiltinPropertyDefinition

OMBuiltinPropertyDefinition::name

const wchar_t* OMBuiltinPropertyDefinition::name(void)

The name of the OMProperty defined by this OMBuiltinPropertyDefinition.

Defined in: OMPropertyDefinition.cpp

Back to OMBuiltinPropertyDefinition

OMBuiltinPropertyDefinition::OMBuiltinPropertyDefinition

OMBuiltinPropertyDefinition::OMBuiltinPropertyDefinition(void)

Constructor.

Defined in: OMPropertyDefinition.cpp

Back to OMBuiltinPropertyDefinition

OMBuiltinPropertyDefinition::type

const OMType* OMBuiltinPropertyDefinition::type(void)

The type of the OMProperty defined by this OMBuiltinPropertyDefinition.

Defined in: OMPropertyDefinition.cpp

Back to OMBuiltinPropertyDefinition

OMBuiltinPropertyDefinition::~OMBuiltinPropertyDefinition

OMBuiltinPropertyDefinition::~OMBuiltinPropertyDefinition(void)

Destructor.

Defined in: OMPropertyDefinition.cpp

Back to OMBuiltinPropertyDefinition

OMCharacterStringProperty class

OMCharacterStringProperty class OMCharacterStringProperty: public OMVariableSizeProperty

Abstract base class for persistent character string properties supported by the Object Manager.

Defined in: OMCharacterStringProperty.h

Class Template Arguments

CharacterType: The type of the characters that comprise the string.

Author

Tim Bingham - tjb - (Avid Technology, Inc.)

Class Members

Public members.

OMCharacterStringProperty(const OMPropertyId propertyId, const wchar_t* name): Constructor.
virtual ~OMCharacterStringProperty(void): Destructor.
operator const CharacterType* () const: Type conversion. Convert an OMCharacterStringProperty into a string of CharacterType characters.
void assign(const CharacterType* characterString): Assign the string characterString to this OMCharacterStringProperty.
size_t length(void) const: The length of this OMCharacterStringProperty in characters (not counting the null terminating character).
static size_t stringLength(const CharacterType* characterString): Utility function for computing the length, in characters, of the string of CharacterType characters characterString.

OMCharacterStringProperty::assign

template <class CharacterType>
void OMCharacterStringProperty<CharacterType>::assign(const CharacterType* characterString)

Assign the string characterString to this OMCharacterStringProperty.

Defined in: OMCharacterStringPropertyT.h

Parameters

characterString: The string of CharacterType characters to assign.

Class Template Arguments

CharacterType: The type of the characters that comprise the string.

Back to OMCharacterStringProperty

OMCharacterStringProperty::length

template <class CharacterType>
size_t OMCharacterStringProperty<CharacterType>::length(void) const

The length of this OMCharacterStringProperty in characters (not counting the null terminating character).

Defined in: OMCharacterStringPropertyT.h

Return Value

The length of this OMCharacterStringProperty.

Class Template Arguments

CharacterType: The type of the characters that comprise the string.

Back to OMCharacterStringProperty

OMCharacterStringProperty::operator const CharacterType*

template <class CharacterType>
OMCharacterStringProperty<CharacterType>::operator const CharacterType*(void)

Type conversion. Convert an OMCharacterStringProperty into a string of CharacterType characters.

Defined in: OMCharacterStringPropertyT.h

Return Value

The result of the conversion as a value of type pointer to CharacterType.

Class Template Arguments

CharacterType: The type of the characters that comprise the string.

Back to OMCharacterStringProperty

OMCharacterStringProperty::stringLength

template <class CharacterType>
size_t OMCharacterStringProperty<CharacterType>::stringLength(const CharacterType* characterString)

Utility function for computing the length, in characters, of the string of CharacterType characters characterString.

Defined in: OMCharacterStringPropertyT.h

Return Value

The length of the the string of CharacterType characters characterString.

Parameters

characterString: A string of CharacterType characters.

Class Template Arguments

CharacterType: The type of the characters that comprise the string.

Back to OMCharacterStringProperty

OMClassFactory class

OMClassFactory class OMClassFactory

Abstract base class decribing the class factory used by the Object Manager and provided by Object Manager clients.

Defined in: OMClassFactory.h

Author

Tim Bingham - tjb - (Avid Technology, Inc.)

Class Members

Public members.

virtual ~OMClassFactory(void): Destructor.
virtual OMStorable* create(const OMClassId& classId) const: Create an instance of the appropriate derived class, given the class id.

OMContainer class

OMContainer class OMContainer

Abstract base class for collections of elements.

Defined in: OMContainer.h

Class Template Arguments

Element: The type of an OMContainer element. This type must support = and ==.

Author

Tim Bingham - tjb - (Avid Technology, Inc.)

Class Members

Public members.

virtual size_t count(void) const: The number of elements in this OMContainer. count returns the actual number of elements in the OMContainer.
virtual void clear(void): Remove all elements from this OMContainer.

OMContainerElement class

OMContainerElement class OMContainerElement

Elements of Object Manager reference containers.

Defined in: OMContainerElement.h

Class Template Arguments

ObjectReference: The type of the contained object reference

Author

Tim Bingham - tjb - (Avid Technology, Inc.)

Class Members

Public members.

OMContainerElement(void): Constructor.
OMContainerElement(const ObjectReference& reference): Constructor.
OMContainerElement(const OMContainerElement<ObjectReference;>& rhs): Copy constructor.
~OMContainerElement(void): Destructor.
OMContainerElement<ObjectReference;>& operator=: Assignment. This operator provides value semantics for OMContainer. This operator does not provide assignment of object references.
bool operator==(const OMContainerElement<ObjectReference;>& rhs) const: Equality. This operator provides value semantics for OMContainer. This operator does not provide equality of object references.
ObjectReference& reference(void): The contained ObjectReference.
void setReference(const ObjectReference& reference): Set the contained ObjectReference.
void save(void): Save this OMContainerElement.
void close(void): Close this OMContainerElement.
void detach(void): Detach this OMContainerElement.
void restore(void): Restore this OMContainerElement.
OMStorable* getValue(void) const: Get the value of this OMContainerElement.
OMStorable* pointer(void) const: The value of this OMContainerElement as a pointer. This function provides low-level access. If the object exits but has not yet been loaded then the value returned is 0.

Class Members

Protected members.

ObjectReference _reference: The actual object reference.

OMContainerElement::close

template <class ObjectReference>
void OMContainerElement<ObjectReference>::close(void)

Close this OMContainerElement.

Defined in: OMContainerElementT.h

Class Template Arguments

ObjectReference: The type of the contained object reference

Back to OMContainerElement

OMContainerElement::detach

template <class ObjectReference>
void OMContainerElement<ObjectReference>::detach(void)

Detach this OMContainerElement.

Defined in: OMContainerElementT.h

Class Template Arguments

ObjectReference: The type of the contained object reference

Back to OMContainerElement

OMContainerElement::getValue

template <class ObjectReference>
OMStorable* OMContainerElement<ObjectReference>::getValue(void) const

Get the value of this OMContainerElement.

Defined in: OMContainerElementT.h

Return Value

A pointer to the ReferencedObject.

Class Template Arguments

ObjectReference: The type of the contained object reference

Back to OMContainerElement

OMContainerElement::OMContainerElement

template <class ObjectReference>
OMContainerElement<ObjectReference>::OMContainerElement(const OMContainerElement<ObjectReference;>& rhs)

Copy constructor.

Defined in: OMContainerElementT.h

Parameters

rhs: The OMContainerElement to copy.

Class Template Arguments

ObjectReference: The type of the contained object reference

Back to OMContainerElement

OMContainerElement::OMContainerElement

template <class ObjectReference>
OMContainerElement<ObjectReference>::OMContainerElement(const ObjectReference& reference)

Constructor.

Defined in: OMContainerElementT.h

Parameters

reference: The ObjectReference for this OMContainerElement.

Class Template Arguments

ObjectReference: The type of the contained object reference

Back to OMContainerElement

OMContainerElement::OMContainerElement

template <class ObjectReference>
OMContainerElement<ObjectReference>::OMContainerElement(void)

Constructor.

Defined in: OMContainerElementT.h

Class Template Arguments

ObjectReference: The type of the contained object reference

Back to OMContainerElement

OMContainerElement::operator=

template <class ObjectReference>
OMContainerElement<ObjectReference;>& OMContainerElement<ObjectReference>::operator=(const OMContainerElement<ObjectReference;>& rhs)

Assignment. This operator provides value semantics for OMContainer. This operator does not provide assignment of object references.

Defined in: OMContainerElementT.h

Return Value

The OMContainerElement resulting from the assignment.

Parameters

rhs: The OMContainerElement to be assigned.

Class Template Arguments

ObjectReference: The type of the contained object reference

Back to OMContainerElement

OMContainerElement::operator==

template <class ObjectReference>
bool OMContainerElement<ObjectReference>::operator==(const OMContainerElement<ObjectReference;>& rhs)

Equality. This operator provides value semantics for OMContainer. This operator does not provide equality of object references.

Defined in: OMContainerElementT.h

Return Value

True if the values are the same, false otherwise.

Parameters

rhs: The OMContainerElement to be compared.

Class Template Arguments

ObjectReference: The type of the contained object reference

Back to OMContainerElement

OMContainerElement::pointer

template <class ObjectReference>
OMStorable* OMContainerElement<ObjectReference>::pointer(void)

The value of this OMContainerElement as a pointer. This function provides low-level access. If the object exits but has not yet been loaded then the value returned is 0.

Defined in: OMContainerElementT.h

Return Value

A pointer to the reference OMStorable, if loaded.

Class Template Arguments

ObjectReference: The type of the contained object reference

Back to OMContainerElement

OMContainerElement::reference

template <class ObjectReference>
ObjectReference& OMContainerElement<ObjectReference>::reference(void)

The contained ObjectReference.

Defined in: OMContainerElementT.h

Return Value

The contained ObjectReference.

Class Template Arguments

ObjectReference: The type of the contained object reference

Back to OMContainerElement

OMContainerElement::restore

template <class ObjectReference>
void OMContainerElement<ObjectReference>::restore(void)

Restore this OMContainerElement.

Defined in: OMContainerElementT.h

Class Template Arguments

ObjectReference: The type of the contained object reference

Back to OMContainerElement

OMContainerElement::save

template <class ObjectReference>
void OMContainerElement<ObjectReference>::save(void)

Save this OMContainerElement.

Defined in: OMContainerElementT.h

Class Template Arguments

ObjectReference: The type of the contained object reference

Back to OMContainerElement

OMContainerElement::setReference

template <class ObjectReference>
void OMContainerElement<ObjectReference>::setReference(const ObjectReference& reference)

Set the contained ObjectReference.

Defined in: OMContainerElementT.h

Parameters

reference: The new contained ObjectReference.

Class Template Arguments

ObjectReference: The type of the contained object reference

Back to OMContainerElement

OMContainerElement::~OMContainerElement

template <class ObjectReference>
OMContainerElement<ObjectReference>::~OMContainerElement(void)

Destructor.

Defined in: OMContainerElementT.h

Class Template Arguments

ObjectReference: The type of the contained object reference

Back to OMContainerElement

OMContainerIterator class

OMContainerIterator class OMContainerIterator

Abstract base class for iterators over Object Manager containers. The elements of an Object Manager container have a well defined order. An Object Manager container may be traversed in either the forward or reverse direction.

Defined in: OMContainerIterator.h

Class Template Arguments

Element: The type of the contained elements.

Author

Tim Bingham - tjb - (Avid Technology, Inc.)

Class Members

Public members.

virtual void reset(OMIteratorPosition initialPosition): Reset this OMContainerIterator to the given initialPosition. If initialPos