Function Name: Initialize Associate Iterator

Definition

Creates an iterator to (traverse over the list of)/(return pointers to) associate objects that meet the following conditions:

1. they are associated to the start_object as an immediate associate (an associate that is exactly one link away) via either a 2-way association, or via a 1-way association from the start_object to the associated object. If an object is associated to the start_object via a 1-way association from the associated object to the start_object, then the associated object will not be included in the list of objects returned by this iterator (because if it is a 1-way association into the start_object, then the start_object, by definition, does not know which objects are at the other end of the 1-way associations).

2. they satisfy the rules specified in the search filter, if a search filter is defined for the iterator. If NULL is passed in for the search filter, then no filtering is applied, and only condition (1) must be satisfied.

If a start_object is associated solely by 1-way incoming associations, or if the start_object does not participate in any associations, then an Associate Iterator for that start_object will not return any objects. An Associate Iterator would be created, but it would have a length of 0 and would not return any objects.

To get the next object from an iterator, call SE_GetNextObject().

To find out the remaining length of an iterator (the number of objects remaining inside the iterator), call SE_GetIterationLengthRemaining().

When finished with an iterator, free it with a call to the SE_FreeIterator() function. Iterators can be freed at any time (they can be freed before all of their objects have been returned, that is, before their remaining length == 0, if the user so desires).

Returns

SE_NULL_REQUIRED_PARAMETER - and *iterator_out_ptr is left unaltered, if iterator_out_ptr was NULL.

SE_INVALID_OR_NULL_OBJECT - and *iterator_out_ptr is set to NULL, if start_object is not a handle to a valid, active (i.e., unfreed) SEDRIS object.

SE_UNRESOLVED_START_OBJECT - and *iterator_out_ptr is set to NULL, if start_object is currently unresolved.

SE_OUT_OF_MEMORY - and *iterator_out_ptr is set to NULL, if memory allocation failed.

SE_FAILURE - and *iterator_out_ptr is set to NULL, if

1. inter_transmittal_referencing_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 API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

Prototype

Parameters Notes

start_object

 the object whose list of associates will be returned

filter

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

inter_transmittal_referencing_traversal

 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.

iterator_out_ptr

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