SE GetPackedHierarchy

SEDRIS Reference Manual APPENDIX A - LEVEL 0 READ and WRITE API Functions SE GetPackedHierarchy

extern SE_Status_Code
SE_GetPackedHierarchy
(
SE_Object		root_object,	(notes)
SE_Boolean		directly_attach_table_components,	(notes)
SE_Boolean		process_inheritance,	(notes)
SE_Integer_Unsigned		hierarchy_depth,	(notes)
SE_ITR_Behaviour		itr_traversal,	(notes)
SE_Packed_Hierarchy	*	hierarchy_out_ptr	(notes)
);

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_STAT_CODE_SUCCESS and the packed hierarchy data is copied into *hierarchy_out_ptr, if valid parameters were passed in.

SE_STAT_CODE_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_STAT_CODE_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_STAT_CODE_NULL_REQUIRED_PARAMETER and *hierarchy_out_ptr is left unaltered, if hierarchy_out_ptr was NULL.

SE_STAT_CODE_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_STAT_CODE_UNRESOLVED_START_OBJECT and *hierarchy_out_ptr is left unaltered, if root_object is unresolved.

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

SE_STAT_CODE_FAILURE and *hierarchy_out_ptr is left unaltered, if

itr_traversal is not a valid value, or

dynamic binding is specified at compile time, but the API implementation specified does not provide this function in its shared library.

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.

SE_STAT_CODE_SUCCESS	and the packed hierarchy data is copied into *hierarchy_out_ptr, if valid parameters were passed in.
SE_STAT_CODE_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_STAT_CODE_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_STAT_CODE_NULL_REQUIRED_PARAMETER	and *hierarchy_out_ptr is left unaltered, if hierarchy_out_ptr was NULL.
SE_STAT_CODE_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_STAT_CODE_UNRESOLVED_START_OBJECT	and *hierarchy_out_ptr is left unaltered, if root_object is unresolved.
SE_STAT_CODE_OUT_OF_MEMORY	and *hierarchy_out_ptr is left unaltered, if memory allocation failed.
SE_STAT_CODE_FAILURE	and *hierarchy_out_ptr is left unaltered, if itr_traversal is not a valid value, or dynamic binding is specified at compile time, but the API implementation specified does not provide this function in its shared library.