Programming Reference: ODStorageUnitCursor

# Programming Reference

## ODStorageUnitCursor

Class Definition File | SUCursor.idl
Class C++ Binding | SUCursor.xh

Class Hierarchy

    SOMObject
       ODObject
          ODStorageUnitCursor

Description

An object of the ODStorageUnitCursor class provides swift focusing on frequently accessed data in a storage unit.

A storage-unit cursor represents a focus context for a storage unit. The focus context can be the entire storage unit, a particular property, or a particular value of a particular property. When the focus context is the entire storage unit, the data of interest includes all properties and all their values. When the focus context is a particular property, the data of interest includes all values of that property. When the focus context is a particular value, the data of interest is the data stream corresponding to that value.

A storage-unit cursor uses a property name, a value type, and a value index to specify its focus context. Methods of the storage-unit cursor allow you to get and set each of these three pieces of information.

- To specify the entire storage unit as the focus context, set the property name to kODNULL; set the value type to kODTypeAll and value index to kODIndexAll.

- To specify a property as the focus context, set the property name to the name of the desired property; set the value type to kODTypeAll and value index to kODIndexAll.

- To specify a value as the focus context, set the property name to the name of the property containing the value. You can specify the value by its type or its index:

  - To use its type, set the value type to the type of the desired value and the value index to 0.

  - To use its index, set the value type to kODNULL and the value index to the index of the desired value.

A storage-unit cursor makes it simple for you to focus the storage unit on the corresponding focus context. Your part creates a storage-unit cursor object by calling its storage unit's CreateCursor or CreateCursorWithFocus methods. Your part calls its storage unit's FocusWithCursor method to focus the storage unit on the focus context represented by a storage-unit cursor.

For more information about storage units, focus context, and value indexes, see the class description for ODStorageUnit.

Methods

The methods defined by the ODStorageUnitCursor class include:

- GetProperty
- GetValueIndex
- GetValueType
- SetProperty
- SetValueIndex
- SetValueType

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

### GetProperty

This method gets the property name of this storage-unit cursor.

Signature

    void GetProperty (ODPropertyName *propertyName)

Parameters

propertyName (ODPropertyName *) - output

  The name of the property in the focus context.

Returns

None.

Remarks

When you no longer need the property name returned in the propertyName parameter, you should deallocate it.

Related Methods

- ODStorageUnitCursor::SetProperty

### GetValueIndex

This method gets the value index of this storage-unit cursor.

Signature

    void GetValueIndex (ODValueIndex *valueIndex)

Parameters

valueIndex (ODValueIndex *) - output

  The value index in the focus context.

Returns

None.

Related Methods

- ODStorageUnitCursor::SetValueIndex

### GetValueType

This method gets the value type of this storage-unit cursor.

Signature

    void GetValueType (ODValueType *valueType)

Parameters

valueType (ODValueType *) - output

  The value type of the focus context.

Returns

None.

Remarks

When you no longer need the value type returned in the valueType parameter, you should deallocate it.

Related Methods

- ODStorageUnitCursor::SetValueType

### SetProperty

This method sets the property name of this storage-unit cursor.

Signature

    void SetProperty (ODPropertyName propertyName)

Parameters

propertyName (ODPropertyName) - input

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

Returns

None.

Remarks When you no longer need the property name you pass as the propertyName parameter, you should deallocate it.

Related Methods

- ODStorageUnitCursor::GetProperty

### SetValueIndex

This method sets the value index of this storage-unit cursor.

Signature

    void SetValueIndex (ODValueIndex valueIndex)

Parameters

valueIndex (ODValueIndex) - input

  The value index of the value in the focus context or 0 to ignore the value index (and use the value type to specify the value in the focus context).

Returns

None.

Remarks

When you use this storage-unit cursor to focus your part's storage unit, the value index of this storage-unit cursor is ignored unless the value type is kODNULL.

Related Methods

- ODStorageUnitCursor::GetValueIndex

### SetValueType

This method sets the value type of this storage-unit cursor.

Signature

    void SetValueType (ODValueType valueType)

Parameters

valueType (ODValueType) - input

  The value type of the value in the focus context or kODNULL to ignore the value type (and use the value index to specify the value in the focus context).

Returns

None.

Remarks

When you no longer need the value type you pass as the valueType parameter, you should deallocate it.

Related Methods

- ODStorageUnitCursor::GetValueType

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