Function Name: Add Object To Aggregate

Definition

Creates an object of the given class, sets its fields, adds it to a transmittal, creates its relationship to the given aggregate, then frees the new component object.

Note that this function does not return the object that has just been created. To access that object, you must retrieve it with another function, e.g. SE_GetNextObject() after creating an iterator.

Returns

SE_NULL_REQUIRED_PARAMETER - and no changes are made, if new_object_tag is SE_NULL_TOKEN.

SE_INVALID_OR_NULL_OBJECT - and no changes are made, if aggregate_object is NULL, does not belong to a valid SDRM class, or does not belong to a valid transmittal.

SE_UNRESOLVED_START_OBJECT - and no changes are made, if aggregate_object is unresolved.

SE_INVALID_ACCESS_MODE - and no changes are made, if aggregate_object belongs to a transmittal opened in SE_READ_ONLY mode.

SE_OUT_OF_MEMORY - and no changes are made, if no memory can be allocated for the new object.

SE_FAILURE - and no changes are made, if

1. new_fields is provided, but not consistent with new_object_tag
2. dynamic binding is used, and the specified API implementation does not provide the necessary level 0 functions (e.g. SE_CreateObject()).

Prototype

Parameters Notes

aggregate_object

 existing object, for which we are creating and adding a component

new_object_tag

 the DRM class of the new object being created

new_fields

 if present, used instead of the default fields for the new object