Function Name: Get Object Reference Count

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_GetNthComponentOfGivenType(). This function can also help the user interact with the SE_SetUserData() and SE_GetUserData() functions. See those function descriptions for details.

Returns

SE_NULL_REQUIRED_PARAMETER - and *ref_count_out_ptr is left unaltered, if ref_count_out_ptr was NULL.

SE_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_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.

Prototype

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.