MappHookFunction
- See also
Availability
Function map
- Examples
MappGetHookInfo
- MappInquire
| Table: | For specifying the event type |
| + combination: | For the HookType parameter |
| + combination: | For hooking or unhooking the function to application threads |
| MIL_ID ContextAppId, | //in |
| MIL_INT HookType, | //in |
| MIL_APP_HOOK_FUNCTION_PTR HookHandlerPtr, | //in |
| void *UserDataPtr | //in-out |
DescriptionThis 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.
ParametersSpecifies 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. |
||||||||||||||||||||||||||||||||||||||
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 hook-handler 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_OBJECT_PUBLISH_DMIL + |
Calls the hook-handler function when an object to be used with DMIL has its publication state modified. This event occurs when the publication state is modified using MobjControl() with M_DMIL_PUBLISH, or when the published object is freed as its publication state was set to M_NO. (summarize)Calls the hook-handler function when an object to be used with DMIL has its publication state modified. (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...) |
||||||||||||||||||||||||||||||||||||||
| M_WEB_CLIENT_CONNECTED + |
Calls the hook-handler function when a MILweb client application connects to your MIL application. Before a MILweb client can connect to your application, you must enable MILweb functionality using MappControl() with M_WEB_CONNECTION and M_ENABLE. (summarize)Calls the hook-handler function when a MILweb client application connects to your MIL application. (more details...) |
||||||||||||||||||||||||||||||||||||||
| M_WEB_CLIENT_DISCONNECTED + |
Calls the hook-handler function when a MILweb client application disconnects from your MIL application. |
||||||||||||||||||||||||||||||||||||||
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. |
||||||||||||||||||||||||||||||||||||||
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...) |
||||||||||||||||||||||||||||||||||||||
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:
Type of event hooked.
Event identifier to pass to MappGetHookInfo() when inquiring about the hooked event.
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.
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.
| Header | Include mil.h. |
| Library | Use mil.lib. |
| DLL | Requires mil.dll. |