Programming Reference


ODStorageUnitView

     

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.

     

AddProperty

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

propertyName  (ODPropertyName)  -  input 

The name of the property to be added.

Returns

rv  (ODStorageUnitView *)  -  returns 

A reference to this storage-unit view.

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

     

AddValue

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

Signature
ODStorageUnitView *AddValue (ODValueType type)

Parameters

type  (ODValueType)  -  input 

The type of value to be added.

Returns

rv  (ODStorageUnitView *)  -  returns 

A reference to this storage-unit view.

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

     

CloneInto

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

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 referenced objects are within scope.

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

   

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 the 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:

Furthermore, you must not delete this storage-unit view.

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.      


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 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

     

Externalize

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

rv  (ODStorageUnitView *)  -  returns 

A reference to this storage-unit view.

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

   

GetCursor

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

rv  (ODStorageUnitCursor *)  -  returns 

A reference to the storage-unit cursor representing the focus context of this storage-unit view.

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.    


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.

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

   

GetID

This method returns the storage-unit ID for the storage unit that created this storage-unit view.

Signature
ODID GetID ()

Parameters

None.

Returns

rv  (ODID)  -  returns 

The storage-unit ID for the storage unit that created this storage-unit view.

Related Methods

   

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 storage unit referenced by the specified persistent reference.

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

   

GetName

This method returns the name of the storage unit that created this storage-unit view.

Signature
ODStorageUnitName GetName ()

Parameters

None.

Returns

rv  (ODStorageUnitName)  -  returns 

The name of the storage unit that created this storage-unit view or kODNULL if the storage unit does not have a name.

Remarks

When you no longer need the returned name, you should deallocate it.

Related Methods

   

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 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

   

GetPromiseValue

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

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 data to be retrieved.

value  (ODByteArray *)  -  input 

The byte array whose buffer contains 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 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

   

GetProperty

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

Signature
ODPropertyName GetProperty ()

Parameters

None.

Returns

rv  (ODPropertyName)  -  returns 

The name of the property in the 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 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

   

GetSize

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

Signature
ODULong GetSize ()

Parameters

None.

Returns

rv  (ODULong)  -  returns 

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

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.    


GetStorageUnit

This method returns a reference to the storage unit that created this storage-unit view.

Signature
ODStorageUnit *GetStorageUnit ()

Parameters

None.

Returns

rv  (ODStorageUnit *)  -  returns 

A reference to the storage unit that created this storage-unit view.

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.      


GetStrongStorageUnitRef

This method creates a strong persistent 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 

The persistent reference to the storage unit specified by the embeddedSUID parameter.

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

   

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 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

   

GetValue

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

Signature
ODULong GetValue (ODULong length,
                  ODByteArray *value)

Parameters

length  (ODULong)  -  input 

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

value  (ODByteArray *)  -  in/out 

A 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 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

     

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 storage unit specified by the embeddedSUID parameter.

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

   

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 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

   

InsertValue

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

Signature
void InsertValue (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 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

   

Internalize

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

rv  (ODStorageUnitView *)  -  returns 

A reference to this storage-unit view.

Remarks

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

Related Methods

 

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 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

 

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 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

 

IsValidStorageUnitRef

This method indicates whether the specified persistent reference is valid.

Signature
ODBoolean IsValidStorageUnitRef (ODStorageUnitRef ref)

Parameters

ref  (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 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.  


IsWeakStorageUnitRef

This method indicates whether the specified 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 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

   

Remove

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

rv  (ODStorageUnitView *)  -  returns 

A reference to this storage-unit view.

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

     

RemoveStorageUnitRef

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

Signature
ODStorageUnitView *RemoveStorageUnitRef (ODStorageUnitRef aRef)

Parameters

aRef  (ODStorageUnitRef)  -  input 

The persistent reference to be removed.

Returns

rv  (ODStorageUnitView *)  -  returns 

A reference to this storage-unit view.

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

   

SetName

This method sets the name of the storage unit that created this storage-unit view.

Signature
void SetName (ODStorageUnitName name)

Parameters

name  (ODStorageUnitName)  -  input 

The name to be assigned to the storage unit that created this storage-unit view.

Returns

None.

Related Methods

   

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 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

       

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 from which the promise data is to be stored, from the beginning of the value.

value  (ODByteArray *)  -  input 

A 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 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

   

SetType

This method sets the type of the focused value.

Signature
void SetType (ODValueType valueType)

Parameters

valueType  (ODValueType)  -  input 

The new type of the focused value.

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

   

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 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


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