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