SE SetCallbackForOneFunctionOneStatusCode

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

extern SE_Status_Code
SE_SetCallbackForOneFunctionOneStatusCode
(
SE_Error_Handling_Function_Ptr	user_defined_function,	(notes)
SE_Level_0_API_Function	function_to_catch,	(notes)
SE_Status_Code	status_code_to_catch	(notes)
);

Definition

Registers a user-defined function as the 'callback' function to be called when the given status code is about to be returned by the given Level 0 API function. This user-defined function must be defined to match SE_Error_Handling_Function_Signature (see).

This is the most specific type of callback - a specific status code for a specific function. This callback has priority over a general function callback for the same function (if one is currently defined), and it also has priority over the general callback function (if one is currently defined). 'Has priority over' means that if a specific status code/specific function callback is defined, then it is the only callback which will be called when that particular status code is about to be returned from that particular function.

When an SEDRIS Level 0 API function returns, it will return the the appropriate SE_Status_Code status code. If the user has defined a callback to be called when that particular status code is about to be returned by that particular function, then that user-defined callback function will be called immediately before the function returns the status code. After the user-defined callback has been called, the Level 0 API function will still return the status code it was about to return. The user-defined callback has no effect on the status code returned. Instead, the user-defined callback simply provides the user a method for tracking the return values of the Level 0 API functions without explicitly checking each return value with an 'if' or 'switch' statement.

Returns

SE_STAT_CODE_SUCCESS and the callback is set, if valid parameters were passed in.

SE_STAT_CODE_FAILURE and no changes are made, if

function_to_catch and/or status_code_to_catch contained invalid values, or

the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

Parameters Notes

user_defined_function

 a pointer to a user-defined callback
    function. If NULL, then this 'clears' the specific function/specific
    status code callback capability for the given function and the given
    status code.

function_to_catch

 the specific function for which user_defined_function
    is designed to be a callback.

status_code_to_catch

 the specific status_code which will trigger a
    call to the user_defined_function when that status_code is about to
    be returned by the function_to_catch function.

SE_STAT_CODE_SUCCESS	and the callback is set, if valid parameters were passed in.
SE_STAT_CODE_FAILURE	and no changes are made, if function_to_catch and/or status_code_to_catch contained invalid values, or the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.