PETWENABLECALLBACK callback function

The EtwEnableCallback function is an optional driver-supplied callback function that is used to receive enable or disable notifications.

Syntax


PETWENABLECALLBACK EtwEnableCallback;

VOID EtwEnableCallback(
  _In_        LPCGUID                  SourceId,
  _In_        ULONG                    IsEnabled,
  _In_        UCHAR                    Level,
  _In_        ULONGLONG                MatchAnyKeyword,
  _In_        ULONGLONG                MatchAllKeyword,
  _In_opt_    PEVENT_FILTER_DESCRIPTOR FilterData,
  _Inout_opt_ PVOID                    CallbackContext
)
{ ... }

Parameters

SourceId [in]

The GUID that identifies the session that enabled the provider.

IsEnabled [in]

The parameter indicates whether the provider is being enabled or disabled. The value is TRUE if the session enabled the provider; otherwise, it is FALSE.

Level [in]

The level at which the event is enabled. This parameter is a provider-defined value that specifies the verboseness of the events that the provider writes. The provider must write the event if this value is less than or equal to the level value that the event defines.

This value is passed in the Level parameter of the EnableTraceEx function or the EnableLevel parameter of the EnableTrace function.

MatchAnyKeyword [in]

The bitmask of keywords that the provider uses to determine the category of events that it writes.

This value is passed in the MatchAnyKeyword parameter of the EnableTraceEx function or the EnableFlag parameter of the EnableTrace function. MatchAnyKeyword is a 64-bit value and is basically an extended version of the 32-bit EnableFlag.

MatchAllKeyword [in]

This bitmask additionally restricts the category of events that the provider writes.

This value is passed in the MatchAllKeywords parameter of the EnableTraceEx function.

FilterData [in, optional]

The provider-defined data. This parameter is optional. The provider determines the layout of the data and its purpose. For example, the provider can use this data to additionally filter the events that it writes or use it to perform some calculations before writing the events. For detailed information, see Event Filter Descriptor.

CallbackContext [in, out, optional]

The context of the callback function that is defined when the provider called EtwRegister to register itself. This parameter is optional.

Return value

None

Remarks

Use the EtwRegister function to specify a pointer to the EtwEnableCallback function.

Use the FilterData parameter of the callback function to supply the provider with sophisticated filtering abilities. The EtwEnableCallback function does not replace the enable-status function calls (EtwEventEnabled and EtwProviderEnabled). However, it serves as a supplement to them. However, unless your level and keywords are currently enabled, the event will not be written, regardless of the FilterData that the callback function provides.

Callers of EtwEnableCallback must be running at IRQL = PASSIVE_LEVEL in the context of a system thread.

Requirements

Target platform

Desktop

Version

Available in Windows Vista and later versions of Windows.

Header

Wdm.h (include Wdm.h or Ntddk.h)

IRQL

PASSIVE_LEVEL

See also

EtwRegister
EtwEventEnabled
EtwProviderEnabled
Event Filter Descriptor
EnableTrace
EnableTraceEx

 

 

Send comments about this topic to Microsoft

Show: