Edit

EventProviderEnabled function (evntprov.h)

  • Article

Determines whether an event provider should generate a particular event based on the event's Level and Keyword.

Returns FALSE if ETW can quickly determine that no session is listening for a specified event from the given provider. Otherwise returns TRUE.

Syntax

BOOLEAN EVNTAPI EventProviderEnabled(
  [in] REGHANDLE RegHandle,
  [in] UCHAR     Level,
  [in] ULONGLONG Keyword
);

Parameters

[in] RegHandle

Registration handle of the provider. The handle comes from EventRegister.

If RegHandle is NULL, EventProviderEnabled will return FALSE.

[in] Level

An 8-bit number used to describe an event's severity or importance. See EVENT_DESCRIPTOR for more information about event level values.

[in] Keyword

A 64-bit bitmask used to indicate an event's membership in a set of event categories. See EVENT_DESCRIPTOR for more information about event keyword values.

Return value

Returns FALSE if ETW can quickly determine that no session is listening for a specified event from the given provider. Otherwise returns TRUE.

Remarks

This API provides a simple way to determine whether an event is enabled (i.e. whether any event consumer sessions are interested in receiving the event) based on the provider handle, the event level, and the event keyword.

Note

This API performs a conservative quick test. It is possible for this API to return true in certain cases where subsequent in-depth filtering would determine that no sessions need to record the event.

This API provides functionality similar to the functionality provided by EventEnabled. When a provider has access to an event's complete EVENT_DESCRIPTOR, the provider should use EventEnabled. When a provider has access only to the event's Level and Keyword, the provider should use EventProviderEnabled.

Most event providers will not call EventProviderEnabled directly:

  • The EventWrite APIs include their own EventProviderEnabled test and return immediately if the event is not enabled.
  • Most ETW providers use an ETW framework (e.g. manifests or TraceLogging) instead of directly calling EventWrite or EventProviderEnabled. ETW frameworks generally provide their own event-enabled API which should be used instead of calling EventProviderEnabled.
  • ETW framework implementations usually check their own provider state rather than calling EventProviderEnabled.

For additional details, see EventEnabled.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header evntprov.h
Library Advapi32.lib
DLL Advapi32.dll

See also

EventEnabled

EVENT_DESCRIPTOR