SE GetAggregate

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

extern SE_Return_Code
SE_GetAggregate
(
SE_Object		component_object,	¹
SE_DRM_Class		drm_class,	²
SE_ITR_Behaviour		itr_traversal,	³
SE_Object	*	aggregate_object,	⁴
SE_Object	*	link_object	⁵
);

Definition

Retrieves an aggregate object of a specified DRM class or of any DRM class (if not specified with drm_class) that directly contains the given object (component_object) as a component. For example, if SE_GetAggregate() is called with a <Model> as the component_object object, then a handle to the <Model Library> would be returned at *aggregate_object, since the <Model Library> is the aggregate object that contains the <Model> as a component.

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 and a valid aggregate of the specified class was found.
SE_STATCODE_DIFFERENT_TRANSMITTAL	set if the following conditions are met: 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 aggregate, and the iterator successfully resolved it and retrieved the aggregate 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 aggregate object is unresolved. In this case, the output parameters are set as for the SE_STATCODE_SUCCESS case.

SE_Status_Code(s) when SE_RETCOD_FAILURE is returned:

SE_STATCODE_UNRESOLVED_INPUT_OBJECT	set if component_object is unresolved.
SE_STATCODE_NO_OBJECT	set if no aggregate object of the specified 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

¹ the object for which one aggregate is desired.

² the DRM class of aggregate desired. If SE_CLS_DRM_NULL is passed in, then any type of aggregate object will do. If an abstract class is specified, the API will look for a concrete aggregate that is a descendant of the given abstract DRM class.

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

⁴ pointer to an SE_Object for the aggregate found.

⁵ if requested, then a handle to the link class object (a.k.a. association class object) traversed to reach the aggregate 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).