Programming Reference: ODStorageUnitRefIterator

# Programming Reference

## ODStorageUnitRefIterator

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

Class Hierarchy

    SOMObject
       ODObject
          ODStorageUnitRefIterator

Description

An object of the ODStorageUnitRefIterator class provides access to all persistent references in a focused value.

If a value in a storage unit contains persistent references, a storage-unit reference iterator can provide access to each persistent reference. For example, a caller might need to access all referenced storage units in a clone operation. A caller can use a storage-unit reference iterator to access the persistent reference in any storage unit value. This practice might be helpful for utilities that fix up cross-references or index a document. Persistent references cannot be created or removed during iteration, and the storage unit must remain focused to the value on which the storage-unit reference iterator is iterating.

Callers create a storage-unit reference iterator object by calling its storage unit's CreateStorageUnitRefIterator method, which returns a reference to a storage-unit reference iterator object.

For more information on cloning, see the chapters on storage and data transfer in the OpenDoc Programming Guide. For more information on accessing objects through iterators, see the chapter on OpenDoc runtime features in the OpenDoc Programming Guide.

Methods

The methods defined by the ODStorageUnitRefIterator class include:

- First
- IsNotComplete
- Next

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

### First

This method begins the iteration and returns a copy of the first persistent reference in the focused value of the storage unit, if it exists.

Signature

    void First (ODStorageUnitRef ref)

Parameters

ref (ODStorageUnitRef) - output

  A copy of the first persistent reference in the focused value of the storage unit. If the focused value contains no persistent references, the return value is undefined.

Returns

None.

Remarks

Your part must call this method before calling the IsNotComplete method for the first time. This method may be called multiple times. Each call resets the iteration.

It is your responsibility to deallocate the returned persistent reference when it is no longer needed.

Exception Handling

kODErrIteratorOutOfSync | The focused values was modified during the iteration.

### IsNotComplete

This method indicates whether the iteration is incomplete.

Signature

    ODBoolean IsNotComplete ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the iteration is incomplete

  kODTrue | The iteration is incomplete.
  kODFalse | The iteration is complete.

Remarks

Your part calls this method to test whether more persistent references remain in the focused value. This method returns kODTrue if the preceding call to the First or Next method found a persistent reference. This method returns kODFalse when you have examined all the persistent references (that is, when the previous call to First or Next returned kODNULL).

Exception Handling

kODErrIteratorNotInitialized | This method was called before calling the First or Next method.
kODErrIteratorOutOfSync | The focused value was modified during the iteration.

### Next

This method returns a copy of the next persistent reference in the focused value of the storage unit, if it exists.

Signature

    void Next (ODStorageUnitRef ref)

Parameters

ref (ODStorageUnitRef) - output

  A copy of the next persistent reference in the focused value of the storage unit. If the focused value contains no persistent references or if the iteration is complete, the return value is undefined.

Returns

None.

Remarks

If your part calls this method before calling this storage-unit reference iterator's First method to begin the iteration, then this method works the same as calling the First method.

It is your responsibility to deallocate the returned persistent reference when it is no longer needed.

Exception Handling

kODErrIteratorOutOfSync | The focused value was modified during the iteration.

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