Function Name: Get Packed Hierarchy

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.

Returns

SE_DIFFERENT_TRANSMITTAL - and the packed hierarchy data is copied into *hierarchy_out_ptr, if valid parameters were passed in but one or more objects encountered were contained in a different transmittal to root_object.

SE_UNRESOLVED_OBJECT - and the packed hierarchy data is copied into *hierarchy_out_ptr, 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_NULL_REQUIRED_PARAMETER - and *hierarchy_out_ptr is left unaltered, if hierarchy_out_ptr was NULL.

SE_INVALID_OR_NULL_OBJECT - and *hierarchy_out_ptr is left unaltered, if root_object is not a handle to a valid, active (i.e., unfreed) SEDRIS object.

SE_UNRESOLVED_START_OBJECT - and *hierarchy_out_ptr is left unaltered, if root_object is unresolved.

SE_OUT_OF_MEMORY - and *hierarchy_out_ptr is left unaltered, if memory allocation failed.

SE_FAILURE - and *hierarchy_out_ptr is left unaltered, if

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

Prototype

Parameters Notes

root_object

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

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.

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.

hierarchy_out_ptr

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