| MIL 10 Reference
| Customize Help
| Save Settings

MsysGetHookInfo


See also
Availability
Available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux

Not supported on:
Not supported on Matrox CronosPlus
Not supported on Matrox GPU processing driver
Not supported on Matrox Orion HD
Not supported on Matrox Radient eCL
Not supported on Matrox Radient eV-CXP
Not supported on Matrox Solios eA/XA
Not supported on Matrox Solios ecl/xcl/ev-cl
Not supported on Matrox Vio
Partially supported on:
Partially supported on Host system
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 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 Matrox 4Sight-X with restrictions
Available on Matrox Supersight with restrictions
Available on Non-Matrox computer with restrictions
Available on Matrox 4Sight GP
function map Function map
Examples
MsysFree
MsysHookFunction
Synopsis
Get information about a hook event.
Syntax
MIL_INT MsysGetHookInfo(
MIL_ID SysId, //in
MIL_ID EventId, //in
MIL_INT64 InquireType, //in
void *UserVarPtr //out
)
Description

This function allows you to get information about the event that caused the hook function to be called. MsysGetHookInfo() should only be called within the scope of a system hook-handler function (see MsysHookFunction()).

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.

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

Specifies the default Host system of the current MIL application.

 † a c e f g h o s
Collapse MIL system identifier

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

 † a c e f g h o s
EventId

Specifies the system event identifier received by the hook-handler function (see MsysHookFunction()).

InquireType

Specifies the type of information about which to inquire.

See the Parameter associations section for possible values that can be specified.

UserVarPtr
Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):
  • array of type MIL_TEXT_CHAR
  • MIL_DOUBLE
  • MIL_INT
  • MIL_INT64

Specifies the address in which to write the requested information.

See the Parameter associations section for possible values that can be returned.

Parameter associations

The tables below list possible values for the InquireType parameter and possible values returned to the UserVarPtr parameter.

The following allows you to retrieve information about various system hook event. Unless otherwise specified, you can retrieve these information types if you call this function from within a function hooked to any system event using MsysHookFunction().

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_INT.

function map For retrieving information about a general system hook event
CollapseInquireType Description
MIL system-specific
tooltip (†)
UserVarPtr
- Possible values returned
Collapse M_GRAB_TRIGGER_MISSED

Retrieves the number of missed triggers occurring on timer 2.

(summarize)
† f
Collapse Value

Specifies the number of missed triggers.

 † f

The following allows you to retrieve information about a camera-specific event. The following information types are only available if MsysGetHookInfo() was called from a function hooked to a GenICam event using M_CAMERA_PRESENT. In addition, the GenICam event must be enabled using MdigControlFeature(), and the message channel must be supported by your camera.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_INT.

function map For inquiring about a camera-specific event
CollapseInquireType Description
MIL system-specific
tooltip (†)
UserVarPtr
- Possible values returned
Collapse M_CAMERA_PRESENT

Retrieves whether a camera has been added or re-connected to the system.

(summarize)
† c o s
Collapse M_FALSE

Specifies that a camera has been added or re-connected to the system.

 † c o s
Collapse M_TRUE

Specifies that a camera has been removed from the system.

 † c o s
Collapse M_GC_IP_ADDRESS_STRING

Retrieves the IP address (IPv4) of the camera that generated the M_CAMERA_PRESENT event.

(summarize)
† c s
Collapse UserVarPtr data type info

Data type: array of type MIL_TEXT_CHAR
Array size: Determined with M_GC_IP_ADDRESS_STRING_SIZE.

† c s
Collapse MIL_TEXT("nnn.nnn.nnn.nnn") 1

Specifies the IP address of the camera as a string. The address string is expressed in dotted decimal notation, where each dotted decimal value (nnn) is a number between 0 and 255.

(summarize)
† c s
Collapse M_GC_IP_ADDRESS_STRING_SIZE

Inquires the length of the string returned by M_GC_IP_ADDRESS_STRING.

(summarize)
† c s
Collapse Value

Specifies the length of the string, including the terminating null character ("\0").

 † c s
Collapse M_GC_MAC_ADDRESS_STRING

Retrieves the MAC address of the camera that generated the M_CAMERA_PRESENT event.

(summarize)
† c s
Collapse UserVarPtr data type info

Data type: array of type MIL_TEXT_CHAR
Array size: Determined with M_GC_MAC_ADDRESS_STRING_SIZE.

† c s
Collapse MIL_TEXT("nn-nn-nn-nn-nn-nn") 1

Specifies the MAC address of the camera, as a string. The address string is expressed in hexadecimal pairs, where each pair (nn) is a hexadecimal number between 00 and FF.

(summarize)
† c s
Collapse M_GC_MAC_ADDRESS_STRING_SIZE

Inquires the length of the string returned by M_GC_MAC_ADDRESS_STRING.

(summarize)
† c s
Collapse Value

Specifies the length of the string, including the terminating null character ("\0").

 † c s
Collapse M_GC_UNIQUE_ID_STRING

Inquires the unique identifier for your camera.

(summarize)
† c o s
MIL system specific

This is the camera's MAC address.

 † c s

This is the camera's global unique identifier (GUID).

 † o
Collapse UserVarPtr data type info

Data type: array of type MIL_TEXT_CHAR
Array size: Determined by calling MsysGetHookInfo() with M_GC_UNIQUE_ID_STRING_SIZE

† c o s
Collapse MIL_TEXT("nnnnnnnnnnnn") 1

Specifies the unique identifier, as a string. The string is expressed in hexadecimal.

(summarize)
† c o s
Collapse M_GC_UNIQUE_ID_STRING_SIZE

Inquires the size of the string containing the unique identifier for your camera.

(summarize)
† c o s
Collapse Value

Specifies the number of characters in the string.

 † c o s
Collapse M_GC_USER_NAME

Retrieves the user-defined name of the camera that generated the M_CAMERA_PRESENT event.

(summarize)
† c o s
Collapse UserVarPtr data type info

Data type: array of type MIL_TEXT_CHAR
Array size: Determined by calling M_GC_USER_NAME_SIZE.

† c o s
Collapse MIL_TEXT("CameraName") 1

Specifies the name of the camera.

 † c o s
Collapse M_GC_USER_NAME_SIZE

Inquires the length of the string returned by M_GC_USER_NAME.

(summarize)
† c o s
Collapse Value

Specifies the length of the string, including the terminating null character ("\0").

 † c o s
Collapse M_NUMBER

Retrieves the system-assigned digitizer device number associated with the camera that generated an M_CAMERA_PRESENT event.

(summarize)
† c o s
Collapse Value

Specifies the digitizer device number.

 † c o s
Collapse M_TIME_STAMP

Retrieves the operating system's time stamp at the point which the event generated a service request. The time stamp is generated by the operating system's performance counter. Time stamps can be used to see if a frame has been missed since the last time stamp.

(summarize)
† c o s
Collapse UserVarPtr data type info

Data type: MIL_DOUBLE

† c o s
Collapse Value

Specifies operating system's time stamp, in secs.

 † c o s

1 If the value was passed in a variable, it won't be returned enclosed in MIL_TEXT().

The following allows you to retrieve information about an I/O change event. The following information types are only available if MsysGetHookInfo() was called from a function hooked to an event using M_IO_CHANGE.

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 MsysHookFunction() with M_IO_CHANGE will be executed for each interrupt.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_INT.

function map For inquiring about an I/O change event
CollapseInquireType Description
MIL system-specific
tooltip (†)
UserVarPtr
- Possible values returned
Collapse M_IO_INTERRUPT_SOURCE
[This is only applicable to Matrox 4Sight GP platform]

Retrieves the input signal that triggered the hook function.

See the MIL Hardware-specific Notes for a listing of available auxiliary signals and their corresponding numbers in MIL.

(summarize)
† a e f g h
Collapse M_AUX_IOn

Specifies that auxiliary signal n triggered the hook function, where n is the number of the auxiliary signal.

 † a e f g h
Collapse M_IO_STATUS

Retrieves the state of the input signal that generated the interrupt. The returned value reflects the state of the input signal at the time of the interrupt.

(summarize)
† a e f g h
Collapse M_OFF

Specifies that the I/O signal is off.

 † a e f g h
Collapse M_ON

Specifies that the I/O signal is on.

 † a e f g h

The following allows you to retrieve information about a reference latch event. The following information types are only available if using a latch that has previously saved the time or counter value upon a hardware event and using MsysHookFunction() with any hook event.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_INT.

function map For inquiring about a reference latch value
CollapseInquireType Description
MIL system-specific
tooltip (†)
UserVarPtr
- Possible values returned
Collapse M_REFERENCE_LATCH_VALUE +
[This is only applicable to Matrox 4Sight GP platform]

Retrieves the last timestamp or counter value stored by the specified latch.

This is only available on Matrox 4Sight GPm with MIL 10 Update 26 installed.


You must specify a combination value from the following table:
(summarize)
† a
Collapse UserVarPtr data type info

Data type: MIL_INT64

† a
Collapse Value

Specifies the last timestamp or counter value stored by the specified latch.

 † a
Combination constant for M_REFERENCE_LATCH_VALUE.

You must add the following value to the above-mentioned value to specify which of the I/O command lists to use.

function map For specifying the I/O command list to use
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_IO_COMMAND_LISTn +

Specifies to inquire about I/O command list n, where n is either 1 or 2.

This is only available on Matrox 4Sight GPm with MIL 10 Update 26 installed.


You must specify a combination value from the following table:
(summarize)
† a
Combination constant for M_IO_COMMAND_LISTn.

You must add the following value to the above-mentioned value to specify which latch to inquire about.

function map For specifying the latch to inquire
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_LATCHn

Specifies to inquire about latch n, where n is a number from 0 to 4.

This is only available on Matrox 4Sight GPm with MIL 10 Update 26 installed.

(summarize)
† a
Return value
The returned value is M_NULL if successful. If the operation fails, a non-null (!M_NULL) value is returned.
Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
DEFAULT HOST GRAB TRIGGER MISSED CAMERA PRESENT FALSE TRUE GC IP ADDRESS STRING GC IP ADDRESS STRING SIZE GC MAC ADDRESS STRING GC MAC ADDRESS STRING SIZE GC UNIQUE ID STRING GC UNIQUE ID STRING SIZE GC USER NAME GC USER NAME SIZE NUMBER TIME STAMP IO INTERRUPT SOURCE AUX IOn IO STATUS OFF ON REFERENCE LATCH VALUE IO COMMAND LISTn LATCHn