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: |
Overridden Methods | There are no methods overridden by the ODNameSpace class. |
This method indicates whether this name space contains an entry with the specified key.
Signature
ODBoolean Exists (ODISOStr key) |
Parameters
Returns
| kODTrue | The key exists within this name space. |
| kODFalse | The key does not exist within this name space. |
This method returns the unique name of this name space.
Signature
ODISOStr GetName () |
Parameters
None.
Returns
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
This method returns a reference to the parent name space of this name space.
Signature
ODNameSpace *GetParent () |
Parameters
None.
Returns
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
This method returns the type of the name space.
Signature
ODNSTypeSpec GetType () |
Parameters
None.
Returns
| 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
This method reads the content of this name space from a file.
Signature
void ReadFromFile (ODByteArray *file) |
Parameters
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
This method reads the content of this name space from the specified storage-unit view.
Signature
void ReadFromStorage (ODStorageUnitView *view) |
Parameters
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
This method sets the type of the name space.
Signature
void SetType (ODNSTypeSpec type) |
Parameters
| 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
This method removes the specified entry from this name space.
Signature
void Unregister (ODISOStr key) |
Parameters
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
This method writes the name space out as a stream to the specified file.
Signature
void WriteToFile (ODByteArray *file) |
Parameters
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
This method writes the content of this name space to the specified storage-unit view.
Signature
void WriteToStorage (ODStorageUnitView *view) |
Parameters
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