Edit

EventEnabled function (evntprov.h)

  • Article

Determines whether an event provider should generate a particular event based on the event's EVENT_DESCRIPTOR.

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 EventEnabled(
  [in] REGHANDLE          RegHandle,
  [in] PCEVENT_DESCRIPTOR EventDescriptor
);

Parameters

[in] RegHandle

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

If RegHandle is NULL, EventEnabled will return FALSE.

[in] EventDescriptor

EVENT_DESCRIPTOR that provides information that will be used to determine whether the event is enabled. This includes the event's Level (severity) and Keyword (categories).

Return value

Returns FALSE if the provider should skip generating the event, i.e. returns FALSE if ETW can quickly determine that no event collection session would record an event from the given provider with the specified descriptor. Otherwise returns TRUE, indicating that the provider should generate the event.

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 and the event descriptor.

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 EventProviderEnabled. 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 EventEnabled directly:

  • The EventWrite APIs include their own EventEnabled 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 EventEnabled. ETW frameworks generally provide their own event-enabled API which should be used instead of calling EventEnabled.
  • ETW framework implementations usually check their own provider state rather than calling 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

EventProviderEnabled

EVENT_DESCRIPTOR