SEDRIS Reference Manual
APPENDIX A - Transmittal Access Level 0 API
Functions
SE SetSpecificCallback
extern SE_Return_Code
SE_SetSpecificCallback
(
SE_Status_Logger_Ptr user_defined_function,1
SE_API_Function function_to_catch,2
SE_Status_Code status_code_to_catch3
);

Definition

This function registers the function specified by user_defined_function as the callback function to be called when the status code specified by status_code_to_catch is about to be returned by the API function specified by function_to_catch. This user-defined function shall be of type SE_Status_Logger (see).

The value NULL for user_defined_function indicates that a callback function is not being requested.

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). The term has priority over means that if a specific status code/specific function callback is defined, it is the only callback that will be called when that particular status code is about to be returned from that particular function.

When an API function returns, it will return the appropriate 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, 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 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 API functions without explicitly checking each return value.


Returns

SE_RETCOD_SUCCESS and the callback function is set.
SE_RETCOD_FAILURE and the status code is set appropriately if the call failed.

Status Codes

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
  1. function_to_catch and/or status_code_to_catch contained invalid values, or
  2. the call fails for any reason

Parameters Notes

1 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.

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

3 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.


Prev: SE_SetSecondErrorMessage. Next: SE_SetTransmittalName. Up:Index.

Last updated: July 26, 2006 Copyright © 2006 SEDRIS