Programming Reference: ODStorageUnit

# Programming Reference

## ODStorageUnit

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:

- Unfocused. When a storage unit is unfocused, its focus context is undefined.

- Focused on the entire storage unit. When the focus context is the storage unit, the data of interest includes all properties and all their values.

- Focused on a particular property. When the focus context is a property, the data of interest includes all values of the focused property.

- Focused on a particular value of a particular property. When the focus context is a value, the data of interest is the data stream corresponding to a focused value.

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.

- A storage-unit view represents the storage unit prefocused on a particular focus context. You can pass a storage-unit view among your software components to give them access to the particular focused data stream.

- A storage-unit cursor represents a focus context. You can create storage-unit cursors for focus contexts that you access frequently, then use those cursors to switch the focus from one context to another.

- A storage-unit reference iterator allows you to access all persistent references in the focused value of 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

- CloneInto
- Externalize
- Internalize
- Lock
- Unlock

Manipulating Storage Units

- AddProperty
- AddValue
- CountProperties
- CountValues
- GetID
- GetName
- GetSize
- Remove
- SetName

Manipulating Focuses

- Exists
- ExistsWithCursor
- Focus
- FocusWithCursor
- GetProperty

Manipulating Values

- DeleteValue
- GetGenerationNumber
- GetOffset
- GetType
- GetValue
- IncrementGenerationNumber
- InsertValue
- SetOffset
- SetType
- SetValue

Manipulating Persistent References

- GetIDFromStorageUnitRef
- GetStrongStorageUnitRef
- GetWeakStorageUnitRef
- IsStrongStorageUnitRef
- IsValidStorageUnitRef
- IsWeakStorageUnitRef
- RemoveStorageUnitRef
- SetStorageUnitRef

Manipulating Promises

- ClearAllPromises
- GetPromiseValue
- IsPromiseValue
- ResolveAllPromises
- SetPromiseValue

Creating Objects

- CreateCursor
- CreateCursorWithFocus
- CreateStorageUnitRefIterator
- CreateView

Utility Routines

- GetDraft
- GetSession

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

### AddProperty

This method adds a property with the specified name to this storage unit.

Signature

    ODStorageUnit *AddProperty (ODPropertyName propertyName)

Parameters

propertyName (ODPropertyName) - input

  The name of the property to be added.

Returns

rv (ODStorageUnit *) - returns

  A reference to this storage unit.

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

- ODStorageUnit::GetProperty
- ODStorageUnit::Remove

### AddValue

This method adds a value of the specified type to the focused property.

Signature

    ODStorageUnit *AddValue (ODValueType type)

Parameters

type (ODValueType) - input

  The type of value to be added.

Returns

rv (ODStorageUnit *) - returns

  A reference to this storage unit.

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

- ODStorageUnit::Remove

### ClearAllPromises

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

- ODStorageUnit::ResolveAllPromises

### CloneInto

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

key (ODDraftKey) - input

  The draft key identifying this cloning operation.

destStorageUnit (ODStorageUnit *) - input

  A reference to the destination storage unit to which the data is to be copied.

scopeID (ODID) - input

  The ID of the frame that defines the scope of this cloning operation or kODIDALL if all references objects are within scope.

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

- ODDraft::Clone
- ODDraft::WeakClone

### CountProperties

This method returns the number of properties in this storage unit.

Signature

    ODULong CountProperties ()

Parameters

None.

Returns

rv (ODULong) - returns

  The number of properties in this storage unit.

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

- ODStorageUnit::CountValues

### CountValues

This method returns the number of values in the current focus context for this storage unit.

Signature

    ODULong CountValues ()

Parameters

None.

Returns

rv (ODULong) - returns

  The number of values in this storage unit.

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

- ODStorageUnit::CountProperties

### CreateCursor

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

propertyName (ODPropertyName) - input

  The name of the property in the focus context or kODNULL if the focus context is the entire storage unit.

valueType (ODValueType) - input

  The value type of the value in the focus context, kODTypeAll for all value types, or kODNULL to ignore this parameter.

valueIndex (ODValueIndex) - input

  The value index of the value in the focus context, kODIndexAll for all value indexes, or 0 to ignore this parameter.

Returns

rv (ODStorageUnitCursor *) - returns

  A reference to the newly created storage-unit cursor.

Remarks

Your part calls this method; its parameters specify the focus context for the storage-unit cursor.

- To specify the entire storage unit as the focus context, pass kODNULL in the propertyName parameter, kODTypeAll in the valueType parameter, and kODIndexAll in the valueIndex parameter.

- To specify a property as the focus context, pass its name in the propertyName parameter, kODTypeAll in the valueType parameter, and kODIndexAll in the valueIndex parameter.

- To specify a value as the focus context, pass the name of the property containing the value in the propertyName parameter. You can specify the value by its type or its index:

  - To use its type, pass the type of the desired value in the valueType parameter and 0 in the valueIndex parameter.

  - To use its index, pass kODNULL in the valueType parameter and the index of the desired value in the valueIndex parameter.

Exception Handling

kODErrZeroRefCount | This storage unit has a reference count of 0.

Related Methods

- ODStorageUnit::CreateCursorWithFocus

### CreateCursorWithFocus

This method creates a storage-unit cursor representing the current focus context of this storage unit.

Signature

    ODStorageUnitCursor *CreateCursorWithFocus ()

Parameters

None.

Returns

rv (ODStorageUnitCursor *) - returns

  A reference to the newly created storage-unit cursor.

Exception Handling

kODErrZeroRefCount | This storage unit has a reference count of 0.

Related Methods

- ODStorageUnit::CreateCursor

### CreateStorageUnitRefIterator

This method creates a storage-unit reference iterator for the focused value.

Signature

    ODStorageUnitRefIterator *CreateStorageUnitRefIterator ()

Parameters

None.

Returns

rv (ODStorageUnitRefIterator *) - returns

  A reference to a storage-unit reference iterator used to traverse all persistent references in the focused value.

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:

- DeleteValue
- Internalize
- Remove
- RemoveStorageUnitRef
- SetStorageUnitRef
- SetType
- SetValue

Furthermore, you must not delete 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.

### CreateView

This method creates a storage-unit view for this storage unit with its current focus context.

Signature

    ODStorageUnitView *CreateView ()

Parameters

None.

Returns

rv (ODStorageUnitView *) - returns

  A reference to the newly created storage-unit view.

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.

### DeleteValue

This method deletes data from the focused value, starting at the offset (inclusive).

Signature

    void DeleteValue (ODULong length)

Parameters

length (ODULong) - input

  The number of bytes of data to be deleted.

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

- ODStorageUnit::InsertValue
- ODStorageUnit::Remove

### Exists

This method indicates whether the specified focus context exists in this storage unit.

Signature

    ODBoolean Exists (ODPropertyName propertyName,
                      ODValueType valueType,
                      ODValueIndex valueIndex)

Parameters

propertyName (ODPropertyName) - input

  The name of the property in the focus context or kODNULL for the focused property.

valueType (ODValueType) - input

  The value type of the value in the focus context, kODTypeAll for all value types, or kODNULL to ignore this parameter.

valueIndex (ODValueIndex) - input

  The value index of the value in the focus context, kODIndexAll for all value indexes, or 0 to ignore this parameter.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the specified focus context exists in this storage unit.

  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.

- To specify a property as the focus context, pass its name in the propertyName parameter or kODNULL for the focused property. Pass kODTypeAll in the valueType parameter and kODIndexAll in the valueIndex parameter.

- To specify a value as the focus context, pass the name of the property containing the value in the propertyName parameter or kODNULL for the focused property. You can specify the value by its type or its index:

  - To use its type, pass the type of the desired value in the valueType parameter and 0 in the valueIndex parameter.

  - To use its index, pass kODNULL in the valueType parameter and the index of the desired value in the valueIndex parameter.

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

- ODStorageUnit::ExistsWithCursor
- ODStorageUnit::Focus

### ExistsWithCursor

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

cursor (ODStorageUnitCursor *) - input

  A reference to the storage-unit cursor representing the focus context to be tested.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the focus context specified by the storage-unit cursor exists in this storage unit

  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

- ODStorageUnit::Exists
- ODStorageUnit::FocusWithCursor

### Externalize

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

rv (ODStorageUnit *) - returns

  A reference to this storage unit.

Exception Handling

kODErrZeroRefCount | This storage unit has a reference count of 0.

Related Methods

- ODStorageUnit::Internalize

### Focus

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

propertyName (ODPropertyName) - input

  The name of the property in the desired focus context or kODNULL to ignore this parameter.

propertyPosCode (ODPositionCode) - input

  The position code, relative to the desired focus context, of the property in the focus context or kODPosUndefined to ignore this parameter.

valueType (ODValueType) - input

  The value type of the value in the desired focus context, kODTypeAll for all value types, or kODNULL to ignore this parameter.

valueIndex (ODValueIndex) - input

  The value index of the value in the desired focus context, kODIndexAll for all value indexes, or 0 to ignore this parameter.

valuePosCode (ODPositionCode) - input

  The position code, relative to the current focus context, of the value in the desired focus context, or kODPosUndefined to ignore this parameter.

Returns

rv (ODStorageUnit *) - returns

  A reference to this storage unit, focused on the specified focus context.

Remarks

Your part calls this method; its parameters specify the desired focus context.

- To focus on the entire storage unit, pass kODNULL in the propertyName parameter, kODPosAll in the propertyPosCode parameter, kODTypeAll in the valueType parameter, 0 in the valueIndex parameter, and kODPosUndefined in the valuePosCode parameter.

- To focus on a property, pass its name in the propertyName parameter, or pass kODNULL in the propertyName parameter and the appropriate code in the propertyPosCode parameter. Pass kODTypeAll in the valueType parameter, 0 in the valueIndex parameter, and kODPosUndefined in the valuePosCode parameter.

- To focus on a value, specify the property containing the value using the propertyName parameter or the propertyPosCode parameter, as described in the previous item. You can specify the value by its type, its index, or its position.

  - To use its type, pass the type of the desired value in the valueType parameter, 0 in the valueIndex parameter, and kODPosUndefined in the valuePosCode parameter.

  - To use its index, pass kODNULL in the valueType parameter, the index of the desired value in the valueIndex parameter, and kODPosUndefined in the valuePosCode parameter.

  - To use its position code, pass kODNULL as the valueType parameter, 0 as the valueIndex parameter, and the appropriate code as the valuePosCode parameter.

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

- ODStorageUnit::Exists
- ODStorageUnit::FocusWithCursor

### FocusWithCursor

This method focuses this storage unit on the focus context represented by the specified storage-unit cursor.

Signature

    ODStorageUnit *FocusWithCursor (ODStorageUnitCursor *cursor)

Parameters

cursor (ODStorageUnitCursor *) - input

  A reference to the storage-unit cursor representing the desired focus context.

Returns

rv (ODStorageUnit *) - returns

  A reference to this storage unit, focused on the specified focus context.

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

- ODStorageUnit::ExistsWithCursor
- ODStorageUnit::Focus

### GetDraft

This method returns a reference to the draft object which created this storage unit.

Signature

    ODDraft *GetDraft ()

Parameters

None.

Returns

rv (ODDraft *) - returns

  A reference to the draft object which created this storage unit.

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.

### GetGenerationNumber

This method returns the generation number of the focused value.

Signature

    ODULong GetGenerationNumber ()

Parameters

None.

Returns

rv (ODULong) - returns

  The generation number of the focused value, expressed as an unsigned 32-bit value.

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

- ODStorageUnit::IncrementGenerationNumber

### GetID

This method returns the storage-unit ID for this storage unit.

Signature

    ODID GetID ()

Parameters

None.

Returns

rv (ODID) - returns

  The storage-unit ID for this storage unit.

Exception Handling

kODErrZeroRefCount | This storage unit has a reference count of 0.

Related Methods

- ODStorageUnit::GetIDFromStorageUnitRef

### GetIDFromStorageUnitRef

This method returns the storage-unit ID of a referenced storage unit.

Signature

    ODStorageUnitID GetIDFromStorageUnitRef (ODStorageUnitRef aRef)

Parameters

aRef (ODStorageUnitRef) - input

  A persistent storage-unit reference.

Returns

rv (ODStorageUnitID) - returns

  The storage-unit ID of the specified storage unit.

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

- ODStorageUnit::GetID

### GetName

This method returns the name of this storage unit.

Signature

    ODStorageUnitName GetName ()

Parameters

None.

Returns

rv (ODStorageUnitName) - returns

  The name of this storage unit or kODNULL if the storage unit does not have a name.

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

- ODStorageUnit::SetName

### GetOffset

This method returns the offset of the focused value.

Signature

    ODULong GetOffset ()

Parameters

None.

Returns

rv (ODULong) - returns

  The offset, in bytes, of the read/write position from the beginning of the data stream in the focused value.

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

- ODStorageUnit::GetSize
- ODStorageUnit::SetOffset

### GetPromiseValue

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

valueType (ODValueType) - input

  The type of the value from which the promise data is to be read.

offset (ODULong) - input

  The offset from which the promise data is to be retrieved, from the beginning of the value.

length (ODULong) - input

  The length, in bytes, of the data to be retrieved.

value (ODByteArray *) - in/out

  The byte array whose buffer is to contain the retrieved promise data.

sourcePart (ODPart **) - output

  A reference to the part that made the promise.

Returns

rv (ODULong) - returns

  The number of bytes read.

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

- ODStorageUnit::IsPromiseValue
- ODStorageUnit::SetPromiseValue

### GetProperty

This method returns the name of the property in the current focus context.

Signature

    ODPropertyName GetProperty ()

Parameters

None.

Returns

rv (ODPropertyName) - returns

  The name of the property in the current focus context.

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

- ODStorageUnit::AddProperty
- ODStorageUnit::Remove

### GetSession

This method returns a reference to the session object in which this storage unit runs.

Signature

    ODSession *GetSession ()

Parameters

None.

Returns

rv (ODSession *) - returns

  A reference to the session object in which this storage unit runs.

Exception Handling

kODErrZeroRefCount | This storage unit has a reference count of 0.

Related Methods

- ODStorageSystem::GetSession

### GetSize

This method returns the size of the data in the current focus context.

Signature

    ODULong GetSize ()

Parameters

None.

Returns

rv (ODULong) - returns

  The size, in bytes, of the data in the current focus context.

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.

### GetStrongStorageUnitRef

This method creates a strong persistence reference to the specified storage unit.

Signature

    void GetStrongStorageUnitRef (ODStorageUnitID embeddedSUID,
                                  ODStorageUnitRef strongRef)

Parameters

embeddedSUID (ODStorageUnitID) - input

  The storage-unit ID of the storage unit whose persistent reference is desired.

strongRef (ODStorageUnitRef) - output

  A persistent reference to the specified storage unit.

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

- ODStorageUnit::GetWeakStorageUnitRef
- ODStorageUnit::IsStrongStorageUnitRef
- ODStorageUnit::SetType

### GetType

This method returns the type of the focused value.

Signature

    ODValueType GetType ()

Parameters

None.

Returns

rv (ODValueType) - returns

  The type of the focused value.

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

- ODStorageUnit::SetType

### GetValue

This method reads data from the focused value, starting at the offset (inclusive).

Signature

    ODULong GetValue (ODULong length,
                      ODByteArray *value)

Parameters

length (ODULong) - in/out

  The length, in bytes, of data to be read.

value (ODByteArray *) - in/out

  The byte array whose buffer is to contain the retrieved data.

Returns

rv (ODULong) - returns

  The number of bytes read.

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

- ODStorageUnit::GetSize
- ODStorageUnit::SetType

### GetWeakStorageUnitRef

This method creates a weak persistent reference to the specified storage unit.

Signature

    void GetWeakStorageUnitRef (ODStorageUnitID embeddedSUID,
                                ODStorageUnitRef weakRef)

Parameters

embeddedSUID (ODStorageUnitID) - input

  The storage-unit ID of the storage unit whose persistent reference is desired.

weakRef (ODStorageUnitRef) - output

  The persistent reference to the specified storage unit.

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

- ODStorageUnit::GetStrongStorageUnitRef
- ODStorageUnit::IsWeakStorageUnitRef
- ODStorageUnit::SetType

### IncrementGenerationNumber

This method increments and returns the generation number of the focused value.

Signature

    ODULong IncrementGenerationNumber ()

Parameters

None.

Returns

rv (ODULong) - returns

  The generation number of the focused value.

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

- ODStorageUnit::GetGenerationNumber

### InsertValue

This method inserts data into the focused value, starting at the offset (inclusive).

Signature

    void InsertValue (ODByteArray *value)

Parameters

value (ODByteArray *) - input

  The byte array whose buffer contains the data to be written.

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

- ODStorageUnit::DeleteValue
- ODStorageUnit::SetType

### Internalize

This method reads all properties and values from this storage unit into memory.

Signature

    ODStorageUnit *Internalize ()

Parameters

None.

Returns

rv (ODStorageUnit *) - returns

  A reference to this storage unit.

Remarks

OpenDoc calls this method; your part does not call this method.

Exception Handling

kODErrInvalidStorageUnit | This storage unit is not valid.

Related Methods

- ODStorageUnit::Externalize

### IsPromiseValue

This method indicates whether the focused value is a promise value.

Signature

    ODBoolean IsPromiseValue ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the focused value is a promise value.

  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

- ODStorageUnit::GetPromiseValue
- ODStorageUnit::SetPromiseValue

### IsStrongStorageUnitRef

This method indicates whether the specified reference is a strong persistent reference.

Signature

    ODBoolean IsStrongStorageUnitRef (ODStorageUnitRef ref)

Parameters

ref (ODStorageUnitRef) - input

  The persistent reference to be tested. This value is assumed to be valid.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the specified reference is a strong persistent reference.

  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

- ODStorageUnit::GetStrongStorageUnitRef
- ODStorageUnit::IsValidStorageUnitRef
- ODStorageUnit::IsWeakStorageUnitRef

### IsValidStorageUnitRef

This method indicates whether the specified persistent reference is valid.

Signature

    ODBoolean IsValidStorageUnitRef (ODStorageUnitRef aRef)

Parameters

aRef (ODStorageUnitRef) - input

  The persistent reference to be tested.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the specified persistent reference is valid.

  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.

### IsWeakStorageUnitRef

This method indicates whether the specified persistent reference is a weak persistent reference.

Signature

    ODBoolean IsWeakStorageUnitRef (ODStorageUnitRef ref)

Parameters

ref (ODStorageUnitRef) - input

  The persistent reference to be tested. This value is assumed to be valid.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the specified reference is a weak persistent reference.

  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

- ODStorageUnit::GetWeakStorageUnitRef
- ODStorageUnit::IsStrongStorageUnitRef
- ODStorageUnit::IsValidStorageUnitRef

### Lock

This method locks this storage unit for exclusive access.

Signature

    ODStorageUnitKey Lock (ODStorageUnitKey key)

Parameters

key (ODStorageUnitKey) - input

  The previously acquired identifier for a particular clone operation, or the value kODNULLKey if the valid storage unit key is unknown.

Returns

rv (ODStorageUnitKey) - returns

  The identifier for the locked state of this storage unit.

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

- ODStorageUnit::Unlock

### Remove

This method removes all properties and values in the current focus context from this storage unit.

Signature

    ODStorageUnit *Remove ()

Parameters

None.

Returns

rv (ODStorageUnit *) - returns

  A reference to this storage unit.

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

- ODStorageUnit::AddProperty
- ODStorageUnit::AddValue

### RemoveStorageUnitRef

This method makes a persistent reference invalid in the focused value.

Signature

    ODStorageUnit *RemoveStorageUnitRef (ODStorageUnitRef aRef)

Parameters

aRef (ODStorageUnitRef) - input

  The persistent reference to be removed.

Returns

rv (ODStorageUnit *) - returns

  A reference to this storage unit.

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

- ODStorageUnit::DeleteValue

### ResolveAllPromises

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

- ODPart::FulfillPromise
- ODStorageUnit::ClearAllPromises

### SetName

This method sets the name of this storage unit.

Signature

    void SetName (ODStorageUnitName name)

Parameters

name (ODStorageUnitName) - input

  The name to be assigned to this storage unit.

Returns

None.

Exception Handling

kODErrZeroRefCount | This storage unit has a reference count of 0.

Related Methods

- ODStorageUnit::GetName

### SetOffset

This method sets the offset of the focused value.

Signature

    void SetOffset (ODULong offset)

Parameters

offset (ODULong) - input

  The new offset, in bytes, of the read/write position from the beginning of the data stream in the focused value.

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

- ODStorageUnit::GetOffset
- ODStorageUnit::GetSize

### SetPromiseValue

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

valueType (ODValueType) - input

  The type of the value where the promise data is to be written.

offset (ODULong) - input

  The offset at which the promise data is to be stored, from the beginning of the value.

value (ODByteArray *) - input

  The byte array whose buffer contains the promise data to be written.

sourcePart (ODPart *) - input

  A reference to the part that made the promise.

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

- ODStorageUnit::GetPromiseValue
- ODStorageUnit::GetSize
- ODStorageUnit::IsPromiseValue

### SetStorageUnitRef

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

embeddedSUID (ODStorageUnitID) - input

  The storage-unit ID for the storage unit to be referenced.

ref (ODStorageUnitRef) - input

  A persistent identifier for the new persistent reference being created.

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.

### SetType

This method sets the type of the focused value.

Signature

    void SetType (ODValueType valueType)

Parameters

valueType (ODValueType) - input

  The new type for the focused value.

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

- ODStorageUnit::GetType

### SetValue

This method writes data to the focused value, starting at the offset (inclusive).

Signature

    void SetValue (ODByteArray *value)

Parameters

value (ODByteArray *) - input

  A byte array whose buffer contains the data to be written.

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

- ODStorageUnit::GetSize
- ODStorageUnit::GetValue

### Unlock

This method unlocks this storage unit.

Signature

    void Unlock (ODStorageUnitKey key)

Parameters

key (ODStorageUnitKey) - input

  The storage unit key acquired from the Lock method.

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

- ODStorageUnit::Unlock

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