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.
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 associate, and the iterator successfully resolved it and retrieved the associate from the new, different transmittal. In this case, *object_out_ptr is set to point to the associate, and *association_class_object_out_ptr is set appropriately, unless the user passed in a NULL for that value.
SE_UNRESOLVED_OBJECT- if valid parameters were passed in and only one object was found that satisfied the specified criteria, but the associate object is unresolved. In this case, the output parameters are set as for the SE_SUCCESS case.
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_NULL_REQUIRED_PARAMETER - if object_out_ptr was NULL. In this case, the output parameter values are left unaltered.
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 - if object_in is unresolved. In this case, the output parameters are set for the SE_INVALID_OR_NULL_OBJECT case.
SE_NO_OBJECT - if no associate of the desired DRM class could be found. In this case, the output parameters are set for the SE_INVALID_OR_NULL_OBJECT case.
SE_OUT_OF_MEMORY - if memory could not be allocated. In this case, the parameters are treated as they are for the SE_INVALID_OR_NULL_OBJECT case.
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 associate is desired.
the DRM class of associate desired. If
SE_NULL_TOKEN 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.
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.
a pointer to the associate found, if any
if requested, then a handle
to the link class object (a.k.a. association class object) traversed to
reach the associate 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).