ETWENABLECALLBACK callback function (wdm.h)

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

Syntax

ETWENABLECALLBACK Etwenablecallback;

void Etwenablecallback(
  [in]                LPCGUID SourceId,
                      ULONG ControlCode,
  [in]                UCHAR Level,
  [in]                ULONGLONG MatchAnyKeyword,
  [in]                ULONGLONG MatchAllKeyword,
  [in, optional]      PEVENT_FILTER_DESCRIPTOR FilterData,
  [in, out, optional] PVOID CallbackContext
)
{...}

Parameters

[in] SourceId

The GUID that identifies the session that enabled the provider.

ControlCode

[in] Level

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.

[in] MatchAnyKeyword

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.

[in] MatchAllKeyword

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

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

[in, optional] FilterData

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.

[in, out, optional] CallbackContext

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

See also

EnableTrace

EnableTraceEx

EtwEventEnabled

EtwProviderEnabled

EtwRegister

Event Filter Descriptor