| Customize Help
| Save Settings

MsysGetHookInfo


Function Map
Syntax
Description
Parameters
- SysId
Table: For the system identifier
- EventId
- InquireType
- UserVarPtr
Parameter Associations
Table: For retrieving information about a camera-specific event
+ combination: For identifying the instance of the GenTL library to use
Table: For retrieving information about a timer start or timer end event
+ combination: For specifying the timer to inquire about
Table: For retrieving information about an I/O change event
Table: For retrieving information about a data latch value
+ combination: For specifying the I/O command list to use
+ combination: For specifying the latch to inquire
Table: For retrieving information from a GenTL feature change event
+ combination: For getting the string size
Return value
Compilation information
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
Click to summarizeValue Description MIL system-specific
tooltip (‡)
Click to summarize M_DEFAULT_HOST

Specifies the default Host system of the current MIL application.

 ‡ a c
M10		 g h o t
U28		 u
U36		 v
Click to summarize MIL system identifier

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

 ‡ a c
M10		 g h o t
U28		 u
U36		 v w
U53		 z
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 [optionally, in C++: a reference to a MIL_STRING]
  • MIL_DOUBLE
  • MIL_INT
  • MIL_INT64
  • MIL_UINT64

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 a camera-specific event. The following information types are only available if MsysGetHookInfo() was called from a function hooked to a system event using MsysHookFunction() with M_CAMERA_PRESENT.

function map For retrieving information about a camera-specific event
Click to summarizeInquireType Description MIL system-specific
tooltip (‡)
UserVarPtr
- Possible values returned
Click to summarize M_CAMERA_PRESENT

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

(summarize)
‡ a c
M10		 o t
U28		 u
U36
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: address of a MIL_INT
 ‡ a c
M10		 o t
U28		 u
U36
Click to summarize M_FALSE

Specifies that a camera has been removed from the system.

 ‡ a c
M10		 o t
U28		 u
U36
Click to summarize M_TRUE

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

 ‡ a c
M10		 o t
U28		 u
U36
Click to summarize M_GC_REMOTE_IP_ADDRESS_STRING +

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

(summarize)
‡ c
M10
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: array of type MIL_TEXT_CHAR [optionally, in C++: MIL_STRING ] MORE
 ‡ c
M10
Click to summarize 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
M10
Click to summarize M_GC_REMOTE_MAC_ADDRESS_STRING +

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

(summarize)
‡ c
M10
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: array of type MIL_TEXT_CHAR [optionally, in C++: MIL_STRING ] MORE
 ‡ c
M10
Click to summarize 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
M10
Click to summarize M_GC_UNIQUE_ID_STRING +

Retrieves the unique identifier for your camera.

(summarize)
‡ a c
M10		 o t
U28
MIL system specific

This is the camera's MAC address.

 ‡ c
M10

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

 ‡ o
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: array of type MIL_TEXT_CHAR [optionally, in C++: MIL_STRING ] MORE
 ‡ a c
M10		 o t
U28
Click to summarize MIL_TEXT("nnnnnnnnnnnn") 1

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

(summarize)
‡ a c
M10		 o t
U28
Click to summarize M_GC_USER_NAME

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

(summarize)
‡ a c
M10		 o t
U28
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: array of type MIL_TEXT_CHAR [optionally, in C++: MIL_STRING ] MORE
 ‡ a c
M10		 o t
U28
Click to summarize MIL_TEXT("CameraName") 1

Specifies the name of the camera.

 ‡ a c
M10		 o t
U28
Click to summarize M_NUMBER

Retrieves the device number of the digitizer to which a camera has been connected or disconnected from, causing an M_CAMERA_PRESENT event. SET

(summarize)
‡ a c
M10		 o t
U28		 u
U36		 v
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: address of a MIL_INT
 ‡ a c
M10		 o t
U28		 u
U36		 v
Click to summarize M_DEVn +

Specifies the device number (rank) of the board. INFO

(summarize)
‡ a c
M10		 o t
U28		 u
U36		 v
MIL system specific

This value is combined with a value from the following table:
‡ v
Click to summarize 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)
‡ a c
M10		 o t
U28		 v w
U53		 z
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: address of a MIL_DOUBLE
 ‡ a c
M10		 o t
U28		 v w
U53		 z
Click to summarize Value

Specifies operating system's time stamp, in sec.

 ‡ a c
M10		 o t
U28		 v w
U53		 z

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

Combination value for M_DEVn (when InquireType=M_NUMBER and UserVarPtr=M_DEVn).

The following value is combined with the above-mentioned value to identifythe GenTL library for which a MIL GenTL system was allocated.

All third-party proprietary GenTL libraries installed on your computer are sorted and indexed by MIL. Use the GenTL Producer index number to identify the library that your MIL system should use to communicate with the hardware devices on the specified transportation layer. These libraries are indexed and sorted for reference by MIL (the GenTL Consumer). In all cases, the same number and type of libraries should be installed on every computer that will run your application; the order in which they are installed, however, is not important.

To determine the number of GenTL libraries installed on your computer, use MappInquire() with M_GENTL_PRODUCER_COUNT or use the General Default Values page of the MILConfig utility.

function map For identifying the instance of the GenTL library to use
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize

Specifies the GenTL Producer (library) for which this MIL GenTL system was allocated.

(summarize)
‡ v
Parameters

Specifies the index of the GenTL Producer.

 ‡ v
0 <= Value <= 127

Specifies the index.
‡ v

The following allows you to retrieve information about a timer event. The following information types are only available if MsysGetHookInfo() was called from a function hooked to an event using M_TIMER_START or M_TIMER_END.

function map For retrieving information about a timer start or timer end event
Click to summarizeInquireType Description MIL system-specific
tooltip (‡)
UserVarPtr
- Possible values returned
Click to summarize M_TIMER_INDEX

Retrieves the index value of the timer that generated an M_TIMER_END or an M_TIMER_START event.

[Matrox 4Sight GP/GPm]

On a Matrox 4Sight GPm computer, this value is only available if MIL 10 update 51 (or later) is installed. It is not available on Matrox 4Sight GP.

(summarize)
‡ a t
U28		 w
U53		 z
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: address of a MIL_INT
 ‡ a t
U28		 w
U53		 z
Click to summarize Value

Specifies the value of the index of the timer.

 ‡ a t
U28		 w
U53		 z
Click to summarize M_TIMER_VALUE +

Retrieves the value of the specified timer.

This is typically used with a timer end event (set using MsysHookFunction() with M_TIMER_END). Note that, if used with a timer start event (M_TIMER_START), it will return 0.

To inquire the value of the timer that caused the event, use M_TIMER_INDEX to learn which timer to inquire.

[Matrox 4Sight GP/GPm]

On a Matrox 4Sight GPm computer, this value is only available if MIL 10 update 51 (or later) is installed. It is not available on Matrox 4Sight GP.

(summarize)
‡ a t
U28		 w
U53		 z
MIL system specific

You must specify a combination value from the following table:
‡ t
U28
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: address of a MIL_DOUBLE
 ‡ a t
U28		 w
U53		 z
Click to summarize Value

Specifies the current value of the timer, in nsec.

 ‡ a t
U28		 w
U53		 z
Combination value for M_TIMER_VALUE.

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

function map For specifying the timer to inquire about
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize M_TIMERn

Specifies the timer to inquire about.

 ‡ t
U28

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.

function map For retrieving information about an I/O change event
Click to summarizeInquireType Description MIL system-specific
tooltip (‡)
UserVarPtr
- Possible values returned
Click to summarize M_IO_INTERRUPT_SOURCE

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 g h t
U28		 w
U53		 z
MIL system specific
[This is only applicable to Matrox 4Sight GP/GPm platform]

This constant is only available on a Host system if the Host system has been allocated on a Matrox 4Sight GPm.

 ‡ a w
U53		 z
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: address of a MIL_INT
 ‡ a g h t
U28		 w
U53		 z
Click to summarize M_AUX_IOn

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

 ‡ a g h t
U28		 w
U53		 z
Click to summarize 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 g h t
U28		 w
U53		 z
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: address of a MIL_INT
 ‡ a g h t
U28		 w
U53		 z
Click to summarize M_OFF

Specifies that the I/O signal is off.

 ‡ a g h t
U28		 w
U53		 z
Click to summarize M_ON

Specifies that the I/O signal is on.

 ‡ a g h t
U28		 w
U53		 z

The following allows you to retrieve information about a data latch event. The following information types are only available if using a latch that has previously saved the time, I/O command list counter, or rotary decoder position counter value upon a hardware event.

function map For retrieving information about a data latch value
Click to summarizeInquireType Description MIL system-specific
tooltip (‡)
UserVarPtr
- Possible values returned
Click to summarize M_REFERENCE_LATCH_VALUE +

Retrieves the last timestamp or counter value stored by the specified latch, associated with the specified I/O command list.

This setting is available in functions hooked to any type of event.


You must specify a combination value from the following table:
(summarize)
‡ a t
U28		 w
U53		 z
MIL system specific
[This is only applicable to Matrox 4Sight GP/GPm platform]

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

This is only available on Matrox 4Sight EV6 with MIL 10 Update 86 (or later) installed.

 ‡ a
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: address of a MIL_INT64
 ‡ a t
U28		 w
U53		 z
Click to summarize Value

Specifies the last timestamp or counter value stored by the specified latch, associated with the specified command list.

 ‡ a t
U28		 w
U53		 z
Click to summarize M_SYS_DATA_LATCH_VALUE +

Retrieves the last rotary decoder position counter value stored by the specified latch, associated with the rotary decoders of the system.

This setting is only available if MsysGetHookInfo() was called from a function hooked to an event using M_TIMER_START, M_TIMER_END, or M_IO_CHANGE.

[Matrox 4Sight GP/GPm]

This is only available on Matrox 4Sight GPm and EV6 with MIL 10 Update 86 (or later) installed.


You must specify a combination value from the following table:
(summarize)
‡ a
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: address of a MIL_UINT64
 ‡ a
Click to summarize Value

Specifies the last rotary decoder position counter value stored by the specified latch, associated with the rotary decoders of the system.

 ‡ a
Combination value 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
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize M_IO_COMMAND_LISTn +

Specifies to inquire about I/O command list n.


You must specify a combination value from the following table:
(summarize)
‡ a t
U28		 w
U53		 z
MIL system specific
[This is only applicable to Matrox 4Sight GP/GPm platform]

For Matrox 4Sight GPm and EV6 n is a number from 1 to 2.

 ‡ a

For Matrox Indio and Matrox Concord POE n is a number from 1 to 2.

 ‡ w
U53		 z

For Matrox Iris GTR, n must be 1.

 ‡ t
U28
Combination value for M_IO_COMMAND_LISTn; M_SYS_DATA_LATCH_VALUE.

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

function map For specifying the latch to inquire
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize M_LATCHn

Specifies to inquire about latch n.

(summarize)
‡ a t
U28		 w
U53		 z
MIL system specific
[This is only applicable to Matrox 4Sight GP/GPm platform]

For Matrox 4Sight GPm and EV6, n is a number from 1 to 4, unless used with M_SYS_DATA_LATCH_VALUE (in which case, n is a number from 1 to 2).

 ‡ a

For Matrox Indio, n is a number from 1 to 4.

 ‡ w
U53

For Matrox Iris GTR, n is a number from 1 to 2.

 ‡ t
U28

The following allows you to retrieve information from a GenTL feature change event. These information types are only available if MsysGetHookInfo() was called from a function hooked to GenICam feature change event using MsysHookFunction() with M_FEATURE_CHANGE.

function map For retrieving information from a GenTL feature change event
Click to summarizeInquireType Description MIL system-specific
tooltip (‡)
UserVarPtr
- Possible values returned
Click to summarize M_GC_FEATURE_CHANGE_NAME +

Retrieves the name of the GenTL feature that changed.

(summarize)
‡ v
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: array of type MIL_TEXT_CHAR [optionally, in C++: MIL_STRING ] MORE
 ‡ v
Click to summarize Value

Specifies the feature name.

 ‡ v
Combination value for M_GC_FEATURE_CHANGE_NAME; M_GC_REMOTE_IP_ADDRESS_STRING; M_GC_REMOTE_MAC_ADDRESS_STRING; M_GC_UNIQUE_ID_STRING.

You can add the following value to the above-mentioned values to get the string's length.

function map For getting the string size
Click to summarizeInquireType Description MIL system-specific
tooltip (‡)
UserVarPtr
- Possible values returned
Click to summarize M_STRING_SIZE

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

(summarize)
‡ a c
M10		 o t
U28		 v
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: address of a MIL_INT
 ‡ a c
M10		 o t
U28		 v
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 CAMERA PRESENT FALSE TRUE GC REMOTE IP ADDRESS STRING GC REMOTE MAC ADDRESS STRING GC UNIQUE ID STRING GC USER NAME NUMBER DEVn TIME STAMP TIMER INDEX TIMER VALUE TIMERn IO INTERRUPT SOURCE AUX IOn IO STATUS OFF ON REFERENCE LATCH VALUE SYS DATA LATCH VALUE IO COMMAND LISTn LATCHn GC FEATURE CHANGE NAME STRING SIZE M_DEVn M_TIMERn M_AUX_IOn M_IO_COMMAND_LISTn M_LATCHn