SE GetAssociate

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

extern SE_Return_Code
SE_GetAssociate
(
SE_Object		object_in,	(notes)
SE_DRM_Class		drm_class,	(notes)
SE_ITR_Behaviour		itr_traversal,	(notes)
SE_Object	*	object_out_ptr,	(notes)
SE_Object	*	link_class_object_out_ptr	(notes)
);

Definition

Retrieves an associate object of a specified DRM class or of any DRM class (if not specified with drm_class) for the given object. For example, if SE_GetAssociate() is called with an <Image Mapping Function> instance, then a handle to the associated <Image> instance will be returned at *object_out_ptr.

Returns

SE_RET_CODE_SUCCESS	and the requested object is returned, if valid parameters were passed in and all operations succeeded.
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, only one object was found that satisfied the specified criteria, and no ITR references were involved.

SE_Status_Code(s) when SE_RET_CODE_FAILURE is returned:

SE_STAT_CODE_DIFFERENT_TRANSMITTAL SE_STAT_CODE_DIFFERENT_TRANSMITTAL set if valid parameters were passed in, the user requested that the API automatically resolve inter-transmittal references (ITR), an ITR reference was encountered in searching for the associate, and the iterator successfully resolved it and retrieved the associate from the new, different transmittal.

SE_STAT_CODE_UNRESOLVED_OUTPUT_OBJECT SE_STAT_CODE_UNRESOLVED_OUTPUT_OBJECT set if valid parameters were passed in and only one object was found that satisfied the specified criteria, but the associate object is unresolved.

SE_STAT_CODE_UNRESOLVED_INPUT_OBJECT SE_STAT_CODE_UNRESOLVED_INPUT_OBJECT set if object_in is unresolved.

SE_STAT_CODE_NO_OBJECT SE_STAT_CODE_NO_OBJECT set if no associate of the desired DRM class could be found.

SE_STAT_CODE_INACTIONABLE_FAILURE SE_STAT_CODE_INACTIONABLE_FAILURE set if

drm_class or itr_traversal was not valid, or

the call fails for any other reason.

Parameters Notes

object_in

 the object for which one associate is desired.

drm_class

 the DRM class of associate desired. If
    SE_DRM_CLS_NULL is passed in, then any associated object will do.
    Asking for an object of an abstract DRM class is allowed; in that case,
    the API will look for a concrete associate that is a descendant of the
    of the given abstract DRM class.

itr_traversal

 the user must choose how
    the function will behave when it encounters an Inter-Transmittal
    Reference (ITR). The function could automatically resolve such
    references and continue the search within the new transmittal;
    report all ITR references without resolving them; or just ignore
    them completely and continue to search within the current
    transmittal.

object_out_ptr

 a pointer to the associate found, if any

link_class_object_out_ptr

 if requested, then a handle
    to the link class object (a.k.a. association class object) traversed to
    reach the associate is copied to *link_class_object_out_ptr, if
    there is a link object; otherwise set to NULL.

    If the user passes in NULL for link_class_object_out_ptr, then
    link objects will be ignored (and *link_class_object_out_ptr
    will not be affected).

SE_STAT_CODE_DIFFERENT_TRANSMITTAL SE_STAT_CODE_DIFFERENT_TRANSMITTAL	set if valid parameters were passed in, the user requested that the API automatically resolve inter-transmittal references (ITR), an ITR reference was encountered in searching for the associate, and the iterator successfully resolved it and retrieved the associate from the new, different transmittal.
SE_STAT_CODE_UNRESOLVED_OUTPUT_OBJECT SE_STAT_CODE_UNRESOLVED_OUTPUT_OBJECT	set if valid parameters were passed in and only one object was found that satisfied the specified criteria, but the associate object is unresolved.
SE_STAT_CODE_UNRESOLVED_INPUT_OBJECT SE_STAT_CODE_UNRESOLVED_INPUT_OBJECT	set if object_in is unresolved.
SE_STAT_CODE_NO_OBJECT SE_STAT_CODE_NO_OBJECT	set if no associate of the desired DRM class could be found.
SE_STAT_CODE_INACTIONABLE_FAILURE SE_STAT_CODE_INACTIONABLE_FAILURE	set if drm_class or itr_traversal was not valid, or the call fails for any other reason.