Class Definition File | StorageU.idl |
Class C++ Binding | StorageU.xh |
Class Hierarchy |
SOMObject ODObject ODRefCntObject ODStorageUnit |
Description | An object of the ODStorageUnit class represents the basic unit of persistent storage. The ODStorageUnit class is implemented differently for different platforms and storage mechanisms. The 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 one another at many levels. Every persistent object has an associated storage unit where it stores its data persistently. Storage units are also used for data-transfer operations; the clipboard and the drag-and-drop object each have a content storage unit where they store the data to be transferred. Because storage units may no longer be valid as soon as a data transfer is complete, you should never cache a reference to a data-transfer object's storage unit. Your part creates a new storage unit by calling its draft's CreateStorageUnit method. It accesses an existing storage unit by calling its draft's AcquireStorageUnit method. A storage unit consists of one or more properties, each of which has a unique name within the storage unit and is distinguished by the kind of information it contains (such as "name" or "content"). For example, the properties in your part's storage unit are used to store persistently both the content of your part and also supplemental information. OpenDoc defines a standard set of properties for all parts. You can define additional properties for information specific to your particular part. A property consists of one or more data streams, called values, each of which has a named type. Each property can have only one value of a given type. In a data-transfer operation, the source part writes data to one of more values of the data-transfer object's content storage unit; the destination part reads from those values. The source part can write the data to be transferred or a promise, which is a specification of data to be transferred at a future time. A value that contains promises data is called a promise value; a value that does not contain promise data is called a regular value. When and if a destination tries to read the promise, the storage unit first resolves the promise by asking the source part to fulfill it. The source part fulfills the promise by replacing the promise in the storage unit with the actual data that was promised. OpenDoc assigns a runtime identifier, a storage-unit ID, to each of its storage units. A storage-unit ID is a nonpersistent identifier for a storage unit that is unique within its draft (storage-unit IDs are not unique across drafts and do not persist across sessions). You can use the storage-unit ID to identify storage units and to compare two storage units for equality. The ID of the storage unit for a persistent object is also used as the ID of the object itself. If you retain the ID of a persistent object when you release it, you can use that ID to recreate the object from the data stored in its storage unit. For example, when a frame is scrolled out of view, you can save its ID and release it; if the frame is later scrolled back into view, you can obtain a reference to it by passing the saved ID to the draft's AcquireFrame method. If the frame has been purged since you released it, the AcquireFrame method recreates it from its stored data. Storage units can maintain persistent references to other storage units in the same draft. A persistent reference stored in a storage unit value is an opaque type that identifies another storage unit in the same draft. Whereas the ID of a storage unit identifies another storage unit within the current session, a persistent reference to the storage unit identifies it persistently across sessions. Persistent references permit complex runtime relationships between objects to be stored externally and later reconstructed; for example, the embedding relationships of the parts within a draft are preserved by persistent references to the part's storage unit. Persistent references can be strong or weak. In a clone operation, copies are made of all storage units referenced by strong persistent reference in the object being cloned. A weak persistent reference is typically ignored during cloning; however, if a storage unit is cloned because there are strong persistent references to it, then weak persistent references to the storage unit are preserved. OpenDoc allows you to focus a storage unit on the particular data of interest, called the focus context. Before reading or writing to a storage unit, for example, you must focus on the data stream defined by a particular value of a particular property. At any time, the storage unit can be in one of the following states:
To define a focus context, you can specify a property by its name or a position code. Within a given property, you can specify the value of interest by a value type, a position code, or a value index. A position code is a constant that specifies an absolute position for the property or value, or a position relative to the property or value in the current focus context. Position codes allow you to access the next or previous property within a set of properties in a storage unit or the next or previous value within a set of values in the same property. A value index is a number representing the ordinal position of the value within the property. The first value created for a property has index 1; the second, 2; and so on. When the storage unit is focused on a value of a property, you can read data from and write data to the corresponding data stream. The storage unit has a zero-based offset that specifies the current read/write position in the stream. When the storage unit is first focused, the offset is 0, indicating the beginning of the stream. Each read and write advances the offset by the number of bytes that were read or written. The storage unit also has methods that allow you to get and set the current offset. You can call methods of a storage unit to create related objects that make it easy to work with the data in the storage unit.
For more information about these objects, see the descriptions of the classes ODStorageUnitView, ODStorageUnitCursor, and ODStorageUnitRefIterator. |
Methods | The methods defined by the ODStorageUnit class include: Accessing and Storing Manipulating Storage Units Manipulating Focuses Manipulating Values
Manipulating Persistent References
Manipulating Promises Creating Objects Utility Routines |
Overridden Methods | There are no methods overridden by the ODStorageUnit class. |
This method adds a property with the specified name to this storage unit.
Signature
ODStorageUnit *AddProperty (ODPropertyName propertyName) |
Parameters
Returns
Remarks
If the storage unit does not already contain a property with the specified name, the new property is added and this storage unit is focused on the newly added property. Otherwise, this storage unit is focused on the existing property with the specified name.
Note:
The propertyName parameter of AddProperty cannot be the same as the type parameter of AddValue.
Exception Handling
kODErrCannotAddProperty | Cannot add the specified property to this storage unit. |
kODErrIllegalNullPropertyInput | The specified property name is null. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method adds a value of the specified type to the focused property.
Signature
ODStorageUnit *AddValue (ODValueType type) |
Parameters
Returns
Remarks
If the focused property does not already contain a value of the specified type, the new value is added and this storage unit is focused on the newly added value. Otherwise, this storage unit is focused on the existing value with the specified value type.
Note:
The propertyName parameter of AddProperty cannot be the same as the type parameter of AddValue.
Exception Handling
kODErrInvalidType | The specified value type is null. |
kODErrUnfocusedStorageUnit | This storage unit is not focused on a property. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method changes all promise values in this storage unit into regular values.
Signature
void ClearAllPromises () |
Parameters
None.
Returns
None.
Remarks
This method does not change the data in any promise values. It changes the values from promise values to regular values.
After this method executes successfully, the storage unit is unfocused.
Exception Handling
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method copies all properties and values of this storage unit to the specified destination storage unit.
Signature
void CloneInto (ODDraftKey key, ODStorageUnit *destStorageUnit, ODID scopeID) |
Parameters
Returns
None.
Remarks
This method is not called by parts. Your part should call its draft's Clone or WeakClone method instead of this method.
If this storage unit has persistent references to other objects, the scopeID parameter determines which of the referenced objects are within the scope of this cloning operation. Typically, the scopeID parameter is the ID of a frame, and only those objects embedded in that frame are within scope.
This method copies this storage unit's data into the specified destination storage unit. If this storage unit has persistent references to other objects, this method clones any persistent referenced objects that are within the scope of this cloning operation. Objects referenced by strong persistent references are strongly cloned by recursive calls to the Clone method; objects referenced by weak persistent references are weakly cloned by calls to the WeakClone method.
Exception Handling
kODErrInvalidDraftKey | The specified draft key is invalid. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method returns the number of properties in this storage unit.
Signature
ODULong CountProperties () |
Parameters
None.
Returns
Remarks
After this method executes successfully, the focus context of this storage unit is not changed.
Exception Handling
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method returns the number of values in the current focus context for this storage unit.
Signature
ODULong CountValues () |
Parameters
None.
Returns
Remarks
This storage unit must be focused on a property or a value, not the entire storage unit.
Exception Handling
kODErrUnfocusedStorageUnit | This storage unit is not focused on a property or a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method creates a storage-unit cursor representing the specified focus context for this storage unit.
Signature
ODStorageUnitCursor *CreateCursor (ODPropertyName propertyName, ODValueType valueType, ODValueIndex valueIndex) |
Parameters
Returns
Remarks
Your part calls this method; its parameters specify the focus context for the storage-unit cursor.
Exception Handling
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method creates a storage-unit cursor representing the current focus context of this storage unit.
Signature
ODStorageUnitCursor *CreateCursorWithFocus () |
Parameters
None.
Returns
Exception Handling
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method creates a storage-unit reference iterator for the focused value.
Signature
ODStorageUnitRefIterator *CreateStorageUnitRefIterator () |
Parameters
None.
Returns
Remarks
You can call this method if you need to perform an operation on all storage-unit references in the focused value.
While you are using the returned storage-unit reference iterator, you must not modify the focused value; in particular, you must not call any of the following methods of this storage unit:
You must delete the returned storage-unit reference iterator when it is no longer needed.
Exception Handling
kODErrUnfocusedStorageUnit | This storage unit is not focused on a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
This method creates a storage-unit view for this storage unit with its current focus context.
Signature
ODStorageUnitView *CreateView () |
Parameters
None.
Returns
Remarks
Your part calls this method.
Exception Handling
kODErrUnfocusedStorageUnit | This storage unit is not focused on a property or a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
This method deletes data from the focused value, starting at the offset (inclusive).
Signature
void DeleteValue (ODULong length) |
Parameters
Returns
None.
Remarks
You call this method to delete data from the focused value. If that value is a promise value, the promise is fulfilled before the data is deleted. This method starts deleting data at the current offset and stops after deleting the number of bytes specified by the length parameter or after reaching the end of the data in the focused value, whichever comes first.
Exception Handling
kODErrUnfocusedStorageUnit | This storage unit is not focused on a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method indicates whether the specified focus context exists in this storage unit.
Signature
ODBoolean Exists (ODPropertyName propertyName, ODValueType valueType, ODValueIndex valueIndex) |
Parameters
Returns
kODTrue | The specified focus exists. |
kODFalse | The specified focus does not exist. |
Remarks
You can call this method to see if you can focus this storage unit on the specified focus context. However, this method does not change the current focus context. The parameters specify the context to be checked.
If this method returns kODTrue, it is safe to call the Focus method with the specified focus context.
Exception Handling
kODErrInvalidPropertyName | The specified property name is improperly formed or illegal. |
kODErrInvalidType | The specified value type is improperly formed or illegal. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method indicates whether the focus context represented by the specified storage-unit cursor exists in this storage unit.
Signature
ODBoolean ExistsWithCursor (ODStorageUnitCursor *cursor) |
Parameters
Returns
kODTrue | The focus context specified by the storage-unit cursor exists in this storage unit |
kODFalse | The focus context specified by the storage-unit cursor does not exist in this storage unit |
Remarks
You can call this method to see whether you can focus this storage unit using the specified storage-unit cursor; however, this method does not change the current focus context.
If this method returns kODTrue, it is safe to call the FocusWithCursor method with the specified storage-unit cursor.
Exception Handling
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method resolves all promises in this storage unit and saves all properties and values to persistent, external storage.
Signature
ODStorageUnit *Externalize () |
Parameters
None.
Returns
Exception Handling
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method focuses this storage unit on the specified focus context.
Signature
ODStorageUnit *Focus (ODPropertyName propertyName, ODPositionCode propertyPosCode, ODValueType valueType, ODValueIndex valueIndex, ODPositionCode valuePosCode) |
Parameters
Returns
Remarks
Your part calls this method; its parameters specify the desired focus context.
After this method executes successfully, this storage unit's offset is 0.
Before calling this method, you can call the Exists method to check whether the specified focus context exists.
Exception Handling
kODErrInvalidPropertyName | The specified property name is improperly formed or illegal. |
kODErrInvalidType | The value type parameter is unknown or null. |
kODErrInvalidValue | This storage unit does not contain the specified value. |
kODErrUnsupportedPosCode | One of the specified position codes is not supported. |
kODErrValueIndexOutOfRange | The specified property has no value at the specified index. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method focuses this storage unit on the focus context represented by the specified storage-unit cursor.
Signature
ODStorageUnit *FocusWithCursor (ODStorageUnitCursor *cursor) |
Parameters
Returns
Remarks
After this method executes successfully, this storage unit's offset is 0.
Before calling this method, you can call the ExistsWithCursor method to check whether the specified focus context exists.
Exception Handling
kODErrIllegalNullSUCursorInput | The cursor parameter is null. |
kODErrInvalidProperty | The cursor parameter specifies a property that does not exist. |
kODErrInvalidValue | The cursor parameter specifies a value type that does not exist for the specified property. |
kODErrValueIndexOutOfRange | The cursor parameter specifies a value index that is out of range for the specified property. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method returns a reference to the draft object which created this storage unit.
Signature
ODDraft *GetDraft () |
Parameters
None.
Returns
Remarks
This method does not increment the reference count of the returned draft. For that reason, if you cache the returned draft, you should call its Acquire method to increment its reference count and then call its Release method when you are finished using it.
Exception Handling
kODErrZeroRefCount | This storage unit has a reference count of 0. |
This method returns the generation number of the focused value.
Signature
ODULong GetGenerationNumber () |
Parameters
None.
Returns
Remarks
You can use the generation number of a value to tell whether the data in the value has changed. For example, your part could compare the number returned by this method with a saved generation number.
Exception Handling
kODErrUnfocusedStorageUnit | This storage unit is not focused on a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method returns the storage-unit ID for this storage unit.
Signature
ODID GetID () |
Parameters
None.
Returns
Exception Handling
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method returns the storage-unit ID of a referenced storage unit.
Signature
ODStorageUnitID GetIDFromStorageUnitRef (ODStorageUnitRef aRef) |
Parameters
Returns
Remarks
Before you call this method, you must focus this storage unit on the value that created the specified persistent reference. This method looks up the storage unit referenced by the specified persistent reference and returns its storage-unit ID.
Exception Handling
kODErrInvalidStorageUnitRef | The specified persistent reference is not valid. |
kODErrUnfocusedStorageUnit | This storage unit is not focused on a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method returns the name of this storage unit.
Signature
ODStorageUnitName GetName () |
Parameters
None.
Returns
Remarks
When you no longer need the returned name, you should deallocate it.
Exception Handling
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method returns the offset of the focused value.
Signature
ODULong GetOffset () |
Parameters
None.
Returns
Remarks
An offset of 0 means the beginning of the data stream corresponding to the focused value; an offset equal to the size returned by the GetSize method means the end of the data stream.
Exception Handling
kODErrUnfocusedStorageUnit | This storage unit is not focused on a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method reads promise data from the specified value of the focused property.
Signature
ODULong GetPromiseValue (ODValueType valueType, ODULong offset, ODULong length, ODByteArray *value, ODPart **sourcePart) |
Parameters
Returns
Remarks
You call this method to read promise data without fulfilling the promise. This method first focuses the storage unit on the specified value of the focused property. It then starts reading data at the specified offset and stops after reading the number of bytes specified by the length parameter or after reaching the end of data in the focused value, whichever comes first.
When you call this method, the _buffer field of the value output parameter should be kODNULL; if it is not, the buffer to which that field points will not be deallocated.
This method sets the _buffer field of the value output parameter to point to a memory block containing the promise data, the _maximum field to the specified length, and _length field to the number of bytes actually read.
This method sets the sourcePart parameter to a reference to the part that made the promise. This method does not increment the reference count of the part that made the promise.
When you no longer need the structure you pass the value parameter, you should deallocate that structure and its buffer.
Exception Handling
kODErrInvalidType | The specified value type is improperly formed or illegal. |
kODErrInvalidValue | This ocused property does not have a value with the specified value type. |
kODErrUnfocusedStorageUnit | This storage unit is not focused on a property or value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method returns the name of the property in the current focus context.
Signature
ODPropertyName GetProperty () |
Parameters
None.
Returns
Remarks
When you no longer need the returned property name, you should deallocate it.
Exception Handling
kODErrUnfocusedStorageUnit | This storage unit is not focused on a property or value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method returns a reference to the session object in which this storage unit runs.
Signature
ODSession *GetSession () |
Parameters
None.
Returns
Exception Handling
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method returns the size of the data in the current focus context.
Signature
ODULong GetSize () |
Parameters
None.
Returns
Remarks
If this storage unit is focused on the entire storage unit, this method returns the total size of all properties and values in this storage unit. If it is focused on a property, this method returns the total size of all values in the focused property. If it is focused on a value, this method returns the size of the data stream corresponding to the focused value.
If the focused value is a promise value, the promise is fulfilled before the size of the value is evaluated.
Exception Handling
kODErrZeroRefCount | This storage unit has a reference count of 0. |
This method creates a strong persistence reference to the specified storage unit.
Signature
void GetStrongStorageUnitRef (ODStorageUnitID embeddedSUID, ODStorageUnitRef strongRef) |
Parameters
Returns
None.
Remarks
Before you call this method, you should focus this storage unit on the value where you want to store the strong persistent reference. After this method executes successfully, call the SetValue method to store the resulting persistent reference, returned in the strongRef parameter, into the focused value.
Note:
The scope of a persistent reference is limited to the value in which it was created. When retrieving the storage unit, you must focus it on the same value in which the persistent reference was created.
For more information on persistent references, see the chapter on storage in the OpenDoc Programming Guide.
Exception Handling
kODErrIllegalNullStorageUnitInput | The embeddedSUID parameter is null. |
kODErrUnfocusedStorageUnit | This storage unit is not focused on a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method returns the type of the focused value.
Signature
ODValueType GetType () |
Parameters
None.
Returns
Remarks
When you no longer need the returned value type, you should deallocate it.
Exception Handling
kODErrUnfocusedStorageUnit | This storage unit is not focused on a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method reads data from the focused value, starting at the offset (inclusive).
Signature
ODULong GetValue (ODULong length, ODByteArray *value) |
Parameters
Returns
Remarks
You call this method to read data from the focused value. If that value contains a promise value, the promise is fulfilled before the data is read. This method starts reading data at the current offset and stops after reading the number of bytes specified by the length parameter or after reaching the end of the data in the focused value, whichever comes first.
When you call this method, the _buffer field of the value parameter should be kODNULL; if it is not, the buffer to which that field points will not be deallocated.
This method sets the _buffer field of the value output parameter to point to the memory block containing the data that is read from the storage unit; it sets the _maximum field to the specified length and the _length field to the number of bytes actually read.
When you no longer need the structure you pass as the value parameter, you should deallocate that structure and its buffer.
Exception Handling
kODErrUnfocusedStorageUnit | This storage unit is not focused on a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method creates a weak persistent reference to the specified storage unit.
Signature
void GetWeakStorageUnitRef (ODStorageUnitID embeddedSUID, ODStorageUnitRef weakRef) |
Parameters
Returns
None.
Remarks
Before you call this method, you should focus this storage unit on the value where you want to store the weak persistent reference. After this method executes successfully, call the SetValue method to store the resulting persistent reference, returned in the weakRef parameter, into the focused value.
Note:
The scope of a persistent reference is limited to the value in which it was created. When retrieving the storage unit, you must focus it on the same value in which the persistent reference was created.
For more information on persistent references, see the chapter on storage in the OpenDoc Programming Guide.
Exception Handling
kODErrIllegalNullStorageUnitInput | The embeddedSUID parameter is null. |
kODErrUnfocusedStorageUnit | This storage unit is not focused on a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method increments and returns the generation number of the focused value.
Signature
ODULong IncrementGenerationNumber () |
Parameters
None.
Returns
Remarks
You can use the generation number of a value to tell whether the data in the value has changed. For example, when your part makes a significant change to the data in a value, you can call this method to increment its generation number.
Exception Handling
kODErrUnfocusedStorageUnit | This storage unit is not focused on a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method inserts data into the focused value, starting at the offset (inclusive).
Signature
void InsertValue (ODByteArray *value) |
Parameters
Returns
None.
Remarks
You call this method to insert data into the focused value without overwriting the existing data at and beyond the current offset. If the focused value is a promise value, the promise is fulfilled before the data is written.
This method writes data to the focused value, starting at the current offset. If the focused value contained any data at and beyond the offset, that data appears after the inserted data. The size of the value is increased to accommodate the inserted data.
When you no longer need the structure you pass as the value parameter, you should deallocate that structure and its buffer.
Exception Handling
kODErrUnfocusedStorageUnit | This storage unit is not focused on a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method reads all properties and values from this storage unit into memory.
Signature
ODStorageUnit *Internalize () |
Parameters
None.
Returns
Remarks
OpenDoc calls this method; your part does not call this method.
Exception Handling
kODErrInvalidStorageUnit | This storage unit is not valid. |
Related Methods
This method indicates whether the focused value is a promise value.
Signature
ODBoolean IsPromiseValue () |
Parameters
None.
Returns
kODTrue | The focused value is a promise value. |
kODFalse | The focused value is a regular value. |
Remarks
If the focused value is a promise value, the promise is not resolved by this method.
Exception Handling
kODErrUnfocusedStorageUnit | This storage unit is not focused on a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method indicates whether the specified reference is a strong persistent reference.
Signature
ODBoolean IsStrongStorageUnitRef (ODStorageUnitRef ref) |
Parameters
Returns
kODTrue | The specified reference is a strong persistent reference. |
kODFalse | The specified reference is not a strong persistent reference. |
Remarks
Before calling this method, you can call the IsValidStorageUnitRef method to check whether the specified persistent reference is valid.
Exception Handling
kODErrUnfocusedStorageUnit | This storage unit is not focused on a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method indicates whether the specified persistent reference is valid.
Signature
ODBoolean IsValidStorageUnitRef (ODStorageUnitRef aRef) |
Parameters
Returns
kODTrue | The specified persistent reference is valid. |
kODFalse | The specified persistent reference is not valid. |
Exception Handling
kODErrUnfocusedStorageUnit | This storage unit is not focused on a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
This method indicates whether the specified persistent reference is a weak persistent reference.
Signature
ODBoolean IsWeakStorageUnitRef (ODStorageUnitRef ref) |
Parameters
Returns
kODTrue | The specified reference is a weak persistent reference. |
kODFalse | The specified reference is not a weak persistent reference. |
Remarks
Before calling this method, you can call the IsValidStorageUnitRef method to check whether the specified persistent reference is valid.
Exception Handling
kODErrUnfocusedStorageUnit | This storage unit is not focused on a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method locks this storage unit for exclusive access.
Signature
ODStorageUnitKey Lock (ODStorageUnitKey key) |
Parameters
Returns
Remarks
Every thread must acquire the storage unit key for multithreading support.
Exception Handling
kODErrInvalidStorageUnitKey | The specified storage unit key is not valid. |
Related Methods
This method removes all properties and values in the current focus context from this storage unit.
Signature
ODStorageUnit *Remove () |
Parameters
None.
Returns
Remarks
If the current focus context is the entire storage unit, this method removes all properties and their values. If it is focused on a property, this method removes the focused property and all its values. If it is focused on a value, this method removes the focused value.
After this method executes successfully, the storage unit is unfocused.
Exception Handling
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method makes a persistent reference invalid in the focused value.
Signature
ODStorageUnit *RemoveStorageUnitRef (ODStorageUnitRef aRef) |
Parameters
Returns
Remarks
This method does not change the data in the focused value, but after this method is called, the specified persistent reference is no longer valid. To remove data corresponding to the persistent reference, you must call the DeleteValue method.
Exception Handling
kODErrUnfocusedStorageUnit | This storage unit is not focused on a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method resolves all promises in this storage unit.
Signature
void ResolveAllPromises () |
Parameters
None.
Returns
None.
Remarks
To resolve a promise, the storage unit calls the FulfillPromise method of the part that made the promise. This method does not change the current focus context.
Exception Handling
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method sets the name of this storage unit.
Signature
void SetName (ODStorageUnitName name) |
Parameters
Returns
None.
Exception Handling
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method sets the offset of the focused value.
Signature
void SetOffset (ODULong offset) |
Parameters
Returns
None.
Remarks
You can call this method if you want to read or write data at a particular position in the focused value. An offset of 0 means the beginning of the data stream corresponding to the focused value; an offset equal to the current size of the focused value (as returned by the GetSize method) means the end of the data stream. You may not specify an offset larger than the current size of the focused value.
Exception Handling
kODErrUnfocusedStorageUnit | This storage unit is not focused on a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method writes data to the specified value of the focused property, creating the value if it does not exist and making the value a promise value.
Signature
void SetPromiseValue (ODValueType valueType, ODULong offset, ODByteArray *value, ODPart *sourcePart) |
Parameters
Returns
None.
Remarks
You call this method to write a promise for a value of the specified type in the focused property. You may call this method multiple times to promise values of different types or to write to different offsets in the same value.
This method writes data to the specified value, starting at the specified offset (inclusive), and overwrites any data at and beyond the offset. If the current offset plus the length of the data being written is greater than the current size of the value (as returned by the GetSize method), the size of the value is increased to accommodate the new data.
When you no longer need the structure you pass as the value parameter, you should deallocate that structure and its buffer.
Exception Handling
kODErrInvalidType | The specified value type is null. |
kODErrUnfocusedStorageUnit | This storage unit is not focused on a property or value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method creates, in the focused value, a specified persistent reference to the specified storage unit using the specified persistent identifier.
Signature
void SetStorageUnitRef (ODStorageUnitID embeddedSUID, ODStorageUnitRef ref) |
Parameters
Returns
None.
Remarks
This method is called only by the container suite. Parts, the document shell, and container applications should call this method.
The embeddedSUID parameter specifies the ID that identifies the storage unit within the current session. The ref parameter specifies the reference to be used within the focused value to identify the storage unit persistently across sessions.
Exception Handling
kODErrInvalidID | The embeddedSUID parameter is invalid. |
kODErrUnfocusedStorageUnit | This storage unit is not focused on a property and value. |
This method sets the type of the focused value.
Signature
void SetType (ODValueType valueType) |
Parameters
Returns
None.
Exception Handling
kODErrInvalidType | The specified value type is improperly formed or illegal. |
kODErrUnfocusedStorageUnit | This storage unit is not focused on a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method writes data to the focused value, starting at the offset (inclusive).
Signature
void SetValue (ODByteArray *value) |
Parameters
Returns
None.
Remarks
You call this method to write data to the focused value. If that value is a promise value, the promise is fulfilled before the data is written.
This method writes data to the focused value, starting at the current offset, and overwrites any data at and beyond the offset. If the current offset plus the length of data being written is greater than the current size of the value (as returned by the GetSize method), the size of the value is increased to accommodate the new data.
When you no longer need the structure you pass as the value parameter, you should deallocate that structure and its buffer.
Exception Handling
kODErrUnfocusedStorageUnit | This storage unit is not focused on a value. |
kODErrZeroRefCount | This storage unit has a reference count of 0. |
Related Methods
This method unlocks this storage unit.
Signature
void Unlock (ODStorageUnitKey key) |
Parameters
Returns
None.
Remarks
Every thread must acquire the storage unit key for multithreading support.
Exception Handling
kODErrInvalidStorageUnitKey | The specified storage unit key is not valid. |
kODErrStorageUnitNotLocked | This storage unit is not locked. |
Related Methods