spe_callback_handler_register - Register a user-defined function specified by the function pointer handler as the library callback function identified by callnum.
#include <libspe2.h>
int spe_callback_handler_register (void *handler, unsigned int callnum, unsigned int mode)
| Parameters | |
| handler | A function pointer to the user-defined callback handler. |
| callnum | The identifier under which to register this callback function. The valid range is 0..255. |
| mode | Specifies if a new callback should be registered or if an existing callback is being updated by this call. If a new registration is requested using a preexisting identifier for callnum, the request fails. If an update is requested for an unregistered value of callnum, the request fails. |
The spe_callback_handler_register function registers a new user-defined function specified by the function pointer as the library callback handler identified by callnum or updates an existing registration. In either case, handler must be a valid function pointer. and cannot be NULL. The function can also be used to update a built-in function registration. If an application wants to make a temporary change to an existing callback handler registration, it should first query the existing handler, then update with its own, temporary handler, and once the temporary handler is no longer required perform another update restoring the original handler registration.
On success, the function returns 0 (zero).
On error, -1 is returned and errno is set to indicate the error.
Possible errors include:
| EINVAL | Function argument error, for example, callnum out of range. |
| ESRCH | Error updating registration - no existing registration found. |
| EACCES | Error registering new callback - a callback is already registered for this callnum. |
Possible values of mode are as follows:
| Values | Description |
| SPE_CALLBACK_NEW | Register a new callback handler |
| SPE_CALLBACK_UPDATE | Update registration of an existing callback handler |