Programming Reference: ODStorageSystem

# Programming Reference

## ODStorageSystem

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

Class Hierarchy

    SOMObject
       ODObject
          ODBaseStorageSystem
             ODStorageSystem

Description

An object of the ODStorageSystem class provides the function of the OpenDoc storage system.

The OpenDoc storage system is a high-level persistent storage mechanism that enables multiple part editors to share a single document file effectively. When a document is opened, the session object creates a single storage-system object. All parts of that document share the storage-system object; you can obtain a reference to it by calling the session object's GetStorageSystem method.

The storage-system object creates and maintains a collection of container objects. Each container object can hold one or more document objects, each of which contains one or more draft objects. Each draft contains a number of storage unit objects, which hold streams of stored data.

Each container object has a container type and an identifier; these two characteristics together uniquely identify the container. OpenDoc supports both file containers and memory containers. File containers are persistent across sessions, whereas memory containers are transitory.

For more information related to container objects, see the class description for ODContainer.

Methods

The methods defined by the ODStorageSystem class include:

- AcquireContainer
- CreateContainer
- CreatePlatformTypeList
- CreateTypeList
- GetSession
- NeedSpace

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

### AcquireContainer

This method is called by the document shell or container applications to retrieve a reference to the container object with the specified container type and identifier.

Signature

    ODContainer *AcquireContainer (ODContainerType containerType,
                                   ODContainerID *id)

Parameters

containerType (ODContainerType) - input

  The type of the container object. This parameter can be set to an ODContainerType type.

id (ODContainerID *) - input

  A container ID whose buffer contains data identifying the container object.

Returns

rv (ODContainer *) - returns

  A reference to the specified container object.

Remarks

The document shell and container applications call this method when opening an OpenDoc container.

The structure of the data in the id parameter's buffer depends on the type of container, specified by the containerType parameter. For example, the identifier for a file container is a specification for a file-system file; the identifier for a memory container is a handle for a relocatable memory block.

When the structure passed as the id parameter is no longer needed, the caller should deallocate that structure and its buffer.

This method increments the reference count of the returned container object. When the caller has finished using that container object, it should call the container's Release method.

Exception Handling

kODErrCannotCreateContainer | The specified container type is not valid.
kODErrIllegalNullIDInput | The id parameter is null.

Related Methods

- ODStorageSystem::CreateContainer

### CreateContainer

This method is called by the document shell or container part to create a container object with the specified container type and identifier.

Signature

    ODContainer *CreateContainer (ODContainerType containerType,
                                  ODContainerID *id)

Parameters

containerType (ODContainerType) - input

  The type of the container object. This parameter can be set to an ODContainerType type.

id (ODContainerID *) - input

  A container ID whose buffer contains data identifying the container object.

Returns

rv (ODContainer *) - returns

  A reference to the newly created container object.

Remarks

The structure of the data in the id parameter's buffer depends on the type of container, as specified by the containerType parameter. For example, the identifier for a file container is a specification for a file-system file; the identifier for a memory container is a handle for a relocatable memory block.

The physical container corresponding to the specified container type and container identifier must exist when this method is called.

When the structure passed as the id parameter is no longer needed, the caller should deallocate that structure and its buffer.

This method initializes the reference count of the returned container. When the caller has finished using that container, it should call the container's Release method.

Exception Handling

kODErrCannotCreateContainer | The specified container type is not valid.
kODErrContainerExists | A container already exists with the specified container type and container identifier.
kODErrIllegalNullIDInput | The id parameter is null.

Related Methods

- ODStorageSystem::AcquireContainer

Example Code

The following code fragment creates a memory container.

    ODHandle        handle = ODNewHandle(0);
    ODByteArray*  ba;

    ODLockHandle(handle);
    ba = CreateByteArray(&handle, sizeof(ODHandle));
    ODUnlockHandle(handle);

    container = (ODMemoryContainer*) fStorageSystem(ev)->CreateContainer(ev,
                                     kODBentoMemoryContainer,
                                     ba);
    DisposeByteArray(ba);

The following code fragment creates a file container.

    ODFileSpec     fileSpec;
    PlatformFile*  file = new PlatformFile;

    strcpy(fileSpec.name, "TEST.ODP" );
    file->Specify( &fileSpec );
    file->Create(kOpenDocShellSignature, kOpenDocShellSignature, 0);

    ODByteArray*   ba = CreateByteArray(&fileSpec, sizeof(ODFileSpec));

    container = (ODFileContainer*) fStorageSystem(ev)->CreateContainer(ev,
                                   kODDefaultFileContainer,
                                   ba);
    DisposeByteArray(ba);

### CreatePlatformTypeList

This method creates or copies a platform type list.

Signature

    ODPlatformTypeList *CreatePlatformTypeList (ODPlatformTypeList *typeList)

Parameters

typeList (ODPlatformTypeList *) - input

  A reference to the platform type list to be duplicated, or kODNULL to create an empty platform type list.

Returns

rv (ODPlatformTypeList *) - returns

  A reference to the newly created platform type list.

Remarks

Your part calls this method.

### CreateTypeList

This method creates or copies a type list.

Signature

    ODTypeList *CreateTypeList (ODTypeList *typeList)

Parameters

typeList (ODTypeList *) - input

  A reference to the type list to be duplicated, or kODNULL to create an empty type list.

Returns

rv (ODTypeList *) - returns

  A reference to the newly created type list.

Remarks

You can call this method if your part needs a list of types. For example, a list of part kinds it supports.

If the typeList parameter is a reference to an existing type list, the new type list is initialized to contain a copy of each element in the existing type list. The elements in the new list are in the same order as the elements of the existing type list. Because each element of the existing list is a pointer to an ISO string, the pointers themselves are not added to the new type list; instead, each string is copied and a pointer to the new copy is added to the type list.

### GetSession

This method returns a reference to the current session object.

Signature

    ODSession *GetSession ()

Parameters

None.

Returns

rv (ODSession *) - returns

  A reference to the session object which created this storage system.

Remarks

Your part typically calls its storage unit's GetSession method instead of this method.

Related Methods

- ODStorageUnit::GetSession

### NeedSpace

This method notifies this storage system to reserve memory for future use.

Signature

    void NeedSpace (ODSize memSize,
                    ODBoolean doPurge)

Parameters

memSize (ODSize) - input

  The size of the desired memory block.

doPurge (ODBoolean) - input

  A flag indicating whether this operation should trigger the Purge method to obtain the requested memory.

  kODTrue | This object should purge memory to obtain the requested memory.
  kODFalse | This object should not purge memory.

Returns

None.

Remarks

Your part can call this method when it anticipates the need for a large memory block. This method is not guaranteed to generate the memory requested and should be used with caution as it may be a slow operation.

If the doPurge parameter is kODTrue, then this method calls the Purge method associated with this storage system's container objects (and transitively its document objects, draft objects, and storage-unit objects). If the doPurge parameter is kODFalse, the method returns.

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