SE GetAssociate

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

extern SE_Status_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 the given kind of associated object from the given object.

This is a 'short form, 1-shot' version of an Associate Iterator. It saves the user the trouble of creating an iterator, making a call to SE_GetNextObject(), and then freeing the iterator, in the case when the user knows that one and only one associate should be retrieved. Iterators are necessary to retrieve multiple associates, but they can be a nuisance when retrieving unique associates (such as retrieving the one and only one <Image> object that must be associated to an <Image Mapping Function> object).

Given an object (the object_in) and a DRM class of associate to search for (drm_class), this function will look for an immediately associated object of the given DRM class. Only objects at the 'to' end of a one-way association, or at either end of a two-way association, will be returned by this function.

Returns

SE_STAT_CODE_SUCCESS and *object_out_ptr is set to point to the associate, and *link_class_object_out_ptr is set appropriately if provided, if valid parameters were passed in, only one object was found that satisfied the specified criteria, and no ITR references were involved.

SE_STAT_CODE_DIFFERENT_TRANSMITTAL and the output parameters are set as for the SE_STAT_CODE_SUCCESS case, 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_OBJECT and the output parameters are set as for the SE_STAT_CODE_SUCCESS case, 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_MULTIPLE_OBJECTS and the output parameters are set as for the SE_STAT_CODE_SUCCESS case, if valid parameters were passed in but multiple objects were found that satisfied the specified criteria. In this case, an arbitrary object is chosen that specifies the criteria.

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

SE_STAT_CODE_INVALID_OR_NULL_OBJECT and *object_out_ptr is set to NULL and *link_class_object_out_ptr (if provided) is set to NULL, if object_in is not a handle to a valid, active (i.e., unfreed) SEDRIS object, or if drm_class held an invalid value.

SE_STAT_CODE_UNRESOLVED_START_OBJECT and the output parameters are set as for the SE_STAT_CODE_INVALID_OR_NULL_OBJECT case, if object_in is unresolved.

SE_STAT_CODE_NO_OBJECT and the output parameters are set as for the SE_STAT_CODE_INVALID_OR_NULL_OBJECT case, if no associate of the desired DRM class could be found.

SE_STAT_CODE_OUT_OF_MEMORY and the output parameters are set as for the SE_STAT_CODE_INVALID_OR_NULL_OBJECT case, if memory allocation failed.

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

drm_class or itr_traversal was not valid,

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

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_SUCCESS	and object_out_ptr is set to point to the associate, and link_class_object_out_ptr is set appropriately if provided, if valid parameters were passed in, only one object was found that satisfied the specified criteria, and no ITR references were involved.
SE_STAT_CODE_DIFFERENT_TRANSMITTAL	and the output parameters are set as for the SE_STAT_CODE_SUCCESS case, 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_OBJECT	and the output parameters are set as for the SE_STAT_CODE_SUCCESS case, 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_MULTIPLE_OBJECTS	and the output parameters are set as for the SE_STAT_CODE_SUCCESS case, if valid parameters were passed in but multiple objects were found that satisfied the specified criteria. In this case, an arbitrary object is chosen that specifies the criteria.
SE_STAT_CODE_NULL_REQUIRED_PARAMETER	and the output parameter values are left unaltered, if object_out_ptr was NULL.
SE_STAT_CODE_INVALID_OR_NULL_OBJECT	and object_out_ptr is set to NULL and link_class_object_out_ptr (if provided) is set to NULL, if object_in is not a handle to a valid, active (i.e., unfreed) SEDRIS object, or if drm_class held an invalid value.
SE_STAT_CODE_UNRESOLVED_START_OBJECT	and the output parameters are set as for the SE_STAT_CODE_INVALID_OR_NULL_OBJECT case, if object_in is unresolved.
SE_STAT_CODE_NO_OBJECT	and the output parameters are set as for the SE_STAT_CODE_INVALID_OR_NULL_OBJECT case, if no associate of the desired DRM class could be found.
SE_STAT_CODE_OUT_OF_MEMORY	and the output parameters are set as for the SE_STAT_CODE_INVALID_OR_NULL_OBJECT case, if memory allocation failed.
SE_STAT_CODE_FAILURE	and the output parameters are treated as for the SE_STAT_CODE_INVALID_OR_NULL_OBJECT case, if drm_class or itr_traversal was not valid, the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.