SE SetUserData

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

extern SE_Status_Code
SE_SetUserData
(
SE_Object		object_in,	(notes)
void	*	user_data	(notes)
);

Definition

Each SEDRIS Object returned from this API has a void* field set aside for user data. This pointer is for the convenience of the user of this API. When an object is first returned to a user, its user_data is NULL. A user can call SE_SetUserData() to update the user_data of an object as many times as he/she wants, as long as the user still has a valid SE_Object for that object. Once the user has 'returned' an object to the API (by calling SE_FreeObject()) then the user_data for that object is again set to NULL, since, from the user's point-of-view, the object does not exist any more. Whether the API kept that object cached in memory due to API memory management schemes or not, when the object is no longer active from the user's point-of-view (when the user has called SE_FreeObject() for that object once for every time the user was returned an SE_Object for that object), the user_data for that object is reset to NULL by the API.

NOTE:	Memory management of memory pointed to by the user_data is the sole responsibility of the user. If the user_data points to memory that should be freed, then the user should free that memory before returning the object to the API. The API will never access or free or interfere with in any way the memory pointed to by an object's user_data.

In order to help the user determine whether a call to SE_FreeObject() will return the object to the API, the SE_GetObjectReferenceCount() function is available. If a call to SE_GetObjectReferenceCount() indicates that there is only one reference to the object, then the next call to SE_FreeObject() will return the object to the API, and the user should perform any necessary memory management of the memory pointed to by the user_data for the object before the object is returned to the API (because once the object is returned to the API by the SE_FreeObject() call, the API will simply overwrite the user_data with NULL, and any memory that the user_data was pointing to is in danger of being 'orphaned' unless the user had other pointers somewhere that pointed to the same area).

Returns

SE_STAT_CODE_SUCCESS and *user_data is stored with object_in, if valid parameters were passed in. Note that if user_data is NULL, this has the effect of 'clearing' the pointer.

SE_STAT_CODE_INVALID_OR_NULL_OBJECT and no changes are made, if object_in is not a handle to a valid, active (i.e., unfreed) SEDRIS object.

SE_STAT_CODE_FAILURE and no changes are made, 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 to store a pointer to some user data

user_data

 the pointer to be stored with the SEDRIS object.
    If NULL, 'clears' the pointer.

SE_STAT_CODE_SUCCESS	and *user_data is stored with object_in, if valid parameters were passed in. Note that if user_data is NULL, this has the effect of 'clearing' the pointer.
SE_STAT_CODE_INVALID_OR_NULL_OBJECT	and no changes are made, if object_in is not a handle to a valid, active (i.e., unfreed) SEDRIS object.
SE_STAT_CODE_FAILURE	and no changes are made, if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.