Programming Reference: ODContainer

# Programming Reference

## ODContainer

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:

- AcquireDocument
- GetID
- GetName
- GetStorageSystem
- SetName

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

### AcquireDocument

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

id (ODDocumentID) - input

  The ID of the requested document.

Returns

rv (ODDocument *) - returns

  A reference to the specified document object.

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

- ODRefCntObject::Release

### GetID

This method returns the container ID of this container object.

Signature

    ODContainerID GetID ()

Parameters

None.

Returns

rv (ODContainerID) - returns

  The container ID whose buffer contains data identifying this container object.

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.

### GetName

This method returns the name of this container object.

Signature

    ODContainerName GetName ()

Parameters

None.

Returns

rv (ODContainerName) - returns

  The name of this container object or an empty sequence if the container does not have name.

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

- ODContainer::SetName

### GetStorageSystem

This method returns a reference to the storage-system object that created this container object.

Signature

    ODStorageSystem *GetStorageSystem ()

Parameters

None.

Returns

rv (ODStorageSystem *) - returns

  A reference to the storage-system object that created this container object.

### SetName

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

name (ODContainerName *) - input

  The new name of this container

Returns

None.

Related Methods

- ODContainer::GetName

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