Function Name: Get Remaining Packed Hierarchies

Definition

Iterates over the remaining objects available through an iterator and returns packed hierarchies for all of them at one time.

Returns

SE_SUCCESS - if valid parameters were passed in. In this case, *remaining_hierarchies_out_ptr is filled in with the hierarchy list data.

SE_DIFFERENT_TRANSMITTAL - and *remaining_hierarchies_out_ptr is filled in with the hierarchy list data, if valid parameters were passed in, objects were left that have not yet been returned, and one or more objects encountered were contained in different transmittals than the iterator's start_object.

SE_UNRESOLVED_OBJECT - and *remaining_hierarchies_out_ptr is filled in with the hierarchy list data, if valid parameters were passed in, objects were left that have not yet been returned, and one or more objects encountered were not resolved. In this case, the object_is_resolved field is set to SE_FALSE in each of the SE_PACKED_HIERARCHY_OBJECT data structures for those objects that are unresolved.

SE_NULL_REQUIRED_PARAMETER - and *remaining_hierarchies_out_ptr is left unaltered, if remaining_hierarchies_out_ptr was NULL.

SE_NO_OBJECT - and the fields of *remaining_hierarchies_out_ptr set to zero or NULL, if the iterator is out of objects to return.

SE_FAILURE - and the output parameter is set as for SE_NO_OBJECT, if

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

Prototype


extern SE_STATUS_CODE_ENUM
SE_GetRemainingPackedHierarchies
(
SE_ITERATOR iterator, (notes)
SE_UINT32 hierarchy_depth, (notes)
SE_REMAINING_PACKED_HIERARCHIES_LIST *remaining_hierarchies_out_ptr (notes)
);

Parameters Notes

iterator

 the iterator whose remaining objects will be the root of each
    hierarchy returned.

hierarchy_depth

 the depth to which the sub-hierarchy of each remaining
    object is extracted below that object.  A value of 1 indicates that only
    the components of each remaining object are to be returned.  A value of
    0 indicates that the entire sub-hierarchy of each remaining 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
          to represent, and/or take a long time to return.

remaining_hierarchies_out_ptr

 a pointer to a
    SE_REMAINING_PACKED_HIERARCHIES_LIST structure that the function will
    fill in with the hierarchy list data.
Prev: Get Remaining Objects List. Next: Get Root Object. Up:Index.