SEDRIS Reference Manual
APPENDIX A - Transmittal Access Level 0 API
Functions
SE GetAssociate
extern SE_Return_Code
SE_GetAssociate
(
SE_Object associating_object,1
SE_DRM_Class drm_class,2
SE_ITR_Behaviour itr_traversal,3
SE_Object *associate_object,4
SE_Object *link_object5
);

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 *associate_object.


Returns

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

SE_Status_Code(s) when SE_RETCOD_FAILURE is returned:

SE_STATCODE_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_STATCODE_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_STATCODE_UNRESOLVED_INPUT_OBJECT set if associating_object is unresolved.
SE_STATCODE_NO_OBJECT set if no associate of the desired DRM class could be found.
SE_STATCODE_C_ENUMERATION_VALUE_INVALID set if drm_class or itr_traversal was not valid,
SE_STATCODE_INACTIONABLE_FAILURE set if the call fails for any other reason.

Parameters Notes

1 the object for which one associate is desired.

2 the DRM class of associate desired. If SE_CLS_DRM_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.

3 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.

4 a pointer to the associate found, if any

5 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_object, if there is a link object; otherwise set to NULL. If the user passes in NULL for link_object, then link objects will be ignored (and *link_object will not be affected).


Prev: SE_GetAggregate. Next: SE_GetColourModel. Up:Index.

Last updated: July 26, 2006 Copyright © 2006 SEDRIS