QueryTraceW function (evntrace.h)

The QueryTrace function retrieves the property settings and session statistics for the specified event tracing session.

This function is obsolete. The ControlTrace function supersedes this function.

Syntax

ULONG WMIAPI QueryTraceW(
  CONTROLTRACE_ID         TraceId,
  LPCWSTR                 InstanceName,
  PEVENT_TRACE_PROPERTIES Properties
);

Parameters

TraceId

InstanceName

Name of the event tracing session to be queried, or NULL. You must specify InstanceName if TraceHandle is 0.

To specify the NT Kernel Logger session, set InstanceName to KERNEL_LOGGER_NAME.

Properties

Pointer to an initialized EVENT_TRACE_PROPERTIES structure.

You only need to set the Wnode.BufferSize member of the EVENT_TRACE_PROPERTIES structure. You can use the maximum session name (1024 characters) and maximum log file name (1024 characters) lengths to calculate the buffer size and offsets if not known.

On output, the structure members contain the property settings and session statistics for the event tracing session.

Starting with Windows 10, version 1703: For better performance in cross process scenarios, you can now pass filtering into QueryTrace for system wide private loggers. You will need to pass in the new EVENT_TRACE_PROPERTIES_V2 structure to include filtering information. See Configuring and Starting a Private Logger Session for more details.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the system error codes. The following are some common errors and their causes.

• ERROR_BAD_LENGTH

  One of the following is true:

  • The Wnode.BufferSize member of Properties specifies an incorrect size.
  • Properties does not have sufficient space allocated to hold a copy of the session name and log file name (if used).

• ERROR_INVALID_PARAMETER

  One of the following is true:

  • Properties is NULL.
  • InstanceName and TraceHandle are both NULL.
  • InstanceName is NULL and TraceHandle is not a valid handle.

• ERROR_ACCESS_DENIED

  Only users running with elevated administrative privileges, users in the Performance Log Users group, and services running as LocalSystem, LocalService, NetworkService can query event tracing sessions. To grant a restricted user the ability to query trace sessions, add them to the Performance Log Users group or see EventAccessControl.

  Windows XP and Windows 2000: Anyone can control a trace session.

• ERROR_WMI_INSTANCE_NOT_FOUND

  The given session is not running.

Remarks

Event trace controllers call this function.

This function is obsolete. Instead, use ControlTrace with ControlCode set to EVENT_TRACE_CONTROL_QUERY.

Requirements

See also

ControlTrace

QueryAllTraces