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.

Syntax


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
);

Parameters

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:

ValueMeaning
EVENT_CONTROL_CODE_DISABLE_PROVIDER
0

The session is disabling the provider.

EVENT_CONTROL_CODE_ENABLE_PROVIDER
1

The session is enabling the provider.

EVENT_CONTROL_CODE_CAPTURE_STATE
2

The session is requesting that the provider log its state information. The provider determines the state information that it logs.

 

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.

This value is passed in the Level parameter of the EnableTraceEx function or the EnableLevel parameter of EnableTrace.

MatchAnyKeyword [in]

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 EnableTrace.

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.

Return value

This callback function does not return a value.

Remarks

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).

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Evntprov.h

See also

EventRegister
EnableTraceEx

 

 

Community Additions

ADD
Show:
© 2014 Microsoft