| MIL 10 Reference
| Customize Help
| Save Settings

MappGetHookInfo


See also
Availability
Available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
MappGetError
MappHookFunction
Synopsis
Get information about a hooked event.
Syntax
MIL_INT MappGetHookInfo(
MIL_ID ContextAppId, //in
MIL_ID EventId, //in
MIL_INT64 InfoType, //in
void *UserVarPtr //out
)
Description

This function retrieves information about the event that caused the hook-handler function to be called. This function should only be called within the scope of an application hook-handler function call (see MappHookFunction()).

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 if there is complementary information.
Parameters
This function is not supported on the selected boards.
Parameters
ContextAppId

Specifies the identifier of the application context to use.

function map For specifying the application context
CollapseValue Description
Collapse M_DEFAULT

Specifies the current application context.
Collapse Application Context Identifier

Specifies the application context identifier.
EventId

Specifies the application event identifier received by the hook-handler function. See MappHookFunction() for more information.

InfoType

Specifies the type of information to get.

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_ID
  • MIL_INT
  • MIL_INT32
  • MIL_INT64
  • MIL_TEXT_PTR
  • a pointer of type void

Specifies the address in which to write the requested information. Note that, when getting parameter values (MappGetHookInfo() with M_PARAM_VALUE), the UserVarPtr parameter should be of the same data type as value of the selected parameter.

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

Parameter associations

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

If the hook-handler function was called due to an M_ERROR_CURRENT or M_ERROR_FATAL event type, the InfoType parameter can be set to one of the values below.

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

function map For specifying the information type (with an M_ERROR_CURRENT or M_ERROR_FATAL event type)
CollapseInfoType Description
UserVarPtr
- Possible values returned
Collapse M_CURRENT +

Retrieves the error code returned by the last function call. The current-error code is reset to M_NULL_ERROR before each MIL function call and is set to a specific error code if an error occurs while trying to execute the function.

(summarize)
Collapse M_CURRENT_SUB_1 +

Retrieves the first error subcode returned by the last function call.

Note, when there is no error, the error subcode is set to M_NULL_ERROR.

(summarize)
Collapse M_CURRENT_SUB_2 +

Retrieves the second error subcode returned by the last function call.

Note, when there is no error, the error subcode is set to M_NULL_ERROR.

(summarize)
Collapse M_CURRENT_SUB_3 +

Retrieves the third error subcode returned by the last function call.

Note, when there is no error, the error subcode is set to M_NULL_ERROR.

(summarize)
Collapse M_CURRENT_SUB_NB

Retrieves the number of error subcodes associated with the last function called, when it returns an error.

(summarize)

If the hook-handler function was called due to an M_ERROR_GLOBAL event type, the InfoType parameter can be set to one of the values below.

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

function map For specifying the information type (with an M_ERROR_GLOBAL event type)
CollapseInfoType Description
UserVarPtr
- Possible values returned
Collapse M_GLOBAL +

Retrieves the error code of the first error that has occurred since the last call to MappGetError() (with ErrorType set to M_GLOBAL). This value is reset to M_NULL_ERROR after each MappGetError() call with this setting.

(summarize)
Collapse M_GLOBAL_FCT +

Retrieves the opcode associated with the first error-generating function since the last call to MappGetError() (with ErrorType set to M_GLOBAL).

(summarize)
Collapse M_GLOBAL_SUB_1 +

Retrieves the first error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL).

Note, when there is no error, the error subcode is set to M_NULL_ERROR.

(summarize)
Collapse M_GLOBAL_SUB_2 +

Retrieves the second error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL).

Note, when there is no error, the error subcode is set to M_NULL_ERROR.

(summarize)
Collapse M_GLOBAL_SUB_3 +

Retrieves the third error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL).

Note, when there is no error, the error subcode is set to M_NULL_ERROR.

(summarize)
Collapse M_GLOBAL_SUB_NB

Retrieves the number of error subcodes associated with the first error that occurred since the last call to MappGetError() (with ErrorType set to M_GLOBAL).

(summarize)

If the hook-handler function was called due to an M_ERROR_CURRENT, M_TRACE_START, or M_TRACE_END event type, the InfoType parameter can be set to the value below.

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

function map For specifying the information type (with an M_ERROR_CURRENT, M_TRACE_START, or M_TRACE_END event type)
CollapseInfoType Description
UserVarPtr
- Possible values returned
Collapse M_CURRENT_FCT +

Retrieves the opcode associated with the last function called when it returns an error (for M_ERROR_CURRENT), just started (for M_TRACE_START), or just ended (for M_TRACE_END).

(summarize)

You can add the following value to the above-mentioned values to get the associated message instead of the numeric code.

function map For getting the associated message instead of the numeric code
CollapseInfoType Description
UserVarPtr
- Possible values returned
Collapse M_MESSAGE

Returns the error message instead of the error code, or the function name instead of the function code.

(summarize)
Collapse UserVarPtr data type info

Data type: array of type MIL_TEXT_CHAR
Array size: The array must be at least M_ERROR_MESSAGE_SIZE (320) characters in size.

If the hook-handler function was called due to an M_TRACE_START or M_TRACE_END event type, the InfoType parameter can be set to one of the values below.

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

function map For specifying the information type (with an M_TRACE_START or M_TRACE_END event type)
CollapseInfoType Description
UserVarPtr
- Possible values returned
Collapse M_PARAM_NB

Retrieves the number of parameters associated with the MIL function called.

(summarize)
Collapse M_PARAM_SIZE +

Retrieves the size, in bytes, of the specified parameter. For an array parameter, the size is: Number of items in the array X Size of the item.


You must specify a combination value from the following table:
(summarize)
Collapse M_PARAM_TYPE_INFO +

Retrieves the data type of the specified parameter of the MIL function called.


You must specify a combination value from the following table:
(summarize)
Collapse M_PARAM_TYPE_ARRAY_MIL_DOUBLE

Specifies that the parameter is an array of type MIL_DOUBLE. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_ARRAY_MIL_FLOAT

Specifies that the parameter is an array of type MIL_FLOAT. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_ARRAY_MIL_ID

Specifies that the parameter is an array of type MIL_ID. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_ARRAY_MIL_INT

Specifies that the parameter is an array of type MIL_INT. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_ARRAY_MIL_INT8

Specifies that the parameter is an array of type MIL_INT8. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_ARRAY_MIL_INT16

Specifies that the parameter is an array of type MIL_INT16. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_ARRAY_MIL_INT32

Specifies that the parameter is an array of type MIL_INT32. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_ARRAY_MIL_INT64

Specifies that the parameter is an array of type MIL_INT64. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_ARRAY_MIL_UINT

Specifies that the parameter is an array of type MIL_UINT. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_ARRAY_MIL_UINT8

Specifies that the parameter is an array of type MIL_UINT8. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_ARRAY_MIL_UINT16

Specifies that the parameter is an array of type MIL_UINT16. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_ARRAY_MIL_UINT32

Specifies that the parameter is an array of type MIL_UINT32. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_ARRAY_MIL_UINT64

Specifies that the parameter is an array of type MIL_UINT64. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_CONST_ARRAY_MIL_DOUBLE

Specifies that the parameter is a constant array of type MIL_DOUBLE. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_CONST_ARRAY_MIL_FLOAT

Specifies that the parameter is a constant array of type MIL_FLOAT. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_CONST_ARRAY_MIL_ID

Specifies that the parameter is a constant array of type MIL_ID. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_CONST_ARRAY_MIL_INT

Specifies that the parameter is a constant array of type MIL_INT. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_CONST_ARRAY_MIL_INT8

Specifies that the parameter is a constant array of type MIL_INT8. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_CONST_ARRAY_MIL_INT16

Specifies that the parameter is a constant array of type MIL_INT16. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_CONST_ARRAY_MIL_INT32

Specifies that the parameter is a constant array of type MIL_INT32. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_CONST_ARRAY_MIL_INT64

Specifies that the parameter is a constant array of type MIL_INT64. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_CONST_ARRAY_MIL_UINT

Specifies that the parameter is a constant array of type MIL_UINT. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_CONST_ARRAY_MIL_UINT8

Specifies that the parameter is a constant array of type MIL_UINT8. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_CONST_ARRAY_MIL_UINT16

Specifies that the parameter is a constant array of type MIL_UINT16. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_CONST_ARRAY_MIL_UINT32

Specifies that the parameter is a constant array of type MIL_UINT32. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_CONST_ARRAY_MIL_UINT64

Specifies that the parameter is a constant array of type MIL_UINT64. Note that the pointer to the data stored in the array is unavailable after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_CONST_DATA_PTR

Specifies that the parameter is a constant data pointer. Note that the pointer to the data is invalid after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_CONST_MIL_TEXT

Specifies that the parameter is a constant of type MIL_TEXT. This implies that the character encoding scheme of the MIL_TEXT parameter is the scheme you are currently using.

(summarize)
Collapse M_PARAM_TYPE_CONST_MIL_TEXT_ASCII

Specifies that the parameter is a constant of type MIL_TEXT_ASCII. This only appears when you are currently using a character encoding scheme other than ASCII, and the parameter you are inquiring is specifically in ASCII.

(summarize)
Collapse M_PARAM_TYPE_CONST_MIL_TEXT_UNICODE

Specifies that the parameter is a constant of type MIL_TEXT_UNICODE. This only appears when you are currently using a character encoding scheme other than unicode, and the parameter you are inquiring is specifically in unicode.

(summarize)
Collapse M_PARAM_TYPE_DATA_PTR

Specifies that the parameter is a data pointer. Note that the pointer to the data is invalid after exiting the hook-handler function. For future use, copy and save the data.

(summarize)
Collapse M_PARAM_TYPE_FILENAME

Specifies that the parameter is of type FILENAME. This implies that the character encoding scheme of the FILENAME parameter is the scheme you are currently using.

(summarize)
Collapse M_PARAM_TYPE_FILENAME_ASCII

Specifies that the parameter is of type FILENAME_ASCII. This only appears when you are currently using a character encoding scheme other than ASCII, and the parameter you are inquiring is specifically in ASCII.

(summarize)
Collapse M_PARAM_TYPE_FILENAME_UNICODE

Specifies that the parameter is of type FILENAME_UNICODE. This only appears when you are currently using a character encoding scheme other than unicode, and the parameter you are inquiring is specifically in unicode.

(summarize)
Collapse M_PARAM_TYPE_MIL_DOUBLE

Specifies that the parameter is of type MIL_DOUBLE.
Collapse M_PARAM_TYPE_MIL_FLOAT

Specifies that the parameter is of type MIL_FLOAT.
Collapse M_PARAM_TYPE_MIL_ID

Specifies that the parameter is of type MIL_ID.
Collapse M_PARAM_TYPE_MIL_INT

Specifies that the parameter is of type MIL_INT.
Collapse M_PARAM_TYPE_MIL_INT8

Specifies that the parameter is of type MIL_INT8.
Collapse M_PARAM_TYPE_MIL_INT16

Specifies that the parameter is of type MIL_INT16.
Collapse M_PARAM_TYPE_MIL_INT32

Specifies that the parameter is of type MIL_INT32.
Collapse M_PARAM_TYPE_MIL_INT64

Specifies that the parameter is of type MIL_INT64.
Collapse M_PARAM_TYPE_MIL_TEXT

Specifies that the parameter is of type MIL_TEXT. This implies that the character encoding scheme of the MIL_TEXT parameter is the scheme you are currently using.

(summarize)
Collapse M_PARAM_TYPE_MIL_TEXT_ASCII

Specifies that the parameter is of type MIL_TEXT_ASCII. This only appears when you are currently using a character encoding scheme other than ASCII, and the parameter you are inquiring is specifically in ASCII.

(summarize)
Collapse M_PARAM_TYPE_MIL_TEXT_UNICODE

Specifies that the parameter is of type MIL_TEXT_UNICODE. This only appears when you are currently using a character encoding scheme other than unicode, and the parameter you are inquiring is specifically in unicode.

(summarize)
Collapse M_PARAM_TYPE_MIL_UINT

Specifies that the parameter is of type MIL_UINT.
Collapse M_PARAM_TYPE_MIL_UINT8

Specifies that the parameter is of type MIL_UINT8.
Collapse M_PARAM_TYPE_MIL_UINT16

Specifies that the parameter is of type MIL_UINT16.
Collapse M_PARAM_TYPE_MIL_UINT32

Specifies that the parameter is of type MIL_UINT32.
Collapse M_PARAM_TYPE_MIL_UINT64

Specifies that the parameter is of type MIL_UINT64.
Collapse M_PARAM_VALUE +

Retrieves the value of the specified parameter of the MIL function called.


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

You must add the following value to the above-mentioned values to determine the number of the parameter for which to receive the information.

function map For specifying the parameter
CollapseCombination value Description
Collapse Value >= 1

Specifies the number of the parameter for which to retrieve the information. This value must be a positive integer, and should not exceed the number of parameters associated with the MIL function call (M_PARAM_NB).

(summarize)
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 CURRENT CURRENT SUB 1 CURRENT SUB 2 CURRENT SUB 3 CURRENT SUB NB GLOBAL GLOBAL FCT GLOBAL SUB 1 GLOBAL SUB 2 GLOBAL SUB 3 GLOBAL SUB NB CURRENT FCT MESSAGE PARAM NB PARAM SIZE PARAM TYPE INFO PARAM TYPE ARRAY MIL DOUBLE PARAM TYPE ARRAY MIL FLOAT PARAM TYPE ARRAY MIL ID PARAM TYPE ARRAY MIL INT PARAM TYPE ARRAY MIL INT8 PARAM TYPE ARRAY MIL INT16 PARAM TYPE ARRAY MIL INT32 PARAM TYPE ARRAY MIL INT64 PARAM TYPE ARRAY MIL UINT PARAM TYPE ARRAY MIL UINT8 PARAM TYPE ARRAY MIL UINT16 PARAM TYPE ARRAY MIL UINT32 PARAM TYPE ARRAY MIL UINT64 PARAM TYPE CONST ARRAY MIL DOUBLE PARAM TYPE CONST ARRAY MIL FLOAT PARAM TYPE CONST ARRAY MIL ID PARAM TYPE CONST ARRAY MIL INT PARAM TYPE CONST ARRAY MIL INT8 PARAM TYPE CONST ARRAY MIL INT16 PARAM TYPE CONST ARRAY MIL INT32 PARAM TYPE CONST ARRAY MIL INT64 PARAM TYPE CONST ARRAY MIL UINT PARAM TYPE CONST ARRAY MIL UINT8 PARAM TYPE CONST ARRAY MIL UINT16 PARAM TYPE CONST ARRAY MIL UINT32 PARAM TYPE CONST ARRAY MIL UINT64 PARAM TYPE CONST DATA PTR PARAM TYPE CONST MIL TEXT PARAM TYPE CONST MIL TEXT ASCII PARAM TYPE CONST MIL TEXT UNICODE PARAM TYPE DATA PTR PARAM TYPE FILENAME PARAM TYPE FILENAME ASCII PARAM TYPE FILENAME UNICODE PARAM TYPE MIL DOUBLE PARAM TYPE MIL FLOAT PARAM TYPE MIL ID PARAM TYPE MIL INT PARAM TYPE MIL INT8 PARAM TYPE MIL INT16 PARAM TYPE MIL INT32 PARAM TYPE MIL INT64 PARAM TYPE MIL TEXT PARAM TYPE MIL TEXT ASCII PARAM TYPE MIL TEXT UNICODE PARAM TYPE MIL UINT PARAM TYPE MIL UINT8 PARAM TYPE MIL UINT16 PARAM TYPE MIL UINT32 PARAM TYPE MIL UINT64 PARAM VALUE