EnableCallback callback function
Providers implement this function to receive enable or disable notification requests.
The PENABLECALLBACK type defines a pointer to this callback function. EnableCallback is a placeholder for the application-defined function name.
void NTAPI EnableCallback( _In_ LPCGUID SourceId, _In_ ULONG IsEnabled, _In_ UCHAR Level, _In_ ULONGLONG MatchAnyKeyword, _In_ ULONGLONG MatchAllKeywords, _In_opt_ PEVENT_FILTER_DESCRIPTOR FilterData, _In_opt_ PVOID CallbackContext );
- SourceId [in]
GUID that identifies the session that enabled the provider. The value is GUID_NULL if EnableTraceEx did not specify a source identifier.
- IsEnabled [in]
Indicates if the session is enabling or disabling the provider. A value of zero indicates that the session is disabling the provider. A value of 1 indicates that the session is enabling the provider. Beginning with Windows 7, this value can be one of the following values:
If you receive a value (for example, EVENT_CONTROL_CODE_CAPTURE_STATE) that you do not support, ignore the value (do not fail).
- Level [in]
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.
- MatchAnyKeyword [in]
Bitmask of keywords that the provider uses to determine the category of events that it writes.
- MatchAllKeywords [in]
This bitmask is optional. This mask further restricts the category of events that the provider writes.
This value is passed in the MatchAllKeywords parameter of the EnableTraceEx function.
- FilterData [in, optional]
A list of filter data that one or more sessions passed to the provider. A session can specify only one filter but the list will contain filters from all sessions that used filter data to enable the provider.
The filter data is valid only within the callback, so providers should make a local copy of the data.
- CallbackContext [in, optional]
Context of the callback defined when the provider called EventRegister to register itself.
This callback function does not return a value.
To specify that you want to receive notification when a session enables or disables your provider, set the EnableCallback parameter when calling the EventRegister function.
Classic providers needed to specify and implement a callback because it used the information that was passed to the callback to determine the types of events to log and the level of verboseness to use when logging the events. However, with manifest-based providers, the callback is optional and is used for informational purposes; you do not need to specify or implement the callback when registering the provider unless your provider supports filtering. Providers can now just write events and ETW will determine if the event is logged to the session. If you want to verify that the event should be written before writing the event, you can call either the EventEnabled or EventProviderEnabled function.
Each time a new session enables the provider or a current session updates the provider, ETW calls the provider's callback function, if implemented. The level value that ETW passes to the callback is the highest level value specified amongst all the sessions. For example, if session A enabled the provider for warning (3) events and then session B enabled the provider for critical (1) events, the level value for the second callback is also 3, not 1.
The MatchAnyKeyword value that ETW passes to the callback is a composite value of all MatchAnyKeyword values specified for all sessions that enabled the provider. The same is true for the MatchAllKeywords value. The SourceId and FilterData values are those values passed to the EnableTraceEx call.
Your callback function must not call anything that may incur LoadLibrary (more specifically, anything that requires a loader lock).
Minimum supported client
|Windows Vista [desktop apps only]|
Minimum supported server
|Windows Server 2008 [desktop apps only]|