ADM-XRC SDK 2.8.1 User Guide (Linux)
© Copyright 2001-2009 Alpha Data
Prototype
ADMXRC_STATUS ADMXRC_InstallErrorHandler( ADMXRC_HANDLER_FUNCTION Routine)
Arguments
Argument | Type | Purpose |
Routine | In | The error handler routine to install |
Return value
Value | Meaning |
ADMXRC_SUCCESS | The error handler routine was successfully installed or uninstalled |
ADMXRC_FAILED | The error handler routine could not be installed because another thread held the error Mutex for an excessive period of time |
Description
This function is used to install a user-defined error handler function that will be called whenever the ADM-XRC function must return an error condition. The error handler function should be of type ADMXRC_HANDLER_FUNCTION:
void MyErrorHandler( const char* FunctionName, ADMXRC_STATUS Code);
If Routine is non-NULL, it must point to a function of the same type as MyErrorHandler above. If Routine is NULL, any error handler function currently installed will be uninstalled.
A failed call to the ADMXRC_InstallErrorHandler function does not result in any currently installed handler function being called.
The error handler function is always called just before the API function generating the error returns. When the error handler is called, FunctionName will point to a NULL terminated string containing the name of the API function which failed and Code will contain the error code.
Due to the multithreaded nature of the API, mutual exclusion is enforced when the error handler is installed or called. When the error handler is installed, the API attempts to take a Win32 Mutex object, waiting for at most 1000 milliseconds for the wait to succeed. If the mutex wait fails due to timeout, ADMXRC_InstallErrorHandler returns ADMXRC_FAILED.
When the API calls the user specified error handler, the API attempts to take the same mutex in order to prevent the error handler being entered in a reentrant fashion. Therefore, the error handler routine should: