| MIL 10 Reference
| Customize Help
| Save Settings

MsysHookFunction


See also
Availability
Available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux

Not supported on:
Not supported on Host system
Not supported on Matrox GPU processing driver
Not supported on Matrox Orion HD
Not supported on Matrox Radient eV-CXP
Not supported on Matrox Vio
Partially supported on:
Partially supported on Matrox CronosPlus
Partially supported on Matrox GigE Vision driver
Partially supported on Matrox IEEE 1394 IIDC driver
Partially supported on Matrox Iris GT
Partially supported on Matrox Morphis
Partially supported on Matrox Morphis QxT
Partially supported on Matrox Radient eCL
Partially supported on Matrox Solios eA/XA
Partially supported on Matrox Solios ecl/xcl/ev-cl
Partially supported on Matrox USB3 Vision driver (requires Update 19)

For any information regarding a MIL system added during a MIL Update, see the MIL system’s release note

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
MsysGetHookInfo
MsysInquire
Synopsis
Hook a function to a system event.
Syntax
void MsysHookFunction(
MIL_ID SysId, //in
MIL_INT HookType, //in
MIL_SYS_HOOK_FUNCTION_PTR HookHandlerPtr, //in
void *UserDataPtr //in
)
Description

This function allows you to attach or detach a user-defined function to a specified system 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 MsysHookFunction() 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 more information about the event from within the hook handler function using MsysGetHookInfo().

Note that functions hooked to an event execute on a distinct thread. This permits the functions to run concurrently from the operation that fired the event and from functions hooked to other events. Although there is a small queue to permit a certain amount of overlap, hooked functions should not take longer to execute than the period in which two of their associated events can occur. You cannot determine the instance of the event that fired the function.

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 which MIL system’s documentation you should use in its place and any possible differences.
Parameters
This function is not supported on the selected boards.
This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.
Parameters
SysId

Specifies the identifier of the system on which to hook a function.

function map For specifying the system identifier
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse M_DEFAULT_HOST

Specifies the default Host system of the current MIL application.

 † b c e f g h j l m o p r s
Collapse MIL system identifier

Specifies a valid system identifier, previously allocated using MsysAlloc().

 † b c e f g h j l m o p r s
HookType

Specifies the system event to which to hook the function. This parameter can be set to one of the following values.

function map For specifying the system event to hook
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse M_CAMERA_PRESENT +

Hooks the function to the presence of the camera.

Note that this hook requires the use of the mtxgigeservice process. If the service is not started, a MIL error will be generated when calling this value.

(summarize)
† c o s
Collapse M_IO_CHANGE +

Hooks the function to the event that occurs when an I/O signal changes in accordance with its specified interrupt mode, set using MsysControl() with M_IO_INTERRUPT_ACTIVATION. Within the scope of the hook-handler function, it is prudent to verify that the appropriate I/O signal triggered the hook-handler function, using MsysGetHookInfo() with M_IO_INTERRUPT_SOURCE.

If more than one input signal triggers an interrupt at the same time, the hook-handler function (or chain of hook-handler functions) is called for each input signal that generated an interrupt. As a result, any and all user-specified function(s) hooked using this hook type will be executed for each interrupt.

(summarize)
† b e f g h
Collapse M_UART_DATA_RECEIVED +

Hooks the function to the event that occurs when the specified UART receives data. Use MsysInquire() with M_UART_PRESENT to return the number of UARTs available.

Note that this value can be used in combination; see below.

(summarize)
† g h j l m p r
Collapse M_WATCHDOG_WARNING +

Hooks the function to the event that occurs when the Watchdog warning timer is not reset before the specified interval expires. From within your hook-handler function, you should reset the Watchdog's main timer. If it is not reset, the Host computer will reboot.

(summarize)
† g h
Combination constant for M_UART_DATA_RECEIVED.

You can add the following value to the above-mentioned value to set the UART upon which the system event occurs.

function map For specifying the UART upon which the system event occurs
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse
M_UART_NB(
MIL_INT M_DEVn
)

Specifies the UART upon which the system event occurs. Use MsysInquire() with M_UART_PRESENT to determine the number of UARTs on the system.

(summarize)
† g h j l m p r
Parameters

Specifies a UART, where n is from 0 to 3.

 † g h j l m p r
MIL system specific

There is 1 UART available on Matrox Morphis.

 † g

There are 4 UARTs available on Matrox Solios eA/XA Quad, 2 on Matrox Solios eA/XA dual, and 1 on Matrox Solios eA/XA single.

 † l

There are 2 UARTs are available on Matrox Solios eCL/XCL dual-Base/single-Medium operating in dual-Base mode, and 1 is available on Matrox Solios eCL/XCL-B, eCL/XCL-F, and eCL/XCL dual-Base/single-Medium operating in single-Medium mode.

 † j m p r

There are 2 UARTS available on Matrox Radient eCL-DB and eCL-DF, 3 on Matrox Radient eCL-QB, and 1 on Matrox Radient eCL-SF.

 † j p r
Combination constant for the values listed in For specifying the system event to hook.

You can add the following value to the above-mentioned values to specify that the function should be unhooked.

function map For specifying that the function should be unhooked
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_UNHOOK

Unhooks a hooked function.

 † b c e f g h j l m o p r s
HookHandlerPtr

Specifies the address of the function that should be called when the specified event occurs. The hook-handler function must be declared as follows:

MIL_INT MFTYPE HookHandler(
MIL_INT HookType,
MIL_ID EventId,
void *UserDataPtr
)
Parameters
HookType

Type of system event hooked.

EventId

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

UserDataPtr

Specifies the user data pointer passed to MsysHookFunction().

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

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 not used.

Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
DEFAULT HOST CAMERA PRESENT IO CHANGE UART DATA RECEIVED WATCHDOG WARNING DEVn UNHOOK