MsysGetHookInfo

Filters
See also

User Guide:

DirectShow capture filter for MIL Event handling in MIL with hook-handler functions Using I/O command lists Using input signals

Reference:

MdigInquire MsysAlloc MsysHookFunction

Availability

Available in MIL-Lite

Available in MIL

Available on Windows

Available on Linux

Not supported on:

Not supported on Matrox CronosPlus (b)

Not supported on Matrox GPU processing driver (d)

Not supported on Matrox Orion HD (i)

Not supported on Matrox Radient eCL (j)

Not supported on Matrox Radient eV-CXP (k)

Not supported on Matrox Solios eA/XA (l)

Not supported on Matrox Solios ecl/xcl/ev-cl (m)

Not supported on Matrox Vio (n)

Not supported on Matrox RadientPro-CL (requires Update 7) (p)

Not supported on Matrox Radient eV-CLHS (requires Update 21) (q)

Not supported on Matrox Radient eV-CL (requires Update 27) (r)

Partially supported on:

Partially supported on Host system (a)

Partially supported on Matrox GigE Vision driver (c)

Partially supported on Matrox IEEE 1394 IIDC driver (e)

Partially supported on Matrox Iris GT (f)

Partially supported on Matrox Morphis (g)

Partially supported on Matrox Morphis QxT (h)

Partially supported on Matrox USB3 Vision driver (requires Update 19) (o)

Partially supported on Matrox GigE Vision driver (requires Update 25) (s)

Partially supported on Matrox Iris GTR (requires Update 28) (t)

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/GPm

Function map

Examples

msysio.cpp
multicamera.cpp

Function Map

- SysId

Table:

For the system identifier

- EventId

- InquireType

- UserVarPtr

Parameter Associations

Table:	For retrieving information about a general system hook event
Table:	For retrieving information about a camera-specific event
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 reference latch value
+ combination:	For specifying the I/O command list to use
+ combination:	For specifying the latch to inquire

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.

For the system identifier
Value	Description	MIL system-specific tooltip (‡)
M_DEFAULT_HOST	Specifies the default Host system of the current MIL application.	‡	a	c	e	f	g	h	o	s	t
MIL system identifier	Specifies a valid system identifier, previously allocated using MsysAlloc().	‡	a	c	e	f	g	h	o	s	t

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.

For retrieving information about a general system hook event
For retrieving information about a camera-specific event
For retrieving information about a timer start or timer end event
For retrieving information about an I/O change event
For retrieving information about a reference latch value

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().

For retrieving information about a general system hook event
InquireType		Description	MIL system-specific tooltip (‡)
	UserVarPtr - Possible values returned	Description
M_GRAB_TRIGGER_MISSED		Retrieves the number of missed triggers occurring on timer 2. (summarize) Retrieves the number of missed triggers occurring on timer 2. (more details...)				‡	f	t
	UserVarPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT	‡	f	t
	Value	Specifies the number of missed triggers.	‡	f	t

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.

For retrieving information about a camera-specific event
InquireType		Description		MIL system-specific tooltip (‡)
	UserVarPtr - Possible values returned	Description
M_CAMERA_PRESENT		Retrieves whether a camera has been added or re-connected to the system. (summarize) Retrieves whether a camera has been added or re-connected to the system. (more details...)								‡	a	c	o	s	t
	UserVarPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT		‡	a	c	o	s	t
	M_FALSE	Specifies that a camera has been added or re-connected to the system.		‡	a	c	o	s	t
	M_TRUE	Specifies that a camera has been removed from the system.		‡	a	c	o	s	t
M_GC_IP_ADDRESS_STRING		Retrieves the IP address (IPv4) of the camera that generated the M_CAMERA_PRESENT event. (summarize) Retrieves the IP address (IPv4) of the camera that generated the M_CAMERA_PRESENT event. (more details...)		‡		c		s
	UserVarPtr extra info	Data type info: Data type: array of type MIL_TEXT_CHAR (more details...) Data type: array of type MIL_TEXT_CHAR Required array size: MsysGetHookInfo() with M_GC_IP_ADDRESS_STRING_SIZE Data type info: Data type: array of type MIL_TEXT_CHAR (more details...) Data type: array of type MIL_TEXT_CHAR Required array size: MsysGetHookInfo() with M_GC_IP_ADDRESS_STRING_SIZE		‡		c		s
	MIL_TEXT("nnn.nnn.nnn.nnn") ¹	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) Specifies the IP address of the camera as a string. (more details...)		‡		c		s
M_GC_IP_ADDRESS_STRING_SIZE		Inquires the length of the string returned by M_GC_IP_ADDRESS_STRING. (summarize) Inquires the length of the string returned by M_GC_IP_ADDRESS_STRING. (more details...)		‡		c		s
	UserVarPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT		‡		c		s
	Value	Specifies the length of the string, including the terminating null character ("\0").		‡		c		s
M_GC_MAC_ADDRESS_STRING		Retrieves the MAC address of the camera that generated the M_CAMERA_PRESENT event. (summarize) Retrieves the MAC address of the camera that generated the M_CAMERA_PRESENT event. (more details...)		‡		c		s
	UserVarPtr extra info	Data type info: Data type: array of type MIL_TEXT_CHAR (more details...) Data type: array of type MIL_TEXT_CHAR Required array size: MsysGetHookInfo() with M_GC_MAC_ADDRESS_STRING_SIZE Data type info: Data type: array of type MIL_TEXT_CHAR (more details...) Data type: array of type MIL_TEXT_CHAR Required array size: MsysGetHookInfo() with M_GC_MAC_ADDRESS_STRING_SIZE		‡		c		s
	MIL_TEXT("nn-nn-nn-nn-nn-nn") ¹	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) Specifies the MAC address of the camera, as a string. (more details...)		‡		c		s
M_GC_MAC_ADDRESS_STRING_SIZE		Inquires the length of the string returned by M_GC_MAC_ADDRESS_STRING. (summarize) Inquires the length of the string returned by M_GC_MAC_ADDRESS_STRING. (more details...)		‡		c		s
	UserVarPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT		‡		c		s
	Value	Specifies the length of the string, including the terminating null character ("\0").		‡		c		s
M_GC_UNIQUE_ID_STRING		Inquires the unique identifier for your camera. (summarize) Inquires the unique identifier for your camera. (more details...)		‡	a	c	o	s	t
			MIL system specific
			This is the camera's MAC address.	‡		c		s
			This is the camera's global unique identifier (GUID).	‡			o
	UserVarPtr extra info	Data type info: Data type: array of type MIL_TEXT_CHAR (more details...) Data type: array of type MIL_TEXT_CHAR Required array size: MsysGetHookInfo() with M_GC_UNIQUE_ID_STRING_SIZE Data type info: Data type: array of type MIL_TEXT_CHAR (more details...) Data type: array of type MIL_TEXT_CHAR Required array size: MsysGetHookInfo() with M_GC_UNIQUE_ID_STRING_SIZE		‡	a	c	o	s	t
	MIL_TEXT("nnnnnnnnnnnn") ¹	Specifies the unique identifier, as a string. The string is expressed in hexadecimal. (summarize) Specifies the unique identifier, as a string. (more details...)		‡	a	c	o	s	t
M_GC_UNIQUE_ID_STRING_SIZE		Inquires the size of the string containing the unique identifier for your camera. (summarize) Inquires the size of the string containing the unique identifier for your camera. (more details...)		‡	a	c	o	s	t
	UserVarPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT		‡	a	c	o	s	t
	Value	Specifies the number of characters in the string.		‡	a	c	o	s	t
M_GC_USER_NAME		Retrieves the user-defined name of the camera that generated the M_CAMERA_PRESENT event. (summarize) Retrieves the user-defined name of the camera that generated the M_CAMERA_PRESENT event. (more details...)		‡	a	c	o	s	t
	UserVarPtr extra info	Data type info: Data type: array of type MIL_TEXT_CHAR (more details...) Data type: array of type MIL_TEXT_CHAR Required array size: MsysGetHookInfo() with M_GC_USER_NAME_SIZE Data type info: Data type: array of type MIL_TEXT_CHAR (more details...) Data type: array of type MIL_TEXT_CHAR Required array size: MsysGetHookInfo() with M_GC_USER_NAME_SIZE		‡	a	c	o	s	t
	MIL_TEXT("CameraName") ¹	Specifies the name of the camera.		‡	a	c	o	s	t
M_GC_USER_NAME_SIZE		Inquires the length of the string returned by M_GC_USER_NAME. (summarize) Inquires the length of the string returned by M_GC_USER_NAME. (more details...)		‡	a	c	o	s	t
	UserVarPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT		‡	a	c	o	s	t
	Value	Specifies the length of the string, including the terminating null character ("\0").		‡	a	c	o	s	t
M_NUMBER		Retrieves the system-assigned digitizer device number associated with the camera that generated an M_CAMERA_PRESENT event. (summarize) Retrieves the system-assigned digitizer device number associated with the camera that generated an M_CAMERA_PRESENT event. (more details...)		‡	a	c	o	s	t
	UserVarPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT		‡	a	c	o	s	t
	Value	Specifies the digitizer device number.		‡	a	c	o	s	t
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) Retrieves the operating system's time stamp at the point which the event generated a service request. (more details...)		‡	a	c	o	s	t
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE		‡	a	c	o	s	t
	Value	Specifies operating system's time stamp, in secs.		‡	a	c	o	s	t

¹ 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 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.

For retrieving information about a timer start or timer end event
InquireType		Description	MIL system-specific tooltip (‡)
	UserVarPtr - Possible values returned	Description
M_TIMER_INDEX		Retrieves the index value of the timer that generated an M_TIMER_END or an M_TIMER_START event. (summarize) Retrieves the index value of the timer that generated an M_TIMER_END or an M_TIMER_START event. (more details...)			‡	t
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE	‡	t
	Value	Specifies the value of the index of the timer.	‡	t
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. You must specify a combination value from the following table: To specify the timer to inquire about (summarize) Retrieves the value of the specified timer. (more details...)	‡	t
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE	‡	t
	Value	Specifies the current value of the timer, in nsecs.	‡	t

Combination value for M_TIMER_VALUE.

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

For specifying the timer to inquire about
Combination value	Description	MIL system-specific tooltip (‡)
M_TIMERn	Specifies the timer to inquire about.	‡	t

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.

For retrieving information about an I/O change event
InquireType		Description		MIL system-specific tooltip (‡)
	UserVarPtr - Possible values returned	Description
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) Retrieves the input signal that triggered the hook function. (more details...)									‡	a	e	f	g	h	t
			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
	UserVarPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT		‡	a	e	f	g	h	t
	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	t
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) Retrieves the state of the input signal that generated the interrupt. (more details...)		‡	a	e	f	g	h	t
	UserVarPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT		‡	a	e	f	g	h	t
	M_OFF	Specifies that the I/O signal is off.		‡	a	e	f	g	h	t
	M_ON	Specifies that the I/O signal is on.		‡	a	e	f	g	h	t

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.

For retrieving information about a reference latch value
InquireType		Description		MIL system-specific tooltip (‡)
	UserVarPtr - Possible values returned	Description
M_REFERENCE_LATCH_VALUE +		Retrieves the last timestamp or counter value stored by the specified latch. You must specify a combination value from the following table: To specify which of the I/O command lists to use (summarize) Retrieves the last timestamp or counter value stored by the specified latch. (more details...)					‡	a	t
			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 installed.	‡	a
	UserVarPtr extra info	Data type info: Data type: address of a MIL_INT64 Data type info: Data type: address of a MIL_INT64		‡	a	t
	Value	Specifies the last timestamp or counter value stored by the specified latch.		‡	a	t

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.

For specifying the I/O command list to use
Combination value	Description		MIL system-specific tooltip (‡)
M_IO_COMMAND_LISTn +	Specifies to inquire about I/O command list n. You must specify a combination value from the following table: To specify which latch to inquire about (summarize) Specifies to inquire about I/O command list n. (more details...)		‡	a	t
		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 installed. For Matrox 4Sight GPm n is a number from 1 to 2.	‡	a
		For Matrox Iris GTR, n must be 1.	‡		t

Combination value for M_IO_COMMAND_LISTn.

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

For specifying the latch to inquire
Combination value	Description		MIL system-specific tooltip (‡)
M_LATCHn	Specifies to inquire about latch n. (summarize) Specifies to inquire about latch n. (more details...)		‡	a	t
		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 installed. For Matrox 4Sight GPm, n is a number from 0 to 4.	‡	a
		For Matrox Iris GTR, n is a number from 1 to 2.	‡		t

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.