SE InitializeComponentIterator

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

extern SE_Return_Code
SE_InitializeComponentIterator
(
	SE_Object		start_object,	¹
	SE_Search_Boundary		boundary,	²
	SE_Search_Filter		filter,	³
	SE_Boolean		directly_attach_table_components,	⁴
	SE_Boolean		process_inheritance,	⁵
	SE_Boolean		transform_locations,	⁶
	SE_Boolean		follow_model_instances,	⁷
	SE_Boolean		evaluate_static_control_links,	⁸
const	SE_Hierarchy_Select_Parameters	*	select_parameters_ptr,	⁹
const	SE_Hierarchy_Order_Parameters	*	traversal_order_parameters_ptr,	¹⁰
	SE_Traversal_Order		general_traversal_pattern,	¹¹
	SE_ITR_Behaviour		itr_traversal,	¹²
	SE_Iterator	*	iterator_out_ptr	¹³
);

Definition

Creates an iterator to (traverses over the list of)/(returns pointers to) component objects that meet the user specified conditions. This iterator starts at the 'top' of an 'aggregation tree'. Consider the start_object as the root of a tree. All of the components below the start_object will be searched, and the components of those components will be searched, and their components will be searched, etc., as far down (as many levels down) as the search filter specifies. If the search filter does not limit the 'depth' of the search with a maximum search depth rule, then the iterator will search until it has tested every object in the 'aggregation-tree' rooted by the start_object.

Objects returned by a component iterator will meet these conditions:

they are components, either directly or transitively, of the start_object. That is, they are contained within the aggregation tree that is rooted at the start_object.
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 conditions (1) and (3) must be satisfied.
A search filter can include a maximum search depth restriction. If such a restriction is applied, then the sub-tree rooted at the start_object will only be searched until that maximum search depth has been reached. Components beyond that depth will not be searched.
they fall within the bounds of the spatial search boundary, given the inclusion rules defined for that search boundary. If NULL is passed in for the search boundary, then no location based filtering is applied, and only conditions (1) and (2) must be satisfied.

If a start_object does not contain any component objects (or it contains component objects, but none of the components within the specified search depth meet the search filter and/or search boundary conditions), then a Component Iterator for that start_object, search filter, and search boundary will not return any objects. A Component 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_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 invalid,
general_traversal_pattern is invalid,
selection parameters are provided but are not valid,
traversal order parameters are provided, but are not valid
a search filter is provided, but is not a handle to a valid, active (i.e., unfreed) search filter,
a search boundary is provided, but is not a legal, valid search boundary for the scope of start_object
the start_object, search filter, and / or search boundary came from different API implementations, or
the call fails for any other reason.

Parameters Notes

¹ the object whose components will be traversed.

² a spatial search boundary that will be used to filter this iterator's output.

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

⁴ if SE_FALSE, then the actual DRM objects will be examined by the consumer through the component iterators. However, if SE_TRUE, then the component iterators will automatically make the following adjustments to the object types returned through the API in the following special cases: 1) If an <Property Set Index> would otherwise be returned by the component iterator, the <Property Set Index> object will be automatically replaced by the corresponding objects referenced by the primary (1st) <Property Set> of the referenced <Property Set Table Group>. 2) If a <Colour Index> would otherwise be returned by the component iterator, the <Colour Index> object will be replaced by an <Inline Colour> containing the same <Primitive Colour> as the <Primitive Colour> that would have been referenced by the <Colour Index> (through the default <Colour Table> of the associated <Colour Table Group>).

⁵ if true, then 'inherited components' will be inherited, and they will show up as components of the appropriate objects. These 'inherited' components will be just as 'valid' as 'direct' components, and they will satisfy the SE_COMPONENT_DRM_CLASS_MATCH, SE_COMPONENT_FIELD_MATCH, and SE_COMPONENT_RANGE_MATCH macros just as 'direct' components do.

⁶ if true, then all <Location> objects will be transformed according to the transformations (<LSR Transformation>s and/or <World Transformation>s) encountered by the iterator.

⁷ if true, then the iterator will search through the <Geometry Model Instance> to <Geometry Model> association as if it were an aggregation (it will 'instance' the model). The same logic applies to the <Feature Model Instance> to <Feature Model> association.

⁸ if true, then all expressions composed entirely of literals and functions that use only literals will be evaluated, and their results will 'over-write' the appropriate fields of their targeted 'controlled' objects.

⁹ a pointer to the parameters that will be used to determine that components to traverse when encountering a <Aggregate Feature> or <Aggregate Geometry> object.

¹⁰ a pointer to the parameters that will be used to determine what order to traverse the components when encountering a <Aggregate Feature> or <Aggregate Geometry> object.

¹¹ the user must choose whether the Iterator should traverse the search space in a depth-first, breadth-first, or any-order-the-API-chooses manner. The depth-first and breadth-first approaches allow for full transformation and inherited component information to be maintained at all times. The API-chooses-an-order approach can be faster, possibly much faster, but there is no guarantee that any path was taken from the start_object to the returned objects, so it is possible for no context (an empty context) to be returned with the returned objects.

¹² 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 component iterator that will iterate over the objects that meet the conditions described above.