Definition

Retrieves a sub-hierarchy rooted at a given object into a set of data structures that can be directly traversed by the calling application using "C" pointer dereferencing.

NOTE: Model instances are not followed.

Returns

SE_RET_CODE_SUCCESS	and the requested packed hierarchy is returned.
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 and call was successful.
SE_STAT_CODE_DIFFERENT_TRANSMITTAL	set if valid parameters were passed in but one or more objects encountered were contained in a different transmittal to root_object.

SE_Status_Code(s) when SE_RET_CODE_FAILURE is returned:

SE_STAT_CODE_UNRESOLVED_OUTPUT_OBJECT	set if valid parameters were passed in but one or more objects encountered were not resolved. In this case, the object_is_resolved field is set to SE_FALSE in the SE_Packed_Hierarchy_Object data structures for those objects that are unresolved.
SE_STAT_CODE_UNRESOLVED_INPUT_OBJECT	set if root_object is unresolved.
SE_STAT_CODE_INACTIONABLE_FAILURE	set if itr_traversal is not a valid value, or the call fails for any other reason.

Parameters Notes

root_object

 the object to use as the root of the sub-hierarchy.

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, a user may ask for an <Inline Colour> component of a
    <Polygon> without worrying about whether the <Inline Colour>
    instance was an 'immediate' or 'inherited' component of the
    <Polygon>.

    An 'immediate' component will always take precedence over an
    'inherited' component.

hierarchy_depth

 the depth to which the sub-hierarchy is
    extracted below the root object.  A value of 1 indicates that only
    the components of the root object are to be returned.  A value of 0
    indicates that the entire sub-hierarchy of the root object is to be
    returned.

    NOTE: Care must be taken when passing "0" for the hierarchy_depth
          parameter.  The sub-hierarchies of non-primitive root objects
          can be potentially large, require large amounts of memory
          to represent, and/or take a long time to return.

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.

hierarchy_out_ptr

 a pointer to a SE_Packed_Hierarchy structure which
    the function will fill in with the hierarchy data.

Prev: SE_GetObjectReferenceCount. Next: SE_GetPublishedLabels. Up:Index.

Last updated: July 16, 2004 Copyright © 2004 SEDRIS™