SE InitializeAggregateIterator

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

extern SE_Return_Code
SE_InitializeAggregateIterator
(
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 aggregate DRM objects returning handles to those that meet the following conditions:

The aggregate DRM objects contain the start_object as an immediate component (a component that is exactly one link away) via a two-way aggregation relationship.
If a search filter is defined for the iterator, the aggregate 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.

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_INACTIONABLE_FAILURE	set if itr_traversal is set to an illegal value, 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 component object for which the user wants a list of the aggregate objects that contain this component object.

² 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 aggregate objects that (1) contain the given component start_object via a 2-way aggregation and (2) pass the criteria defined in the search filter (if one was was provided).