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.
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
For operation MONITOR_CONTROL_SET_EVENT_TRIGGERS, the following kinds of monitoring events cannot be associated with triggers:
- MF_EVENT_KIND_RESERVED (Reserved)
- MF_EVENT_KIND_BUGCHECK_RTSS_RESERVED (Bugcheck RTSS)
- MF_EVENT_KIND_MARKER (Marker)
- MF_EVENT_KIND_SUBSYSTEM_STOP (Subsystem Stop)
- MF_EVENT_KIND_FAST_SEMAPHORE_ACQUIRE (Fast Semaphore Acquire)
- MF_EVENT_KIND_FAST_SEMAPHORE_RELEASE (Fast Semaphore Release)
- MF_EVENT_KIND_FAST_SEMAPHORE_RELEASE_ALL (Fast Semaphore Release All)
- MF_EVENT_KIND_WFSOEX_WAIT (WaitForSingleObjectEx Wait)
- MF_EVENT_KIND_WFMOEX_WAIT (WaitForMultipleObjectEx Wait)
- MF_EVENT_KIND_THREAD_SLEEP (Thread Sleep)
Attempts to associate one of the above event kinds with a trigger will cause RtMonitorControl to fail with ERROR_INVALID_PARAMETER.
Requirements
Minimum Supported Version |
RTX64 2014 |
Header |
Rtapi.h |
Library | Rtx_Rtss.lib |
See Also: