EnableTraceEx2 function

Enables or disables the specified event trace provider.

This function supersedes the EnableTraceEx function.

Syntax

ULONG EnableTraceEx2(
  _In_      TRACEHANDLE TraceHandle,
  _In_      LPCGUID ProviderId,
  _In_      ULONG ControlCode,
  _In_      UCHAR Level,
  _In_      ULONGLONG MatchAnyKeyword,
  _In_      ULONGLONG MatchAllKeyword,
  _In_      ULONG Timeout,
  _In_opt_  PENABLE_TRACE_PARAMETERS EnableParameters
);

Parameters

TraceHandle [in]

Handle of the event tracing session to which you want to enable or disable the provider. The StartTrace function returns this handle.

ProviderId [in]

GUID of the event trace provider that you want to enable or disable.

ControlCode [in]

You can specify one of the following control codes:

Value	Meaning
EVENT_CONTROL_CODE_DISABLE_PROVIDER	Disables the provider.
EVENT_CONTROL_CODE_ENABLE_PROVIDER	Enables the provider. The session receives events when the provider is registered.
EVENT_CONTROL_CODE_CAPTURE_STATE	Requests that the provider log its state information. First you would enable the provider and then call EnableTraceEx2 with this control code to capture state information.

 

Level [in]

Provider-defined value that specifies the level of detail included in the event. Specify one of the following levels that are defined in Winmeta.h. Higher numbers imply that you get lower levels as well. For example, if you specify TRACE_LEVEL_WARNING, you also receive all warning, error, and critical events.

Value	Meaning
TRACE_LEVEL_CRITICAL 1	Abnormal exit or termination events
TRACE_LEVEL_ERROR 2	Severe error events
TRACE_LEVEL_WARNING 3	Warning events such as allocation failures
TRACE_LEVEL_INFORMATION 4	Non-error events such as entry or exit events
TRACE_LEVEL_VERBOSE 5	Detailed trace events

 

MatchAnyKeyword [in]

Bitmask of keywords that determine the category of events that you want the provider to write. The provider writes the event if any of the event's keyword bits match any of the bits set in this mask. See Remarks.

MatchAllKeyword [in]

This bitmask is optional. This mask further restricts the category of events that you want the provider to write. If the event's keyword meets the MatchAnyKeyword condition, the provider will write the event only if all of the bits in this mask exist in the event's keyword. This mask is not used if MatchAnyKeyword is zero. See Remarks.

Timeout [in]

Set to zero to enable the trace asynchronously; this is the default. If the timeout value is zero, this function calls the provider's enable callback and returns immediately. To enable the trace synchronously, specify a timeout value, in milliseconds. If you specify a timeout value, this function calls the provider's enable callback and waits until the callback exits or the timeout expires. To wait forever, set to INFINITE.

EnableParameters [in, optional]

The parameters used to enable the provider. For details, see ENABLE_TRACE_PARAMETERS.

Return value

If the function is successful, the return value is ERROR_SUCCESS.

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

Remarks

Event trace controllers call this function.

The provider defines its interpretation of being enabled or disabled. Typically, if a provider has been enabled, it generates events, but while it is disabled, it does not.

To include all events that a provider provides, set MatchAnyKeyword to zero (for a manifest-based provider and 0xFFFFFFFF for a classic provider). To include specific events, set the MatchAnyKeyword mask to those specific events. For example, if the provider defines an event for its initialization and cleanup routines (set keyword bit 0), an event for its file operations (set keyword bit 1), and an event for its calculation operations (set keyword bit 2), you can set MatchAnyKeyword to 5 to receive initialization and cleanup events and calculation events.

If the provider defines more complex event keywords, for example, the provider defines an event that sets bit 0 for read and bit 1 for local access and a second event that sets bit 0 for read and bit 2 for remote access, you could set MatchAnyKeyword to 1 to receive all read events, or you could set MatchAnykeyword to 1 and MatchAllKeywords to 3 to receive local reads only.

If an event's keyword is zero, the provider will write the event to the session, regardless of the MatchAnyKeyword and MatchAllKeyword masks.

When you call EnableTraceEx2 the provider may or may not be registered. If the provider is registered, ETW calls the provider's callback function, if it implements one, and the session begins receiving events. If the provider is not registered, ETW will call the provider's callback function when it registers itself, if it implements one, and the session will begin receiving events. If the provider is not registered, the provider's callback function will not receive the source ID or filter data. You can call EnableTraceEx2 one time to enable a provider before the provider registers itself.

If the provider is registered and already enabled to your session, you can also use this function to update the Level, MatchAnyKeyword, MatchAllKeyword parameters, and the EnableProperty and EnableFilterDesc members of EnableParameters.

You do not call EnableTraceEx2 to enable kernel providers. To enable kernel providers, set the EnableFlags member of EVENT_TRACE_PROPERTIES which you then pass to StartTrace. The StartTrace function enables the selected kernel providers.

Up to eight trace sessions can enable and receive events from the same manifest-based provider; however, only one trace session can enable a classic provider. If more than one session tried to enable a classic provider, the first session would stop receiving events when the second session enabled the same provider. For example, if Session A enabled Provider 1 and then Session B enabled Provider 1, only Session B would receive events from Provider 1.

The provider remains enabled for the session until the session disables the provider. If the application that started the session ends without disabling the provider, the provider remains enabled.

To determine the level and keywords used to enable a manifest-based provider, use one of the following commands:

• Logman query providers <provider-name>
• Wevtutil gp <provider-name>

For classic providers, it is up to the provider to document and make available to potential controllers the severity levels or enable flags that it supports. If the provider wants to be enabled by any controller, the provider should accept 0 for the severity level and enable flags and interpret 0 as a request to perform default logging (whatever that may be).

If you use EnableTraceEx2 to enable a classic provider, the following translation occurs:

• The Level parameter is the same as setting the EnableLevel parameter in EnableTrace.
• The MatchAnyKeyword is the same as setting the EnableFlag parameter in EnableTrace except that the keyword value is truncated from a ULONGLONG to a ULONG value.
• In the ControlCallback callback, the provider can call GetTraceEnableLevel to get the level and GetTraceEnableFlags to get the enable flag.
• The other parameter are not used.

Requirements

See also

EnableTraceEx

Send comments about this topic to Microsoft

Build date: 12/4/2012