SE GetNthComponent

SEDRIS Reference Manual APPENDIX A - Transmittal Access Level 0 API Functions SE GetNthComponent

extern SE_Return_Code
SE_GetNthComponent
(
SE_Object		aggregate_object,	(notes)
SE_DRM_Class		desired_component_class,	(notes)
SE_Integer_Positive		n,	(notes)
SE_Object	*	component_object_out_ptr,	(notes)
SE_Object	*	link_class_object_out_ptr	(notes)
);

Definition

Given an object that has multiple, ordered components of a certain DRM class, returns an SE_Object for the Nth component of that class. ITR components will be automatically resolved and if an ITR component is encountered that cannot be resolved, the call will return SE_STAT_CODE_UNRESOLVED_OUTPUT_OBJECT for the n value passed in and any higher n values.

Returns

SE_RET_CODE_SUCCESS and the requested component is returned

SE_RET_CODE_FAILURE and the status code is set appropriately if the call failed.

Status Codes

SE_Status_Code(s) when SE_RET_CODE_SUCCESS is returned:

SE_STAT_CODE_SUCCESS set if valid parameters were passed in and all operations succeeded.

SE_Status_Code(s) when SE_RET_CODE_FAILURE is returned:

SE_STAT_CODE_UNRESOLVED_OUTPUT_OBJECT set if valid parameters were passed in and valid objects are returned, but the object returned using *component_object_out_ptr is unresolved.

SE_STAT_CODE_UNRESOLVED_INPUT_OBJECT set if aggregate_object is an unresolved SEDRIS object.

SE_STAT_CODE_NO_OBJECT set if the aggregate_object did not contain 'n' component objects of the desired class.

SE_STAT_CODE_INACTIONABLE_FAILURE set if

'n' was 0 (since this is a 1-based index),

desired_component_class was invalid,

the given class of component is not ordered for the given aggregate object, or

the call fails for any other reason.

Parameters Notes

aggregate_object

 the object containing the desired component

desired_component_class

 the DRM class of component the user wants.
    Abstract types are allowed.  The SE_DRM_CLS_NULL is not.

n

 the 'index' of that component, given an ordered list of all components
      of the desired class 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.

link_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 link class object was
    attached to the link used to reach the desired component object, then
    *link_class_object_out_ptr will be NULL.

SE_RET_CODE_SUCCESS	and the requested component is returned
SE_RET_CODE_FAILURE	and the status code is set appropriately if the call failed.

SE_STAT_CODE_UNRESOLVED_OUTPUT_OBJECT	set if valid parameters were passed in and valid objects are returned, but the object returned using *component_object_out_ptr is unresolved.
SE_STAT_CODE_UNRESOLVED_INPUT_OBJECT	set if aggregate_object is an unresolved SEDRIS object.
SE_STAT_CODE_NO_OBJECT	set if the aggregate_object did not contain 'n' component objects of the desired class.
SE_STAT_CODE_INACTIONABLE_FAILURE	set if 'n' was 0 (since this is a 1-based index), desired_component_class was invalid, the given class of component is not ordered for the given aggregate object, or the call fails for any other reason.