Synopsis
Hook a function to a digitizer event.
Format
MDIGHOOKFCTPTR MdigHookFunction(DigId, HookType, HookHandlerPtr, UserDataPtr)
Description
This function allows you to attach or detach a user-defined function to a specified digitizer event. Once a hook-handler function is defined and hooked to an event, it is automatically called when the event occurs.
This function is not supported by all platforms.
Note, you must chain all hook functions. Before hooking an event, use MdigInquire to check if another function is hooked to the same event. If the hook-handler pointer is not M_NULL, save the hook-handler pointer and the user data pointer, then call MdigHookFunction. You must ensure that your hook function calls the previous hook function with the saved user data pointer and, when unhooking your function, restores it with a call to MdigHookFunction, using the saved parameters.
The DigId parameter specifies the identifier of the digitizer.
The HookType parameter specifies the event type. This parameter can be set to one of the following:
| MIL_ID DigId; | Digitizer identifier |
| long HookType; | Type of event to hook |
| MDIGHOOKFCTPTR HookHandlerPtr; | Pointer to hook function |
| void *UserDataPtr | User data pointer |
| M_GRAB_START | Hook to the start of each grab. |
| M_GRAB_END | Hook to the end of each grab. |
| M_GRAB_FRAME_START | Hook to the start of grabbed frames. |
| M_GRAB_FRAME_END | Hook to the end of grabbed frames. |
| M_GRAB_FIELD_END | Hook to the end of grabbed fields. |
| M_GRAB_FIELD_END_ODD | Hook to the end of grabbed odd fields. |
| M_GRAB_FIELD_END_EVEN | Hook to the end of grabbed even fields. |
Even if you are not in grabbing mode, the parameter can be set to one of the following:
| M_FRAME_START | Hook to the start of the incoming signal’s frames. |
| M_FIELD_START | Hook to the start of the incoming signal’s fields. |
| M_FIELD_START_ODD | Hook to the start of the incoming signal’s odd fields. |
| M_FIELD_START_EVEN | Hook to the start of the incoming signal’s even fields. |
The HookHandlerPtr parameter specifies the address of the function that should be called when an event occurs.
The hook-handler function, pointed to by HookHandlerPtr, must be declared as follows:
long MFTYPE HookHandler(HookType, EventId, UserDataPtr);
| long HookType; | Type of event hooked |
| MIL_ID EventId; | Event identifier (currently set to null) |
| void MPTYPE *UserDataPtr; | user data pointer |
Upon successful completion, the hook-handler function should return M_NULL. Note, MDIGHOOKFCTPTR and MPTYPE are reserved MIL predefine types for function and data pointers.
The UserDataPtr parameter specifies the address of the user data that you want to make available to the hook-handler function. This address is passed to the hook-handler function, through its UserDataPtr parameter, when the specified event occurs. Set this parameter to M_NULL if not used.
Returned value
The returned value is the address of the hook-handler function (if any) that was previously hooked to the specified type of event. This allows you to chain hooked functions, or to restore the old hook function when unhooking.
See also