SE GetNthAssociateOfDRMClass

SEDRIS Reference Manual APPENDIX A - LEVEL 0 READ and WRITE API Functions SE GetNthAssociateOfDRMClass

extern SE_Status_Code
SE_GetNthAssociateOfDRMClass
(
SE_Object		from_object,	(notes)
SE_DRM_Class		desired_component_class,	(notes)
SE_Integer_Positive		n,	(notes)
SE_Object	*	associate_object_out_ptr,	(notes)
SE_Object	*	link_class_object_out_ptr	(notes)
);

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_STAT_CODE_UNRESOLVED_OBJECT for the n value passed in and any higher n values.

Returns

SE_STAT_CODE_SUCCESS and *associate_object_out_ptr is set to point to the desired associate object, and *link_class_object_out_ptr is set appropriately, if valid parameters were passed in and all operations succeeded.

SE_STAT_CODE_UNRESOLVED_OBJECT and the output parameters are set as for the SE_STAT_CODE_SUCCESS case, if valid parameters were passed in and valid objects are returned, but the object returned using *associate_object_out_ptr is unresolved.

SE_STAT_CODE_NULL_REQUIRED_PARAMETER and the output parameter values are left unaltered, if associate_object_out_ptr was NULL.

SE_STAT_CODE_INVALID_OR_NULL_OBJECT and the output parameters are set to NULL, if from_object was not a handle to a valid, active (i.e., unfreed) SEDRIS object.

SE_STAT_CODE_UNRESOLVED_START_OBJECT and the output parameters are set as for the SE_STAT_CODE_INVALID_OR_NULL_OBJECT case, if from_object is an unresolved SEDRIS object.

SE_STAT_CODE_NO_OBJECT and the output parameters are set as for the SE_STAT_CODE_INVALID_OR_NULL_OBJECT case, if the from_object did not contain 'n' associate objects of the desired class.

SE_STAT_CODE_OUT_OF_MEMORY and the output parameters are set as for the SE_STAT_CODE_INVALID_OR_NULL_OBJECT case, if the API could not allocate memory.

SE_STAT_CODE_FAILURE and the output parameters are set as for the SE_STAT_CODE_INVALID_OR_NULL_OBJECT case, if

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

an invalid value was supplied for desired_associate_class,

the given class of associate is not ordered for the given from_object, or

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

Parameters Notes

from_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 from_object. This is a 1-based
      index.

associate_object_out_ptr

 a pointer to a variable in the user's memory
    space, to which the desired associate of the from_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 associate object will be copied. If no link class object was
    attached to the link used to reach the desired associate object, then
    *link_class_object_out_ptr will be NULL.

SE_STAT_CODE_SUCCESS	and associate_object_out_ptr is set to point to the desired associate object, and link_class_object_out_ptr is set appropriately, if valid parameters were passed in and all operations succeeded.
SE_STAT_CODE_UNRESOLVED_OBJECT	and the output parameters are set as for the SE_STAT_CODE_SUCCESS case, if valid parameters were passed in and valid objects are returned, but the object returned using *associate_object_out_ptr is unresolved.
SE_STAT_CODE_NULL_REQUIRED_PARAMETER	and the output parameter values are left unaltered, if associate_object_out_ptr was NULL.
SE_STAT_CODE_INVALID_OR_NULL_OBJECT	and the output parameters are set to NULL, if from_object was not a handle to a valid, active (i.e., unfreed) SEDRIS object.
SE_STAT_CODE_UNRESOLVED_START_OBJECT	and the output parameters are set as for the SE_STAT_CODE_INVALID_OR_NULL_OBJECT case, if from_object is an unresolved SEDRIS object.
SE_STAT_CODE_NO_OBJECT	and the output parameters are set as for the SE_STAT_CODE_INVALID_OR_NULL_OBJECT case, if the from_object did not contain 'n' associate objects of the desired class.
SE_STAT_CODE_OUT_OF_MEMORY	and the output parameters are set as for the SE_STAT_CODE_INVALID_OR_NULL_OBJECT case, if the API could not allocate memory.
SE_STAT_CODE_FAILURE	and the output parameters are set as for the SE_STAT_CODE_INVALID_OR_NULL_OBJECT case, if 'n' was 0 (since this is a 1-based index), an invalid value was supplied for desired_associate_class, the given class of associate is not ordered for the given from_object, or the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.