RtMonitorControl

RtMonitorControl performs various monitoring control operations, such as starting and stopping and configuring events to collect.

Syntax

BOOL RtMonitorControl(
    RTX64_MONITOR_CONTROL_OP operation,
    void * data,
    size_t size
);

Parameters

operation

Specifies which RTX64_MONITOR_CONTROL_OP control operation to perform.

data

Points to a data buffer that provides information necessary to complete the request operation. This pointer can be NULL if the operation requested requires no additional information. See the Remarks section for information on what data needs to be provided.

size

The size (in bytes) of the data buffer pointed to by parameter data. If no data was necessary to complete the requested operation, size should be set to 0.

Return Value

The return value is TRUE if successful, FALSE otherwise. If RtMonitorControl fails, call GetLastError to obtain the error code. See Error Codes for error descriptions.

Remarks

You can also control monitoring through the Managed Code Framework.

If you do not want to control monitoring programmatically, you can use the Monitor utility.

Enabling monitoring with this API causes CPU and disk I/O overhead. You can eliminate this overhead by programmatically stopping or disabling monitoring with this API or with RtMonitorChangeState.

RtMonitorControl uses the enumeration RTX64_MONITOR_CONTROL_OP to specify the operation to perform. Note that this API is not thread-safe. Therefore, the client is responsible for serializing calls to this API across different threads and processes.

Starting a monitoring session with MONITOR_CONTROL_START requires monitoring to already be enabled in the Control Panel. If monitoring is not enabled or started, the call will fail.

Stopping a monitoring session with MONITOR_CONTROL_STOP requires monitoring to be enabled in the Control Panel. If monitoring is not enabled and started this function will fail.

To enable monitor events using MONITOR_CONTROL_ENABLE_EVENTS, you must use the data parameter to provide information on which events to enable. The data parameter should point to a BOOLEAN array that is MF_EVENT_KIND_MAX elements long, where an event kind enumerator is used as an index into the array. If monitoring is not enabled, this operation fails with error ERROR_NOT_READY.

To enable an event, set it to TRUE, and pass MONITOR_CONTROL_ENABLE_EVENTS to RtMonitorControl. To query the status of what events are enabled, pass in an array where all elements are set to FALSE. For example, if you wanted to enable Thread Creation events you would:

	// Create an array set all elements to FALSE
	BOOLEAN data [MF_EVENT_KIND_MAX] = {FALSE};

	// Set elements you want to enable to TRUE
	data [MF_EVENT_KIND_THREAD_CREATE] = TRUE;

	// Call API to enable set elements in the array 
	RtMonitorControl (MONITOR_CONTROL_ENABLE_EVENTS, data, sizeof(data));

See the MF_EVENT_KIND enumeration for information on the monitor events available to enable.

To disable monitor events using MONITOR_CONTROL_DISABLE _EVENTS you must use the data parameter to provide information on which events to disable. The data parameter should point to a BOOLEAN array that is MF_EVENT_KIND_MAX elements long, where an event kind enumerator is used as an index into the array. If monitoring is not enabled, this operation fails with error ERROR_NOT_READY.

To disable an event, set it to TRUE, and pass MONITOR_CONTROL_DISABLE_EVENTS to RtMonitorControl. To query the status of what events are disabled, pass in an array where all elements are set to FALSE. For example, if you wanted to disable Thread Creation events you would:

	// Create an array set all elements to FALSE 
	BOOLEAN data [MF_EVENT_KIND_MAX] = {FALSE};

	// Set elements you want to disable to TRUE 
	data [MF_EVENT_KIND_THREAD_CREATE] = FALSE;

	// Call API to disable events corresponding to elements in the array that are TRUE
	RtMonitorControl (MONITOR_CONTROL_DISABLE_EVENTS, data, sizeof(data));

See the MF_EVENT_KIND enumeration for information on the monitor events available to disable.

Generation of Data Lost events cannot be disabled. RtMonitorControl returns False with error code ERROR_INVALID_PARAMETER when used in an attempt to disable Data Lost events

Requirements

Minimum Supported Version	RTX64 3.4 (availability from RTSS and Windows applications) RTX64 2014 (availability from RTSS applications only)
Header	Rtapi.h
Library	Rtx_Rtss.lib (RTSS), RtApi.h (Windows)

See Also:

RtGenerateEvent

RTX64_MONITOR_CONTROL_OP

MF_EVENT_KIND