SE SetRootObject

SEDRIS Reference Manual APPENDIX A - LEVEL 0 READ and WRITE API Functions SE SetRootObject

extern SE_Status_Code
SE_SetRootObject
(
SE_Transmittal		transmittal_in,	(notes)
SE_Object		new_root_object_in,	(notes)
SE_Object	*	old_root_object_out_ptr	(notes)
);

Definition

Given a handle to a transmittal that has explicitly been opened in CREATE or UPDATE mode, set the passed DRM object as the root of the transmittal's object hierarchy. The previous root object, if any, is returned in the old_root_object_out_ptr parameter, if requested. If no root object has been set for the given transmittal, NULL is returned in old_root_object_out_ptr.

CAUTION Calling this function will permanently change the root object of the transmittal. In order to avoid orphaning objects within the transmittal, the old_root_object_out_ptr parameter is provided to allow the user to deal with any previously set root object. It is the user's responsibility to provide this argument as needed.

Returns

SE_STAT_CODE_SUCCESS and the old root object was successfully returned (if there was one and it was requested), and new_root_object_in has been successfully set to be the new root object of transmittal_in, if valid parameters were passed in and all operations succeeded.

SE_STAT_CODE_NULL_REQUIRED_PARAMETER and the output parameters are left unaltered, if old_root_object_out_ptr is NULL.

SE_STAT_CODE_INVALID_OR_NULL_TRANSMITTAL and *old_root_object_out_ptr is set to NULL and transmittal_in is left unaltered, if transmittal_in is not a handle to a valid, active (i.e., open) SEDRIS transmittal.

SE_STAT_CODE_INVALID_OR_NULL_OBJECT and the output parameters are set as for SE_STAT_CODE_INVALID_OR_NULL_TRANSMITTAL, if new_root_object_in is not a valid, active (i.e., unfreed) object.

SE_STAT_CODE_UNRESOLVED_OBJECT and the output parameters are set as for SE_STAT_CODE_INVALID_OR_NULL_TRANSMITTAL, if new_root_object_in is not a resolved object.

SE_STAT_CODE_INVALID_ACCESS_MODE and the output parameters are set as for SE_STAT_CODE_INVALID_OR_NULL_TRANSMITTAL, if transmittal_in was opened in read-only mode.

SE_STAT_CODE_DIFFERENT_TRANSMITTAL and the output parameters are set as for SE_STAT_CODE_INVALID_OR_NULL_TRANSMITTAL, if new_root_object_in does not belong to the given transmittal.

SE_STAT_CODE_OUT_OF_MEMORY and the output parameters are set as for SE_STAT_CODE_INVALID_OR_NULL_TRANSMITTAL, if *old_root_object_out_ptr was requested but could not be allocated.

SE_STAT_CODE_FAILURE and the output parameters are set as for SE_STAT_CODE_INVALID_OR_NULL_TRANSMITTAL, if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

Parameters Notes

transmittal_in

 a handle to the transmittal for which the root object
    is being set.

new_root_object_in

 a pointer to the SE_Object handle of the new root
    object of the transmittal.

old_root_object_out_ptr

 a pointer to the SE_Object handle to the
    previous root object of the transmittal.

SE_STAT_CODE_SUCCESS	and the old root object was successfully returned (if there was one and it was requested), and new_root_object_in has been successfully set to be the new root object of transmittal_in, if valid parameters were passed in and all operations succeeded.
SE_STAT_CODE_NULL_REQUIRED_PARAMETER	and the output parameters are left unaltered, if old_root_object_out_ptr is NULL.
SE_STAT_CODE_INVALID_OR_NULL_TRANSMITTAL	and *old_root_object_out_ptr is set to NULL and transmittal_in is left unaltered, if transmittal_in is not a handle to a valid, active (i.e., open) SEDRIS transmittal.
SE_STAT_CODE_INVALID_OR_NULL_OBJECT	and the output parameters are set as for SE_STAT_CODE_INVALID_OR_NULL_TRANSMITTAL, if new_root_object_in is not a valid, active (i.e., unfreed) object.
SE_STAT_CODE_UNRESOLVED_OBJECT	and the output parameters are set as for SE_STAT_CODE_INVALID_OR_NULL_TRANSMITTAL, if new_root_object_in is not a resolved object.
SE_STAT_CODE_INVALID_ACCESS_MODE	and the output parameters are set as for SE_STAT_CODE_INVALID_OR_NULL_TRANSMITTAL, if transmittal_in was opened in read-only mode.
SE_STAT_CODE_DIFFERENT_TRANSMITTAL	and the output parameters are set as for SE_STAT_CODE_INVALID_OR_NULL_TRANSMITTAL, if new_root_object_in does not belong to the given transmittal.
SE_STAT_CODE_OUT_OF_MEMORY	and the output parameters are set as for SE_STAT_CODE_INVALID_OR_NULL_TRANSMITTAL, if *old_root_object_out_ptr was requested but could not be allocated.
SE_STAT_CODE_FAILURE	and the output parameters are set as for SE_STAT_CODE_INVALID_OR_NULL_TRANSMITTAL, if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.