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: |
Overridden Methods | There are no methods overridden by the ODStorageUnitRefIterator class. |
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
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. |
This method indicates whether the iteration is incomplete.
Signature
ODBoolean IsNotComplete () |
Parameters
None.
Returns
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. |
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
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. |