Class Definition File | SUView.idl |
Class C++ Binding | SUView.xh |
Class Hierarchy |
SOMObject ODObject ODStorageUnitView |
Description | An object of the ODStorageUnitView class provides thread-safe access to a storage unit by focusing and locking the storage unit. A storage-unit view represents a particular storage unit, prefocused on a particular focus context. Your part creates a storage-unit view object by focusing a storage unit and then calling the CreateView method of that storage unit. You can pass the storage-unit view among your software components to give them access to the particular focused data stream. A storage-unit view has most of the functionality of a storage unit, except that it has no methods for changing the focus. When you access a storage unit through a storage-unit view, however, the storage-unit view locks the storage unit during the access and unlocks it afterward. The storage-unit view has an associated storage-unit cursor that represents the focus context of the storage-unit view. You can call the GetCursor method of a storage-unit view to obtain its storage-unit cursor. If you make changes to that storage-unit cursor, you change the focus context of the storage-unit view. Typically parts do not change the focus context of a storage-unit view. For more information related to storage units and storage-unit cursors, see the class descriptions for ODStorageUnit and ODStorageUnitCursor. |
Methods | The methods defined by the ODStorageUnitView class include: Storage Manipulating Storage Units Accessing Focus Context Manipulating Value
Manipulating Persistent Reference
Manipulating Promise Creating Objects |
Overridden Methods | There are no methods overridden by the ODStorageUnitView class. |
This method adds a property with the specified name to the storage unit that created this storage-unit view.
Signature
ODStorageUnitView *AddProperty (ODPropertyName propertyName) |
Parameters
Returns
Remarks
If the storage unit that created this storage-unit view does not already contain a property with the specified name, the new property is added and the storage unit is focused on the newly added property. Otherwise, the storage unit is focused on the existing property with the specified name.
The focus context of this storage-unit view remains unchanged.
Exception Handling
kODErrCannotAddProperty | The specified property cannot be added to the storage unit that created this storage-unit view. |
kODErrIllegalNullPropertyInput | The specified property name is null. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
Related Methods
This method adds a value of the specified type to the focused property.
Signature
ODStorageUnitView *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 the storage unit that created that storage-unit view is focused on the newly added value. Otherwise, the storage unit is focused on the existing value with the specified value type.
The focus context of this storage-unit view remains unchanged.
Exception Handling
kODErrInvalidType | The specified value type is improperly formed or illegal. |
kODErrUnfocusedStorageUnit | The focus context of this storage-unit view is not a property or a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
Related Methods
This method copies all properties and values of the storage unit that created this storage-unit view into 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 typically calls its draft's Clone method or WeakClone method instead of this method.
If this storage unit that created this storage-unit view 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.
The storage unit that created this storage-unit view is the source storage unit for the cloning operation. This method copies the source storage unit's data into the specified destination storage unit. If the source storage unit has persistent references to other objects, this method clones any additional 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 not the draft key for the current cloning operation. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
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 | The focus context of this storage-unit view is not a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
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 | The focus context of this storage-unit view is not a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
Related Methods
This method resolves all promises in the storage unit that created this storage-unit view and saves all its properties and values to persistent, external storage.
Signature
ODStorageUnitView *Externalize () |
Parameters
None.
Returns
Exception Handling
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
Related Methods
This method returns a reference to the storage-unit cursor representing the focus context of this storage-unit view.
Signature
ODStorageUnitCursor *GetCursor () |
Parameters
None.
Returns
Remarks
You can change the focus context of this storage-unit view by modifying the returned storage-unit cursor; typically, however, parts do not change the focus context of the storage-unit view.
You should not delete the returned storage-unit cursor.
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 | The focus context of this storage-unit view is not a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
Related Methods
This method returns the storage-unit ID for the storage unit that created this storage-unit view.
Signature
ODID GetID () |
Parameters
None.
Returns
Related Methods
This method returns the storage-unit ID of a referenced storage unit.
Signature
ODStorageUnitID GetIDFromStorageUnitRef (ODStorageUnitRef aRef) |
Parameters
Returns
Remarks
The focused value must be the same 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 | The focus context of this storage-unit view is not a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
Related Methods
This method returns the name of the storage unit that created this storage-unit view.
Signature
ODStorageUnitName GetName () |
Parameters
None.
Returns
Remarks
When you no longer need the returned name, you should deallocate it.
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 | The focus context of this storage-unit view is not a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
Related Methods
This method reads the 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 passed in the value parameter, you should deallocate that structure and its buffer.
Exception Handling
kODErrInvalidValueType | The specified value type is improperly formed or illegal. |
kODErrSUValueDoesNotExist | The focused property does not have a value with the specified value type. |
kODErrUnfocusedStorageUnit | The focus context of this storage-unit view is not a property or a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
Related Methods
This method returns the name of the property in the 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 a value. |
kODErrZeroRefCount | This storage unit has a reference count of zero. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
Related Methods
This method returns the size of the data in the focus context.
Signature
ODULong GetSize () |
Parameters
None.
Returns
Remarks
If the focus context is the storage unit that created this storage-unit view, this method returns the total size of all properties and values in the storage unit. If the focus context is a property, this method returns the total size of all values in the focused property. If the focus context is a value, this method returns the size of the data stream corresponding to the focused value.
If the focused value contains a promise value, the promise is fulfilled before the size of the value is evaluated.
Exception Handling
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
This method returns a reference to the storage unit that created this storage-unit view.
Signature
ODStorageUnit *GetStorageUnit () |
Parameters
None.
Returns
Remarks
This method does not increment the reference count of the returned storage unit. For that reason, if you cache the returned storage unit, you should call its Acquire method to increment its reference count and then call its Release method when you are finished using it.
This method creates a strong persistent reference to the specified storage unit.
Signature
void GetStrongStorageUnitRef (ODStorageUnitID embeddedSUID, ODStorageUnitRef strongRef) |
Parameters
Returns
None.
Remarks
After this method executes successfully, you can call the SetValue method to store the resulting persistent reference, returned in the strongRef output parameter, into the focused value.
Note:
The scope of a persistent reference is limited to the value in which it was created; therefore, when retrieving the storage unit, you must focus it on the same value that the persistent reference was created in.
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 | The focus context of this storage-unit view is not a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
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 | The focus context of this storage-unit view is not a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
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 is 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 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 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 passed in the value parameter, you should deallocate that structure and its buffer.
Exception Handling
kODErrUnfocusedStorageUnit | The focus context of this storage-unit view is not a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
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
After this method executes successfully, you can call the SetValue method to store the resulting persistent reference, returned in the weakRef output parameter, into the focused value.
Note:
The scope of a persistent reference is limited to the value in which it was created; therefore, when retrieving the storage unit, you must focus it on the same value that the persistent reference was created in.
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 | The focus context of this storage-unit view is not a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
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 | The focus context of this storage-unit view is not a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
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 | The focus context of this storage-unit view is not a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
Related Methods
This method reads into memory all properties and values from the storage unit that created this storage-unit view.
Signature
ODStorageUnitView *Internalize () |
Parameters
None.
Returns
Remarks
OpenDoc calls this method; your part does not call this method.
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 | The focus context of this storage-unit view is not a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
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 | The focus context of this storage-unit view is not a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
Related Methods
This method indicates whether the specified persistent reference is valid.
Signature
ODBoolean IsValidStorageUnitRef (ODStorageUnitRef ref) |
Parameters
Returns
kODTrue | The specified persistent reference is valid. |
kODFalse | The specified persistent reference is not valid. |
Exception Handling
kODErrUnfocusedStorageUnit | The focus context of this storage-unit view is not a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
This method indicates whether the specified 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 | The focus context of this storage-unit view is not a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
Related Methods
This method removes all properties and values in the focus context from the storage unit that created this storage-unit view.
Signature
ODStorageUnitView *Remove () |
Parameters
None.
Returns
Remarks
If the focus context of this storage-unit view is the entire storage unit, this method removes all properties and their values. If the focus context is a property, this method removes the focused property and all its values. If the focus context is a value, this method removes the focused value.
After this method executes successfully, the storage unit that created this storage-unit view is unfocused. The focus context of this storage-unit view is unchanged.
This method should be used with caution; if it executes successfully, it makes the focus context of this storage-unit view invalid.
Exception Handling
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
Related Methods
This method makes a persistent reference invalid in the focused value.
Signature
ODStorageUnitView *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 | The current focus context of this storage-unit view is not a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
Related Methods
This method sets the name of the storage unit that created this storage-unit view.
Signature
void SetName (ODStorageUnitName name) |
Parameters
Returns
None.
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 | The focus context of this storage-unit view is not a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
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 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 passed in the value parameter, you should deallocate that structure and its buffer.
Exception Handling
kODErrInvalidType | The specified value type improperly formed or illegal. |
kODErrUnfocusedStorageUnit | The focus context of this storage-unit view is not a property or a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
Related Methods
This method sets the type of the focused value.
Signature
void SetType (ODValueType valueType) |
Parameters
Returns
None.
Remarks
This method should be used with caution; it may make this storage-unit view invalid.
Exception Handling
kODErrInvalidValueType | The specified value type is improperly formed or illegal. |
kODErrUnfocusedStorageUnit | The focus context of this storage-unit view is not a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
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 passed in the value parameter, you should deallocate that structure and its buffer.
Exception Handling
kODErrUnfocusedStorageUnit | The focus context of this storage-unit view is not a value. |
If the storage-unit cursor for this storage-unit view does not represent a legal focus context for the storage unit that created this storage-unit view, this method returns exceptions raised by the FocusWithCursor method of that storage unit.
Related Methods