|
|
Retrieves the next element and link object from the iterator. As a convenience, this method returns false when the iterator is empty. Hence, you can use code like seIterator iter;
seObject comp_obj, link_obj;
some_obj.getComponentIterator(iter);
while (iter.getNext(comp_obj, link_obj))
{
... use comp_obj and link_obj as needed
}
seIterator iter;
seObject comp_obj, link_obj;
some_obj.getComponentIterator(iter);
while (!iter.isCompleted())
{
try {
iter.getNext(comp_obj, link_obj);
... use comp_obj and link_obj as needed
} catch ( seException& e ) {
... process exception
}
}
The ITR behaviour of an iterator is dependent on the ITR behaviour set at the workspace level (see seWorkspace::setITRBehaviour()) when the iterator is created. Iterators are typically created by calling one of the "get" iterator methods of an seObject (for example seObject::getComponentIterator()). After the iterator is created, changing the workspace ITR behaviour has no effect on the iterator.
The ITR behaviour value is interpreted as follows:
-
If ITR behaviour is SE_ITR_BHVR_RESOLVE, then all objects returned by the API will be resolved objects. If an object cannot be resolved (for example the referenced transmittal is missing) then an exception will occur (the exception type will be dependent on the failed step, for example it could be UNRESOLVED_TRANSMITTAL, UNPUBLISHED_OBJECT, or some other exception type).
-
If ITR behaviour is SE_ITR_BHVR_REPORT, then when the iterator encounters an ITR reference it will return an unresolved object, no matter what its DRM type may be. You can call seObject::resolve() to attempt to resolve the object if you need to. Note that the current filter DRM class for the iterator is ignored for ITR references when using SE_ITR_BHVR_REPORT. Hence, you should not use seDRMBase-derived classes as parameters to getNext().
-
If ITR behaviour is SE_ITR_BHVR_IGNORE, then ITR references are skipped by the iterator and are never returned.
- Note:
- If there is no link object associated with the next object, the link object parameter is set to an invalid object handle (i.e. you can use seObject::isValid() to see if a link object was available).
This method respects the DRM ordering of ordered classes.
- Warning:
- If you use one of the seDRMBase-derived classes as parameters to this method, you must ensure that the derived type will be able to hold a reference to whatever object will be returned, or an exception will occur. If you don't know what type will be returned, you can pass in a base class (such as seObject) and then get the type of the object by using seObject::getDRMClass().
- See also:
- seWorkspace::setITRBehaviour(), seObject::isResolved()
- Exceptions:
-
| seException | if an error occurs. |
- Parameters:
-
| obj | in/out: a handle to store the next object |
| link_obj | in/out: a handle to store the next link object (if available) |
|