Programming Reference: ODValueNameSpace

# Programming Reference

## ODValueNameSpace

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

Class Hierarchy

    SOMObject
       SOMClass
          ODObject
             ODNameSpace
                ODValueNameSpace

Description

An object of the ODValueNameSpace class is a collection of values, each of which has a unique key to identify the value within the collection.

A value name space allows a part to identify a value using a unique key, which can be passed easily between parts. A part can create a value name space to store information about other part editors, such as the part's supported part kinds. The values in a value name space are stored as byte arrays whose buffers can contain values of any types.

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

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

Methods

The methods defined by the ODValueNameSpace class include:

- CreateIterator
- GetEntry
- Register

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

### CreateIterator

This method creates a value iterator for the entries in this value name space.

Signature

    ODValueIterator *CreateIterator ()

Parameters

None.

Returns

rv (ODValueIterator *) - returns

  A reference to a value iterator for iterating over the entries in this value name space.

Remarks

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

While you are using the returned value iterator, you must not modify this value name space; in particular, you must not register or unregister entries, and you must not delete this value 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, returns the value associated with that key.

Signature

    ODBoolean GetEntry (ODISOStr key,
                        ODByteArray *value)

Parameters

key (ODISOStr) - input

  The key to search for in this value name space.

value (ODByteArray *) - output

  The byte array whose buffer is to contain the value corresponding to the specified key, if the entry is found.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the entry was found.

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

Remarks

If the specified key is found, this method copies the entry's associated value into the value parameter. If the specified key is not found in this name space, this method searches the parent name space. Searches proceed from each value name space to its parent until one of the following happens: the entry is found, there is no parent name space to search, or the parent name space is an object name space instead of a value name space.

If the key is found, the _buffer field of value output parameter is to point to a memory block containing the copy of the value associated with the key. If the key is not found after searching this value name space and its ancestors, the _buffer field of value parameter is set to kODNULL.

Your part must delete the byte value array and its buffer when they are no longer needed.

Related Methods

- ODNameSpace::Exists
- ODValueNameSpace::Register

### Register

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

Signature

    void Register (ODISOStr key,
                   ODByteArray *value)

Parameters

key (ODISOStr) - input

  The key for the new entry.

value (ODByteArray *) - input

  The byte array whose buffer contains the value to associate with the key.

Returns

None.

Remarks

This method copies both the key and value parameter's buffer into a new entry in the name space. If the specified key already exists within this name space, this method overwrites the old value with the new one and deallocates the memory used by the old value.

Related Methods

- ODNameSpace::Unregister

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