Programming Reference: ODObjectNameSpace

# Programming Reference

## ODObjectNameSpace

Class Definition File | ObjectNS.idl
Class C++ Binding | ObjectNS.xh

Class Hierarchy

    SOMObject
       ODObject
          ODNameSpace
             ODObjectNameSpace

Description

An object of the ODObjectNameSpace class is a collection of objects, each of which has a unique key to identify the object within the collection.

An object name space allows a part to identify an object using a unique key, which can be passed easily between parts. A part can create an object name space to store a reference to a part object to facilitate communications with its embedded parts.

Your part can create objects of the ODObjectNameSpace class by calling the name-space manager's CreateNameSpace method, passing the constant kODNSDataTypeODObject for the type of the name space.

Object name spaces can be arranged hierarchically to allow you to search multiple object name spaces for a single key. Searches move from a child object name space to its parent object name space until the entry is found or until there are no more object name spaces to search.

Methods

The methods defined by the ODObjectNameSpace class include:

- CreateIterator
- GetEntry
- Register

Overridden Methods | There are no methods overridden by the ODObjectNameSpace class.

### CreateIterator

This method creates an object iterator for the entries in this object name space.

Signature

    ODObjectIterator *CreateIterator ()

Parameters

None.

Returns

rv (ODObjectIterator *) - returns

  A reference to an object iterator for inheriting over the entries in this object name space.

Remarks

You call this method when you need to apply an operation to all the entries in this name space.

While you are using the returned object iterator, you must not modify this object name space. You must not register or unregister entries, and you must not delete this object name space.

You must delete the iterator when it is no longer needed.

### GetEntry

This method searches for an entry with the specified key and, if it exists, gets the object associated with that key.

Signature

    ODBoolean GetEntry (ODISOStr key,
                        ODObject **object)

Parameters

key (ODISOStr) - input

  The key to be searched for in this object name space.

object (ODObject **) - output

  A reference to the object corresponding to the specified key or kODNULL if the entry is not found.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the entry is found.

  kODTrue | The entry was found.
  kODFalse | The entry was not found.

Remarks

If the specified key is found, this method sets the object output parameter to a reference to the corresponding object. If the specified key is not found in this name space, this method searches the parent name space. Searches proceed from each object name space to its parent until one of the following happens:

- The entry is found.
- There is no parent name space to search.
- The parent name space is a value name space, not an object name space.

If the object corresponding to the specified key is a reference-counted object, this method does not increment the object's reference count. For this reason, if you cache that object, you should call its Acquire method to increment its reference count. Then you should call its Release method when you are finished using the object.

Related Methods

- ODNameSpace::Exists
- ODObjectNameSpace::Register

### Register

This method adds a new entry to this object name space.

Signature

    void Register (ODISOStr key,
                   ODObject *object)

Parameters

key (ODISOStr) - input

  The key for the new entry.

object (ODObject *) - input

  A reference to the object to be associated with the key.

Returns

None.

Remarks

This method stores a reference to the object parameter in a new entry in the table. If the specified key already exists in this name space, this method overwrites the old entry with the new one.

When you register a reference-counted object with an object registry, this method does not increment its reference count.

Related Methods

- ODNameSpace::Unregister

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]