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: |
Overridden Methods | There are no methods overridden by the ODStorageSystem class. |
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
Returns
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
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
Returns
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
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);
|
This method creates or copies a platform type list.
Signature
ODPlatformTypeList *CreatePlatformTypeList (ODPlatformTypeList *typeList) |
Parameters
Returns
Remarks
This method creates or copies a type list.
Signature
ODTypeList *CreateTypeList (ODTypeList *typeList) |
Parameters
Returns
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.
This method returns a reference to the current session object.
Signature
ODSession *GetSession () |
Parameters
None.
Returns
Remarks
Your part typically calls its storage unit's GetSession method instead of this method.
Related Methods
This method notifies this storage system to reserve memory for future use.
Signature
void NeedSpace (ODSize memSize,
ODBoolean doPurge)
|
Parameters
| 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.