SE GetNthAssociate

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

extern SE_Return_Code
SE_GetNthAssociate
(
SE_Object		from_object,	¹
SE_DRM_Class		desired_associate_class,	²
SE_Integer_Positive		n,	³
SE_Object	*	associate_object,	⁴
SE_Object	*	link_object	⁵
);

Definition

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

Returns

SE_RETCOD_SUCCESS	and the requested object 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 all operations succeeded.

SE_Status_Code(s) when SE_RETCOD_FAILURE is returned:

SE_STATCODE_UNRESOLVED_OUTPUT_OBJECT	set if valid parameters were passed in and valid objects are returned, but the object returned using *associate_object is unresolved.
SE_STATCODE_UNRESOLVED_INPUT_OBJECT	set if from_object is an unresolved object.
SE_STATCODE_NO_OBJECT	set if the from_object did not contain 'n' associate objects of the desired class.
SE_STATCODE_C_ENUMERATION_VALUE_INVALID	set if desired_associate_class was not valid.
SE_STATCODE_INACTIONABLE_FAILURE	set if 'n' was 0 (since this is a 1-based index), the given class of associate is not ordered for the given from_object, or the call fails for any other reason.

Parameters Notes

¹ the object containing the desired component

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

³ the 'index' of that component, given an ordered list of all components of the desired class for the given from_object. This is a 1-based index.

⁴ a pointer to a variable in the user's memory space, to which the desired associate of the from_object will be copied.

⁵ 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 associate object will be copied. If no link class object was attached to the link used to reach the desired associate object, then *link_object will be NULL.