SE InitializeAssociateIterator

SEDRIS Reference Manual APPENDIX A - Transmittal Access Level 0 API Functions SE InitializeAssociateIterator

extern SE_Return_Code
SE_InitializeAssociateIterator
(
SE_Object		start_object,	¹
SE_Search_Filter		filter,	²
SE_ITR_Behaviour		itr_traversal,	³
SE_Iterator	*	iterator_out_ptr	⁴
);

Definition

This function returns a handle to an iterator created to traverse over the list of associate DRM objects returning handles to those that meet the following conditions:

The DRM objects are associated to start_object as an immediate associate (an associate that is exactly one link away) via either a two-way association, or via a one-way association from start_object to the associated DRM object. If a DRM object is associated to start_object via a one-way association from the associated DRM object to start_object, the associated DRM object will not be included in the list of DRM objects returned by this iterator.
If a search filter is defined for the iterator, the associate DRM objects satisfy the rules specified in filter. If no search filter is specified (a search filter handle with value zero is provided), no filtering is applied, and only condition (1) need be satisfied.

If start_object is associated solely by one-way incoming associations, or if start_object does not participate in any associations, an associate iterator is created, but it has a length of 0 and does not return any DRM objects.

The SE_GetNextObject() function is provided to get the next DRM object from an iterator.

The SE_GetIterationLengthRemaining() function may be invoked to find out the remaining length of an iterator (i.e., the number of DRM objects remaining inside the iterator).

The SE_FreeIterator() function should be invoked when finished with an iterator to free it. Iterators can be freed at any time (e.g., iterators can be freed before all of their DRM objects have been returned).

Returns

SE_RETCOD_SUCCESS	and the iterator is initialized.
SE_RETCOD_FAILURE	and the status code is set appropriately if the call failed.

Status Codes

SE_Status_Code(s) when SE_RETCOD_SUCCESS is returned:

SE_STATCODE_SUCCESS

set if valid parameters were passed in and all operations succeeded.

SE_Status_Code(s) when SE_RETCOD_FAILURE is returned:

SE_STATCODE_UNRESOLVED_INPUT_OBJECT	set if start_object is currently unresolved.
SE_STATCODE_C_ENUMERATION_VALUE_INVALID	set if itr_traversal is not a valid value.
SE_STATCODE_INACTIONABLE_FAILURE	set if a search filter is provided, but is not a handle to a valid, active (i.e., unfreed) search filter defined by the specified API implementation, or the call fails for any other reason.

Parameters Notes

¹ the object whose list of associates will be returned

² a search filter that will be used to filter the output of this iterator.

³ the user must choose how the iterator will behave when it encounters an Inter-Transmittal Reference (ITR). The iterator could automatically resolve such references and continue the search within the new transmittal; report all ITR references without resolving them; or just ignore them completely and continue to search within the current transmittal.

⁴ a pointer to the freshly created iterator that will iterate over the associated objects that (1) are associated by an association from the start_object, and (2) pass the criteria defined in the search filter (if a search filter was provided).