SEDRIS Reference Manual
APPENDIX A - Transmittal Access Level 0 API
Functions
SE GetPackedHierarchy
extern SE_Return_Code
SE_GetPackedHierarchy
(
SE_Object root_object,1
SE_Boolean directly_attach_table_components,2
SE_Boolean process_inheritance,3
SE_Integer_Unsigned hierarchy_depth,4
SE_ITR_Behaviour itr_traversal,5
SE_Store store,6
SE_Packed_Hierarchy *hierarchy_out_ptr7
);

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_RETCOD_SUCCESS and the requested packed hierarchy is returned.
SE_RETCOD_FAILURE and the status code is set appropriately if the call failed.

Status Codes

SE_Status_Code(s) when SE_RETCOD_SUCCESS is returned:

SE_STATCODE_SUCCESS set if valid parameters were passed in and call was successful.
SE_STATCODE_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_RETCOD_FAILURE is returned:

SE_STATCODE_UNRESOLVED_OUTPUT_OBJECT set if valid parameters were passed in but one or more objects encountered were not resolved. In this case, the status_code field is set to SE_STATCODE_UNRESOLVED_INPUT_OBJECT in the SE_Packed_Hierarchy_Object data structures for those objects that are unresolved.
SE_STATCODE_UNRESOLVED_INPUT_OBJECT set if root_object is unresolved.
SE_STATCODE_C_ENUMERATION_VALUE_INVALID set if itr_traversal is not a valid value.
SE_STATCODE_C_STORE_INVALID set if store is not a handle to a valid SE_Store.
SE_STATCODE_INACTIONABLE_FAILURE set if the call fails for any other reason.

Parameters Notes

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

2 see SE_InitializeComponentIterator's comments on directly_attach_table_components.

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

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

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

6 the store that will manage the fields memory

7 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 26, 2006 Copyright © 2006 SEDRIS