MappHookFunction

This function allows you to attach or detach a user-defined function to a specified application event. Once a hook-handler function is defined and hooked to an event, it is automatically called when the event occurs.

You can hook more than one function to an event by making separate calls to MappHookFunction() for each function that you want to hook. MIL automatically chains and keeps an internal list of all these hooked functions. When a function is hooked, this new function is added to the end of the list. When the event happens, all user-defined functions in the list will be executed in the same order that they were hooked to the event. You can also remove any function from the list; in this case, MIL preserves the order of the remaining functions in the list.

You can obtain information concerning the event, using MappGetHookInfo(), and take appropriate action before returning control to the application.

In multi-thread environments, an MappHookFunction() call hooks or unhooks the function specified by HookHandlerPtr to all application threads running MIL, unless specifically limited to the calling thread.

This function is typically used to trap errors that occur in an application, without checking every MIL function execution with MappGetError(), or to detect the start or end of certain MIL functions.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see if there is complementary information.

Parameters

This function is not supported on the selected boards.

Parameters

ContextAppId

Specifies the identifier of the application context to use.

For specifying the application context
Value	Description
M_DEFAULT	Specifies the current application context.
Application Context Identifier	Specifies the application context identifier.

HookType

Specifies the event type. This parameter can be set to one of the following values.

For specifying the event type
Value	Description
M_ERROR_CURRENT +	Calls the hook-handler function each time an error occurs. Note that functions attached to this type of event are called first before global errors (M_ERROR_GLOBAL) and before the error dialog occurs (if enabled using MappControl() with M_ERROR). (summarize) Calls the hook-handler function each time an error occurs. (more details...)
M_ERROR_FATAL +	Calls the hook-handler function when a user presses the Cancel button in an error dialog. For this event to occur, MappControl() with M_ERROR must be set to M_PRINT_ENABLE. (summarize) Calls the hook-handler function when a user presses the Cancel button in an error dialog. (more details...)
M_ERROR_GLOBAL +	Calls the hook-handler function when the first error occurs in a series of MIL calls. Note that this event occurs after M_ERROR_CURRENT events, but before the error dialog occurs (if enabled using MappControl() with M_ERROR). (summarize) Calls the hook-handler function when the first error occurs in a series of MIL calls. (more details...)
M_TRACE_END +	Calls the hook-handler function at the end of each MIL function. When setting the HookType parameter to M_TRACE_END, the only MIL function that can be called in a hook function is MappGetHookInfo(), otherwise infinite recursion will occur. (summarize) Calls the hook-handler function at the end of each MIL function. (more details...)
M_TRACE_START +	Calls the hook-handler function at the start of each MIL function. When setting the HookType parameter to M_TRACE_START, the only MIL function that can be called in a hook function is MappGetHookInfo(), otherwise infinite recursion will occur. (summarize) Calls the hook-handler function at the start of each MIL function. (more details...)

Combination constant for any of the possible values of the HookType parameter.

You can add the following value to the above-mentioned values to set whether to detach the hook-handler function.

For the HookType parameter
Combination value	Description
M_UNHOOK	Detaches (that is, unhooks) the hook-handler function.

Combination constant for any of the possible values of the HookType parameter.

You can add the following value to the above-mentioned values to set whether to limit the hooking or unhooking of the function to the calling thread.

For hooking or unhooking the function to application threads
Combination value	Description
M_THREAD_CURRENT	Limits the hooking or unhooking of the function to the calling thread. For example, to call the hook-handler function only for errors occurring in the current thread, specify M_ERROR_CURRENT + M_THREAD_CURRENT as the HookType parameter. (summarize) Limits the hooking or unhooking of the function to the calling thread. (more details...)

HookHandlerPtr

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:

MIL_INT MFTYPE HookHandler(

MIL_INT HookType,

MIL_ID EventId,

void *UserDataPtr

)

Parameters

HookType

Type of event hooked.

EventId

Event identifier to pass to MappGetHookInfo() when inquiring about the hooked event.

UserDataPtr

Specifies the user data pointer passed to MappHookFunction().

Upon successful completion, the hook-handler function should return M_NULL. Note, MFTYPE and MIL_APP_HOOK_FUNCTION_PTR are reserved MIL predefined types for functions and data pointers, respectively.

UserDataPtr

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 user data is not required.

Compilation information

Header	Include mil.h.
Library	Use mil.lib.
DLL	Requires mil.dll.