Programming Reference: ODNameSpace

# Programming Reference

## ODNameSpace

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

Class Hierarchy

    SOMObject
       ODObject
          ODNameSpace

Description

An object of the ODNameSpace class associates an object or data structure with a unique key and provides a fast way to retrieve information.

A name-space object allows a part to identify an object or value using a unique key, which can be passed easily between parts. Parts can use name spaces to store references to parts that support, for example, scripting systems. A part can then iterate over the contents of the name space to obtain a list of scriptable parts or to send a message to all of the scriptable parts. Name spaces can also be written to a storage unit and read back in later.

The ODNameSpace class is an abstract class that defines the basic name-space functionality. OpenDoc defines the subclasses corresponding to two types of name spaces, object and value. An object of the ODObjectNameSpace class represents an object name space, which stores objects; an object of the ODValueNameSpace class represents a value name space, which stores values of any type formatted as byte arrays.

Your part creates a new name space by calling the name-space manager's CreateNameSpace method, specifying a unique name that OpenDoc can use to identify the new name space. Entries within the name space must similarly be identified by a unique key. To obtain a reference to an existing name space, your part calls the name-space manager's HasNameSpace method.

Name spaces can be arranged hierarchically to allow you to search multiple name spaces for a single key. Searches move from the child to parent name space to its parent space until the entry is found or until there are no more name spaces to search. A search also stops if the type of the parent name space is different from the type of the child name space, for example, if a value name space is the child of an object name space.

Methods

The methods defined by the ODNameSpace class include:

- Exists
- GetName
- GetParent
- GetType
- ReadFromFile
- ReadFromStorage
- SetType
- Unregister
- WriteToFile
- WriteToStorage

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

### Exists

This method indicates whether this name space contains an entry with the specified key.

Signature

    ODBoolean Exists (ODISOStr key)

Parameters

key (ODISOStr) - input

  The key for the requested entry.

Returns

rv (ODBoolean) - returns

  A flag indicating the key exists within this name space.

  kODTrue | The key exists within this name space.
  kODFalse | The key does not exist within this name space.

### GetName

This method returns the unique name of this name space.

Signature

    ODISOStr GetName ()

Parameters

None.

Returns

rv (ODISOStr) - returns

  The name of this name space.

Remarks

When you create a name space, you specify its name in the spaceName parameter of the name-space manager's CreateNameSpace method.

When you no longer need the returned name, you should deallocate it.

Related Methods

- ODNameSpaceManager::CreateNameSpace

### GetParent

This method returns a reference to the parent name space of this name space.

Signature

    ODNameSpace *GetParent ()

Parameters

None.

Returns

rv (ODNameSpace *) - returns

  A reference to the parent name space or kODNULL if this name space has no parent.

Remarks

When you create a name space, you specify its parent name space in the inheritsFrom parameter of the name-space manager's CreateNameSpace method.

Related Methods

- ODNameSpaceManager::CreateNameSpace

### GetType

This method returns the type of the name space.

Signature

    ODNSTypeSpec GetType ()

Parameters

None.

Returns

rv (ODNSTypeSpec) - returns

  The type of this name space. This parameter can be set to one of the following values:

  kODNSDataTypeODObject | An object name space.
  kODNSDataTypeODValue | An value name space.

Remarks

When you create a name space, you specify its type in the type parameter of the name-space manager's CreateNameSpace method.

Related Methods

- ODNameSpace::SetType
- ODNameSpaceManager::CreateNameSpace

### ReadFromFile

This method reads the content of this name space from a file.

Signature

    void ReadFromFile (ODByteArray *file)

Parameters

file (ODByteArray *) - input

  A reference to the file from which data is to be read.

Returns

None.

Remarks

You call this method to read in the content of a name space that was written to a file using the WriteToFile method.

The content of this name space is stored in the file as a single stream of data.

This method does not remove the existing content of this name space, but it does overwrite any entry that has the same key as an entry from the file. After this method executes successfully, this name space's new entries will correspond to entries stored in the file.

Exception Handling

kODErrInvalidName | The stored name does not match the name of this name space.

Related Methods

- ODNameSpace::WriteToStorage

### ReadFromStorage

This method reads the content of this name space from the specified storage-unit view.

Signature

    void ReadFromStorage (ODStorageUnitView *view)

Parameters

view (ODStorageUnitView *) - input

  A reference to the storage-unit view from which data is to be read.

Returns

None.

Remarks

You call this method to read in the content of a name space that was written to a storage unit using the WriteToStorage method.

The content of this name space is stored in the storage unit as a single stream of data. The focus context for the specified storage-unit view should be the value from which the name space is to be read.

This method does not remove the existing content of this name space, but it does overwrite any entry that has the same key as an entry from the storage unit. After this method executes successfully, this name space's new entries will correspond to entries read from the storage unit.

Exception Handling

kODErrInvalidName | The stored name does not match the name of this name space.

Related Methods

- ODNameSpace::WriteToStorage

### SetType

This method sets the type of the name space.

Signature

    void SetType (ODNSTypeSpec type)

Parameters

type (ODNSTypeSpec) - input

  The type of this name space. This parameter can be set to one of the following values:

  kODNSDataTypeODObject | An object name space.
  kODNSDataTypeODValue | An value name space.

Returns

None.

Remarks

This method is called by subclasses of the ODNameSpace class to set the type of the name space. Your part should not call this method directly.

Related Methods

- ODNameSpace::GetType

### Unregister

This method removes the specified entry from this name space.

Signature

    void Unregister (ODISOStr key)

Parameters

key (ODISOStr) - input

  The key for the entry to be removed.

Returns

None.

Remarks

If this name space does not contain an entry with the specified key, this method returns without raising an exception. This method does not search the parent name space for the key.

Related Methods

- ODObjectNameSpace::Register
- ODValueNameSpace::Register

### WriteToFile

This method writes the name space out as a stream to the specified file.

Signature

    void WriteToFile (ODByteArray *file)

Parameters

file (ODByteArray *) - input

  The file to which data is to be written.

Returns

None.

Remarks

This stream can be read back in by calling the ReadFromFile method.

Exception Handling

This method can return file system errors and storage errors.

Override Policy

If you subclass ODNameSpace, you should not override this method.

Related Methods

- ODNameSpace::ReadFromFile

### WriteToStorage

This method writes the content of this name space to the specified storage-unit view.

Signature

    void WriteToStorage (ODStorageUnitView *view)

Parameters

view (ODStorageUnitView *) - input

  A reference to the storage unit in which data is to be written.

Returns

None.

Remarks

This method writes the content of this name space as a single stream of data. The focus context for the specified storage-unit view should be the value to which the name space is to be written.

You can read the content of this name space by calling the ReadFromStorage method.

Exception Handling

This method may return platform-specific exceptions.

Related Methods

- ODNameSpace::ReadFromStorage

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