SEDRIS Reference Manual
APPENDIX A - Transmittal Access Level 0 API
Functions
SE InitializeAggregateIterator
extern SE_Return_Code
SE_InitializeAggregateIterator
(
SE_Object start_object,1
SE_Search_Filter filter,2
SE_ITR_Behaviour itr_traversal,3
SE_Iterator *iterator_out_ptr4
);

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:

  1. 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.
  2. 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
  1. itr_traversal is set to an illegal value,
  2. 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
  3. the call fails for any other reason.

Parameters Notes

1 the component object for which the user wants a list of the aggregate objects that contain this component object.

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

3 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.

4 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).


Prev: SE_GetUserData. Next: SE_InitializeAssociateIterator. Up:Index.

Last updated: July 26, 2006 Copyright © 2006 SEDRIS