Function Name: Get Nth Component Of Given Type

Definition

Given an object that has multiple, ordered components of a certain type (i.e., DRM class), returns an SE_OBJECT for the Nth component of that type.

Returns

SE_SUCCESS - if valid parameters were passed in. In this case, *component_object_out_ptr is set to point to the desired component object, and *association_class_object_out_ptr is set appropriately, unless the user passed in a NULL for that value.

SE_UNRESOLVED_OBJECT - if valid parameters were passed in and valid objects are returned, but the object returned using *component_object_out_ptr is unresolved. In this case, the output parameters are set as for the SE_SUCCESS case.

SE_NULL_REQUIRED_PARAMETER - if component_object_out_ptr was NULL. In this case, the output parameter values are left unaltered.

SE_INVALID_OR_NULL_OBJECT - if aggregate_object was not a handle to a valid, active (i.e., unfreed) SEDRIS object. In this case, the *component_object_out_ptr value (and if not NULL, the *association_class_object_out_ptr value) is set to NULL.

SE_UNRESOLVED_START_OBJECT - if aggregate_object is an unresolved SEDRIS object. In this case the parameters are set as for the SE_INVALID_OR_NULL_OBJECT case.

SE_NO_OBJECT - if the aggregate_object did not contain 'n' component objects of the desired type. In this case, the output parameters are set as for the SE_INVALID_OR_NULL_OBJECT case.

SE_OUT_OF_MEMORY - if the API could not allocate memory. In this case, the output parameters are set as for the SE_INVALID_OR_NULL_OBJECT case.

SE_FAILURE - and the output parameters are set as for the SE_INVALID_OR_NULL_OBJECT case, if

  1. 'n' was 0 (since this is a 1-based index),
  2. an invalid value was supplied for desired_component_type,
  3. the given type of component is not ordered for the given aggregate object, or
  4. 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_GetNthComponentOfGivenType
(
SE_OBJECT aggregate_object, (notes)
SE_TOKEN_ENUM desired_component_type, (notes)
SE_PINT32 n, (notes)
SE_OBJECT *component_object_out_ptr, (notes)
SE_OBJECT *association_class_object_out_ptr (notes)
);

Parameters Notes

aggregate_object

 the object containing the desired component

desired_component_type

 the type of component the user wants.
    Abstract types are allowed.  The SE_NULL_TOKEN is not.

n

 the 'index' of that component, given an ordered list of all components
      of the desired type for the given aggregate object. This is a 1-based
      index.

component_object_out_ptr

 a pointer to a variable in the user's memory
    space, to which the desired component of the aggregate_object will be
    copied.

association_class_object_out_ptr

 a pointer to
    a variable in the user's memory space, to which the link object
    (sometimes called the association class object) traversed to reach the
    desired component object will be copied. If no association class object
    was attached to the link used to reach the desired component object,
    then *association_class_object_out_ptr will be NULL.
Prev: Get Next Object. Next: Get Number Of Paths To Transmittal Root. Up:Index.