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

Returns

SE_STAT_CODE_SUCCESS	and *object_out_ptr is set to point to the component, and *link_class_object_out_ptr is set appropriately if provided, if valid parameters were passed in, only one object was found that satisfied the specified criteria, and no ITR references were involved.
SE_STAT_CODE_DIFFERENT_TRANSMITTAL	and the output parameters are set as for the SE_STAT_CODE_SUCCESS case, 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.
SE_STAT_CODE_UNRESOLVED_OBJECT	and the output parameters are set as for the SE_STAT_CODE_SUCCESS case, if valid parameters were passed in and only one object was found that satisfied the specified criteria, but the component object is unresolved.
SE_STAT_CODE_MULTIPLE_OBJECTS	and the output parameters are set as for the SE_STAT_CODE_SUCCESS case, if valid parameters were passed in but multiple objects were found that satisfied the specified criteria. In this case, an arbitrary object is chosen that satisfies the criteria.
SE_STAT_CODE_NULL_REQUIRED_PARAMETER	and the output parameter values are left unaltered, if object_out_ptr was NULL.
SE_STAT_CODE_INVALID_OR_NULL_OBJECT	and *object_out_ptr is set to NULL and *link_class_object_out_ptr (if provided) is set to NULL, if object_in is not a handle to a valid, active (i.e., unfreed) SEDRIS object, or if drm_class held an invalid value.
SE_STAT_CODE_UNRESOLVED_START_OBJECT	and the output parameters are set as for the SE_STAT_CODE_INVALID_OR_NULL_OBJECT case, if object_in is unresolved.
SE_STAT_CODE_NO_OBJECT	and the output parameters are set as for the SE_STAT_CODE_INVALID_OR_NULL_OBJECT case, if no component of the desired DRM class could be found (within the given max_search_distance, if a max_search_distance was given).
SE_STAT_CODE_OUT_OF_MEMORY	and the output parameters are set as for the SE_STAT_CODE_INVALID_OR_NULL_OBJECT case, if memory allocation failed.
SE_STAT_CODE_FAILURE	and the output parameters are treated as for the SE_STAT_CODE_INVALID_OR_NULL_OBJECT case, if drm_class or itr_traversal was not valid, the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

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_DRM_CLS_NULL 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 Colour> component of a <Polygon> without worrying
    about whether the <Inline Colour> 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).

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

link_class_object_out_ptr

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

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

Prev: SE_GetColourModel. Next: SE_GetContextTransformation. Up:Index.

Last updated: May 15, 2003 Copyright © 2003 SEDRIS™