Retrieves the given kind of aggregate object (an aggregate object of the specified 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.
This is a 'short form, 1-shot' version of an Aggregate 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 aggregate should be retrieved. Iterators are necessary to retrieve multiple aggregates, but they can be a nuisance when retrieving unique aggregates (such as the Model Library aggregate of a Model as described above).
Given an object (the object_in)
and a type of aggregate to search for
(drm_class), this function will
look for an immediate aggregate object of the given type. Only aggregates
that include the object_in via
a two-way aggregation will be returned by this function.
SE_DIFFERENT_TRANSMITTAL - 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 aggregate, and the iterator successfully resolved it and retrieved the aggregate from the new, different transmittal. In this case, *object_out_ptr is set to point to the aggregate, and *association_class_object_out_ptr is set appropriately, unless the user passed in a NULL for that value.
SE_MULTIPLE_OBJECTS - 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, and the output parameters are set as for the SE_SUCCESS case.
SE_UNRESOLVED_OBJECT - 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_SUCCESS case.
SE_NULL_REQUIRED_PARAMETER - and no changes are made, if object_out_ptr was NULL.
SE_INVALID_OR_NULL_OBJECT - if object_in is not a handle to a valid, active (i.e., unfreed) SEDRIS object, or if drm_class held an invalid value. In this case
SE_UNRESOLVED_START_OBJECT - and the output parameters are set for the SE_INVALID_OR_NULL_OBJECT case, if object_in is unresolved.
SE_NO_OBJECT - and the output parameters are set for the SE_INVALID_OR_NULL_OBJECT case, if no aggregate object of the specified DRM class could be found.
SE_OUT_OF_MEMORY - and the output parameters are set for the SE_INVALID_OR_NULL_OBJECT case, if memory could not be allocated.
SE_FAILURE - and the output parameters are treated as they are for the SE_INVALID_OR_NULL_OBJECT case, if
the object for which one aggregate is desired.
the DRM class of aggregate desired. If
SE_NULL_TOKEN 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 *association_class_object_out_ptr, if
there is a link object; otherwise set to NULL.
If the user passes in NULL for association_class_object_out_ptr, then
link objects will be ignored (and *association_class_object_out_ptr
will not be affected).