Function Name: Get Component

Definition

Retrieves the given kind of component (drm_class) from the given object (object_in).

This is a 'short form, 1-shot' version of a Component Iterator. It saves the user the trouble of creating an iterator, making a call to SE_GetNextObject(), and then freeing the iterator, in the case when the user knows that the user wants to retrieve one and only one object. Iterators are necessary to retrieve multiple objects, but they can be a nuisance when retrieving unique objects (such as retrieving the Model Library of a Transmittal Root, or retrieving the Location of a Vertex).

Given an object (the object_in), and a class of object to search for (the drm_class), and the maximum distance to search ( max_search_distance) this function will find the first component of the given class that is:

• a component of the start object, object_in (distance = 1) OR
• a member of the aggregate tree rooted at object_in (the tree of object_in's components, and their components, and their components, ...) (distance = between 1 and the given maximum search distance - this is a breadth first search).

SE_GetComponent() stops at Inter-Transmittal References -- see SE_STOP_AT_ITR_REFERENCES in SE_ITR_TRAVERSAL_ENUM for details).

Returns

SE_DIFFERENT_TRANSMITTAL - if valid parameters were passed in, the user requested that the API automatically resolve inter-transmittal references (ITR), an ITR reference was encountered in searching for the component, and the iterator successfully resolved it and retrieved the component from the new, different transmittal. In this case, *object_out_ptr is set to point to the component, and *association_class_object_out_ptr is set appropriately, unless the user passed in a NULL for that value.

SE_MULTIPLE_OBJECTS - if valid parameters were passed in and multiple objects were found that satisfied the specified criteria. In this case, an arbitrary object is chosen that specifies the criteria, and the output parameters are set as for the SE_SUCCESS case.

SE_NULL_REQUIRED_PARAMETER - if object_out_ptr was NULL. In this case, the output parameters are left unaltered.

SE_INVALID_OR_NULL_OBJECT - if object_in is not a handle to a valid, active (i.e., unfreed) SEDRIS object, or if drm_class held an invalid value. In this case

• *object_out_ptr is set to NULL
• *association_class_object_out_ptr is set to NULL (if association_class_object_out_ptr is not NULL)

SE_UNRESOLVED_OBJECT - if valid parameters were passed in, and an inter-transmittal reference (ITR) was encountered in searching for the component. In this case, *next_object_out_ptr is set to point to the unresolved object, and *association_class_object_out_ptr is set appropriately, unless the user passed in a NULL for that value.

SE_UNRESOLVED_START_OBJECT - if object_in is an unresolved SEDRIS object. In this case, the output parameters are set as for the SE_INVALID_OR_NULL_OBJECT case.

SE_NO_OBJECT - if no object of the desired type could be found (within the given max_search_distance, if a max_search_distance was given). In this case, the output parameters are set as for the SE_INVALID_OR_NULL_OBJECT case.

SE_OUT_OF_MEMORY - if memory allocation failed. In this case, the output parameters are set as for the SE_INVALID_OR_NULL_OBJECT case.

SE_FAILURE - and the output parameters are set as for the SE_INVALID_OR_NULL_OBJECT case, if

1. drm_class or inter_transmittal_referencing_traversal was not valid,
2. the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

Prototype

Parameters Notes

object_in

 the object from which the user wants one component.

drm_class

 the type of component the user wants.  This is
    a required parameter in this call. SE_NULL_TOKEN is not allowed.
    Asking for an object of an abstract type is allowed. In that case,
    the API will look for a concrete component that is a 'kind-of'
    (a subclass) of the given abstract type.

directly_attach_table_components

 see SE_InitializeComponentIterator's
    comments on directly_attach_table_components.

process_inheritance

 if true, then inherited components will be
    considered as well as 'immediate' components.  If SE_FALSE, then only
    'immediate' components will be considered.  For example, by setting
    this process_inheritance parameter to SE_TRUE, this allows a user to
    ask for the <Inline Color> component of a <Polygon> without worrying
    about whether the <Inline Color> component was an 'immediate' or
    'inherited' component of the <Polygon>.  An 'immediate' component will
    always take precedence over an 'inherited' component.

max_search_distance

 the maximum distance to search using
    a breadth-first search to traverse the components.  A value of 0
    indicates that the search has an unlimited depth (and should continue
    to search until it finds an object of the appropriate type, or until
    it runs out of objects).

inter_transmittal_referencing_traversal

 the user must choose how
    the function will behave when it encounters an Inter-Transmittal
    Reference (ITR). The function 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.

object_out_ptr

 pointer to a variable in the user's memory space to
    which a handle the component will be copied, if there is a component.

association_class_object_out_ptr

 if not NULL, then an
    SE_OBJECT of the association class object (a.k.a. link class object)
    traversed to reach the component will be copied to
    *association_class_object_out_ptr. If no association class object was
    attached to the link used to reach the component object, then
    *association_class_object_out_ptr will be set to NULL.

    If the user passes in NULL for association_class_object_out_ptr, then
    association class objects will be ignored (and
    *association_class_object_out_ptr will not be affected).