SE GetAggregate

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

extern SE_Return_Code
SE_GetAggregate
(
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 aggregate object of a specified DRM class or of any DRM class (if not specified with drm_class) that directly contains the given object (object_in) as a component. For example, if SE_GetAggregate() is called with a <Model>> as the object_in object, then a handle to the <Model Library> would be returned at * object_out_ptr, since the <Model Library> is the aggregate object that contains the <Model> as a component.

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 and a valid aggregate of the specified class was found.

SE_STAT_CODE_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_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 aggregate object is unresolved. In this case, the output parameters are set as for the SE_STAT_CODE_SUCCESS case.

SE_Status_Code(s) when SE_RET_CODE_FAILURE is returned:

SE_STAT_CODE_UNRESOLVED_INPUT_OBJECT set if object_in is unresolved.

SE_STAT_CODE_NO_OBJECT set if no aggregate object of the specified DRM class could be found.

SE_STAT_CODE_INACTIONABLE_FAILURE set if

drm_class or itr_traversal was not valid,

the call fails for any other reason.

Parameters Notes

object_in

 the object for which one aggregate is desired.

drm_class

 the DRM class of aggregate desired.  If
    SE_DRM_CLS_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.

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

 pointer to an SE_Object for the aggregate found.

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 aggregate 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_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.

SE_STAT_CODE_SUCCESS	set if valid parameters were passed in and a valid aggregate of the specified class was found.
SE_STAT_CODE_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_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 aggregate object is unresolved. In this case, the output parameters are set as for the SE_STAT_CODE_SUCCESS case.

SE_STAT_CODE_UNRESOLVED_INPUT_OBJECT	set if object_in is unresolved.
SE_STAT_CODE_NO_OBJECT	set if no aggregate object of the specified DRM class could be found.
SE_STAT_CODE_INACTIONABLE_FAILURE	set if drm_class or itr_traversal was not valid, the call fails for any other reason.