Programming Reference: ODStorageUnitView

# 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

- CloneInto
- Externalize
- Internalize

Manipulating Storage Units

- AddProperty
- AddValue
- GetID
- GetName
- GetSize
- GetStorageUnit
- Remove
- SetName

Accessing Focus Context

- GetCursor
- GetProperty

Manipulating Value

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

Manipulating Persistent Reference

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

Manipulating Promise

- GetPromiseValue
- IsPromiseValue
- SetPromiseValue

Creating Objects

- CreateStorageUnitRefIterator

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

- ODStorageUnitView::GetProperty
- ODStorageUnitView::Remove

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

- ODStorageUnitView::Remove

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

- ODDraft::Clone
- ODDraft::WeakClone

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

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

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

- ODStorageUnitView::InsertValue
- ODStorageUnitView::Remove

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

- ODStorageUnitView::Internalize

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

- ODStorageUnitView::IncrementGenerationNumber

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

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

- ODStorageUnitView::GetID

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

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

- ODStorageUnitView::GetSize
- ODStorageUnitView::SetOffset

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

- ODStorageUnitView::IsPromiseValue
- ODStorageUnitView::SetPromiseValue

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

- ODStorageUnitView::AddProperty
- ODStorageUnitView::Remove

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

- ODStorageUnitView::GetWeakStorageUnitRef
- ODStorageUnitView::IsStrongStorageUnitRef
- ODStorageUnitView::SetValue

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

- ODStorageUnitView::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) - 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

- ODStorageUnitView::GetSize
- ODStorageUnitView::SetValue

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

- ODStorageUnitView::GetStrongStorageUnitRef
- ODStorageUnitView::IsWeakStorageUnitRef
- ODStorageUnitView::SetValue

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

- ODStorageUnitView::GetGenerationNumber

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

- ODStorageUnitView::DeleteValue
- ODStorageUnitView::SetValue

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

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

- ODStorageUnitView::GetPromiseValue
- ODStorageUnitView::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 | 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

- ODStorageUnitView::GetStrongStorageUnitRef
- ODStorageUnitView::IsValidStorageUnitRef
- ODStorageUnitView::IsWeakStorageUnitRef

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

- ODStorageUnitView::GetWeakStorageUnitRef
- ODStorageUnitView::IsStrongStorageUnitRef
- ODStorageUnitView::IsValidStorageUnitRef

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

- ODStorageUnitView::AddProperty
- ODStorageUnitView::AddValue

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

- ODStorageUnitView::DeleteValue

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

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

- ODStorageUnitView::GetOffset
- ODStorageUnitView::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 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

- ODStorageUnitView::GetPromiseValue
- ODStorageUnitView::GetSize
- ODStorageUnitView::IsPromiseValue

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

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

- ODStorageUnitView::GetSize
- ODStorageUnitView::GetValue

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