|
SEDRIS Reference Manual
APPENDIX A - Transmittal Access Level 0 API Functions SE GetObjectReferenceCount |
|---|
| extern SE_Return_Code | |||
| SE_GetObjectReferenceCount | |||
| ( | |||
| SE_Object | object, | 1 | |
| SE_Integer | * | reference_count | 2 |
| ); | |||
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_Object 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_GetNthComponent(). This function can also help the user interact with the SE_SetUserData() and SE_GetUserData() functions. See those function descriptions for details.
| SE_RETCOD_SUCCESS | and the reference count is returned. |
| SE_RETCOD_FAILURE | and the status code is set appropriately if the call failed. |
SE_Status_Code(s) when SE_RETCOD_SUCCESS is returned:
| SE_STATCODE_SUCCESS | set if valid parameters were passed in. |
SE_Status_Code(s) when SE_RETCOD_FAILURE is returned:
| SE_STATCODE_INACTIONABLE_FAILURE | set if the call fails for any reason. |
1 the DRM object for which the number of 'active user references' will be returned.
2 a pointer to the variable in the user's memory space where the answer will be stored.
Prev: SE_GetObjectIDString.
Next: SE_GetPackedHierarchy.
Up:Index.
|