Definition

Retrieves a component object of a specified DRM class or of any DRM class (if not specified with drm_class) for the given object (object_in). For example, if SE_GetComponent() is called with a <Vertex> object then a handle to the <Location> component object will be returned at *object_out_ptr.

Returns

SE_RET_CODE_SUCCESS	and the requested object is returned, if valid parameters were passed in and all operations succeeded.
SE_RET_CODE_FAILURE	and the status code is set appropriately if the call failed.

Status Codes

SE_Status_Code(s) when SE_RET_CODE_SUCCESS is returned:

SE_STAT_CODE_SUCCESS	set 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	set 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_Status_Code(s) when SE_RET_CODE_FAILURE is returned:

SE_STAT_CODE_UNRESOLVED_OUTPUT_OBJECT	set 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_UNRESOLVED_INPUT_OBJECT	set if object_in is unresolved.
SE_STAT_CODE_NO_OBJECT	set if no component of the desired DRM class could be found.
SE_STAT_CODE_INACTIONABLE_FAILURE	set if drm_class or itr_traversal was not valid, the call fails for any other reason.

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.

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: July 16, 2004 Copyright © 2004 SEDRIS™