EventEnabled function (evntprov.h)
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 |