SE GetObjectReferenceCount

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

extern SE_Status_Code
SE_GetObjectReferenceCount
(
SE_Object		object_in,	(notes)
SE_Integer	*	ref_count_out_ptr	(notes)
);

Definition

Returns the number of currently outstanding SE_Object references for the given object. A user can have multiple references (multiple SE_Objects) to the same object by having the same object returned to the user from multiple iterators or from multiple calls to other Level 0 functions which return SE_Objects. An object is 'active' as long as the user has at least one SE_Object to the object. That is, an object is active until the user calls SE_FreeObject() for as many times as the user received SE_Objects for that object.

For example, if a user called SE_GetNextObject() five times and was returned SE_Objects to the same object five times, then the API counts that the user has five SE_Objects for that object. The object will not be 'returned' to the API until the user calls SE_FreeObject() five times for that object - once for every time the user received a SE_Object to that object.

This function can be used by the user to determine if the user already has a pointer to an object just returned from any of the Level 0 calls that return objects (e.g. SE_GetNextObject(), SE_GetNthComponentOfDRMClass(). This function can also help the user interact with the SE_SetUserData() and SE_GetUserData() functions. See those function descriptions for details.

Returns

SE_STAT_CODE_SUCCESS and *ref_count_out_ptr is set appropriately, if valid parameters were passed in.

SE_STAT_CODE_NULL_REQUIRED_PARAMETER and *ref_count_out_ptr is left unaltered, if ref_count_out_ptr was NULL.

SE_STAT_CODE_INVALID_OR_NULL_OBJECT and *ref_count_out_ptr is set to zero (0), if object_in is not a handle to a valid, active (i.e., unfreed) SEDRIS object.

SE_STAT_CODE_FAILURE and *ref_count_out_ptr is set to zero (0), if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

Parameters Notes

object_in

 the SEDRIS object for which the number of 'active
    user references' will be returned.

ref_count_out_ptr

 a pointer to the variable in the user's memory
    space where the answer will be stored.

SE_STAT_CODE_SUCCESS	and *ref_count_out_ptr is set appropriately, if valid parameters were passed in.
SE_STAT_CODE_NULL_REQUIRED_PARAMETER	and *ref_count_out_ptr is left unaltered, if ref_count_out_ptr was NULL.
SE_STAT_CODE_INVALID_OR_NULL_OBJECT	and *ref_count_out_ptr is set to zero (0), if object_in is not a handle to a valid, active (i.e., unfreed) SEDRIS object.
SE_STAT_CODE_FAILURE	and *ref_count_out_ptr is set to zero (0), if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.