|
SEDRIS Reference Manual
APPENDIX A - Transmittal Access Level 0 API Functions SE SetUserData |
|---|
| extern SE_Return_Code | |||
| SE_SetUserData | |||
| ( | |||
| SE_Object | object_in, | (notes) | |
| void | * | user_data | (notes) |
| ); | |||
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).
| SE_RET_CODE_SUCCESS | and the user data is set. |
| SE_RET_CODE_FAILURE | and the status code is set appropriately if the call failed. |
SE_Status_Code(s) when SE_RET_CODE_SUCCESS is returned:
| SE_STAT_CODE_SUCCESS | set if valid parameters were passed in and the call was successful. |
SE_Status_Code(s) when SE_RET_CODE_FAILURE is returned:
| SE_STAT_CODE_INACTIONABLE_FAILURE | set if the call fails for any reason. |
the SEDRIS object to store a pointer to some user data
the pointer to be stored with the SEDRIS object.
If NULL, 'clears' the pointer.
Prev: SE_SetTransmittalName.
Next: SE_TransmittalsAreSame.
Up:Index.
|