Class Definition File | ODCtr.idl |
Class C++ Binding | ODCtr.xh |
Class Hierarchy |
SOMObject
ODObject
ODRefCntObject
ODContainer
|
Description | An object of the ODContainer class represents a physical container storing a collection of OpenDoc documents. The ODContainer class lets you access these documents independently of the container's physical characteristics or internal structure. The ODContainer class is implemented differently for different platforms and storage mechanism. The ODContainer class manipulates physical containers. Similarly, the ODDocument class manipulates documents; the ODDraft class manipulates drafts; and the ODStorageUnit class manipulates storage units. This set of related classes, ODContainer, ODDocument, ODDraft, and ODStorageUnit, is called a container suite. Container-suite classes are implemented as an integrated set for each platform and storage mechanism because they work intimately with each other at many levels. Each container object can contain one or more document objects. Each document object, in turn, can contain one or more draft objects, and each draft object can contain one or more storage unit objects. Each container, document, draft and storage unit has a unique ID. Only the OpenDoc storage system directly creates container objects. The document shell or container application creates or accesses a container object by calling the storage-system object's CreateContainer or AcquireContainer method. The storage system ensures that there is only one container object associated with each physical container. You can access a document of a container by calling the container's AcquireDocument method. The ODContainer class is responsible for ensuring that there is only one document object associated with each document in the container. For more information on how ODContainer and other container-suite classes are used, see the chapters on storage and the OpenDoc runtime features in the OpenDoc Programming Guide. |
Methods | The methods defined by the ODContainer class include: |
Overridden Methods | There are no methods overridden by the ODContainer class. |
This method is called by the document shell or container application to retrieve a reference to the document object associated with the specified document ID.
Signature
ODDocument *AcquireDocument (ODDocumentID id) |
Parameters
Returns
Remarks
The document shell or container application calls this method when the user opens an OpenDoc document.
This method looks in this container object for the document object associated with the specified document ID. If such a document object exists, the object is returned. If the specified document object does not exist, it is created, initialized, and returned.
This method increments the reference count of the returned document object. When the caller has finished using that document object, it should call the document's Release method.
Exception Handling
kODErrInvalidDocument | The specified document does not exist. |
Related Methods
This method returns the container ID of this container object.
Signature
ODContainerID GetID () |
Parameters
None.
Returns
Remarks
Although parts can call this method, they usually do not need to know the IDs of their associated containers.
The structure of the data identifying this container depends on the type of container, which was specified when the container was created. For example, the identifier for a Bento file container specifies a file-system file; the identifier for a Bento memory container is a handle for a relocatable memory block.
This method returns the name of this container object.
Signature
ODContainerName GetName () |
Parameters
None.
Returns
Remarks
Although parts can call this method, they usually do not need to know the names of their associated container.
If this container has a name, this method returns a copy of that name; otherwise, the text field of the result ODContainerName structure represents an empty sequence of characters. The text field is an ODByteArray structure whose _length field contains 0 and whose _buffer field contains null pointer.
Related Methods
This method returns a reference to the storage-system object that created this container object.
Signature
ODStorageSystem *GetStorageSystem () |
Parameters
None.
Returns
This method is called by the document shell or container application to set the name of this container object.
Signature
void SetName (ODContainerName *name) |
Parameters
Returns
None.
Related Methods