PENABLECALLBACK-Rückruffunktion (evntprov.h)

ETW-Ereignisanbieter definieren optional eine EnableCallback-Funktion , um Konfigurationsänderungsbenachrichtigungen zu empfangen. Der PENABLECALLBACK-Typ definiert einen Zeiger auf diese Rückruffunktion. EnableCallback ist ein Platzhalter für den anwendungsdefinierte Funktionsnamen.

Syntax

PENABLECALLBACK Penablecallback;

void Penablecallback(
  [in]           LPCGUID SourceId,
  [in]           ULONG IsEnabled,
  [in]           UCHAR Level,
  [in]           ULONGLONG MatchAnyKeyword,
                 ULONGLONG MatchAllKeyword,
  [in, optional] PEVENT_FILTER_DESCRIPTOR FilterData,
  [in, optional] PVOID CallbackContext
)
{...}

Parameter

[in] SourceId

GUID, die vom Aufrufer angegeben wird, der den Anbieter aktiviert oder deaktiviert.

Der Wert stammt aus dem SourceId-Parameter von EnableTraceEx oder dem Feld SourceId der ENABLE_TRACE_PARAMETERS , die an EnableTraceEx2 übergeben wird.

Hinweis

Die SourceId ist der Wert der Sitzung, die im Aufruf der EnableTraceEx- oder EnableTraceEx2-API angegeben wurde. Sie kann mit der GUID der Sitzung identisch sein oder nicht.

SourceId wird in mehreren Szenarien auf GUID_NULL festgelegt, in denen die Benachrichtigung keinen Quellbezeichner enthält. Dies kann beispielsweise auftreten, wenn eine Ablaufverfolgungssitzung den Anbieter vor dem Start des Anbieters aktiviert hat, wenn der Anbieter beendet wird oder wenn ein Ablaufverfolgungscontroller eine EnableTrace-API aufruft, ohne eine SourceId anzugeben.

[in] IsEnabled

Gibt den ControlCode an, der dieser Benachrichtigung entspricht. Mögliche Werte:

Wert	Bedeutung
EVENT_CONTROL_CODE_DISABLE_PROVIDER (0)	Der Anbieter wurde nicht in Sitzungen aktiviert.
EVENT_CONTROL_CODE_ENABLE_PROVIDER (1)	Mindestens eine Sitzung hat den Anbieter aktiviert.
EVENT_CONTROL_CODE_CAPTURE_STATE (2)	Eine Sitzung fordert den Anbieter auf, seine Statusinformationen zu protokollieren. Der Anbieter antwortet in der Regel, indem er Ereignisse schreibt, die den Anbieterstatus enthalten.

Hinweis

Der Wert von IsEnabled ist möglicherweise nicht identisch mit dem ControlCode , der an die EnableTrace-API übergeben wurde, die dieses Ereignis ausgelöst hat. Wenn beispielsweise zwei Sitzungen diesen Anbieter aktiviert haben und eine Sitzung diesen Anbieter durch Aufrufen EnableTraceEx2(..., EVENT_CONTROL_CODE_DISABLE_PROVIDER, ...)von deaktiviert, erhält der Anbieter eine Benachrichtigung, bei der IsEnabled auf EVENT_CONTROL_CODE_ENABLE_PROVIDER festgelegt ist, da der Anbieter weiterhin von der anderen Sitzung aktiviert ist.

Nach dem Empfang einer DISABLE_PROVIDER Benachrichtigung kann ein Anbieter seine Leistung optimieren, indem er alle Ereignisse deaktiviert. Nach dem Empfang einer ENABLE_PROVIDER Benachrichtigung sollte ein Anbieter das Schreiben von Ereignissen aktivieren. Es kann auch seine Leistung optimieren, indem die Werte der Filter Level, MatchAnyKeyword und MatchAllKeyword aufgezeichnet und dann nur die Ereignisse geschrieben werden, die die Filter übergeben (wie in Den Hinweisen beschrieben). Nachdem eine CAPTURE_STATE Benachrichtigung empfangen wurde, kann ein Anbieter alle geeigneten Aktionen ausführen und in der Regel Ereignisse schreiben, die die Konfiguration oder den Zustand der Komponente beschreiben.

Ein Anbieter sollte Benachrichtigungen mit IsEnabled-Werten ignorieren, die er nicht erkennt oder unterstützt.

[in] Level

Ein -Wert, der die Ausführlichkeit der Ereignisse angibt, die der Anbieter schreiben soll. Wenn er mit dem Steuerelementcode EVENT_CONTROL_CODE_ENABLE_PROVIDER aufgerufen wird, sollte der Anbieter den Level-Wert aufzeichnen und anschließend Ereignisse überspringen, bei denen der Ausführlichkeitsgrad des Ereignisses größer als der aufgezeichnete Level ist, d. h. ein Ereignis sollte nur geschrieben werden, wenn

eventDescriptor.Level <= recorded.Level

Die Ebene in der Benachrichtigung ist das Maximum der Ebenen, die von Ablaufverfolgungscontrollern in Aufrufen von EnableTrace, EnableTraceEx oder EnableTraceEx2 mithilfe der GUID dieses Ereignisanbieters angegeben werden. Anders ausgedrückt: Wenn mehrere Sitzungen Ereignisse von diesem Ereignisanbieter mit unterschiedlichen Ausführlichkeitsstufen aufzeichnen, wird der Level-Parameter für die EnableCallback-Benachrichtigung auf den höchsten (ausführlichsten) der Ebenen festgelegt.

[in] MatchAnyKeyword

Eine Bitmaske, die Kategorien von Ereignissen angibt, die der Anbieter schreiben soll. Wenn er mit dem Steuerelementcode EVENT_CONTROL_CODE_ENABLE_PROVIDER aufgerufen wird, sollte der Anbieter den MatchAnyKeyword-Wert aufzeichnen und anschließend Ereignisse überspringen, bei denen die Schlüsselwort (keyword) des Ereignisses ungleich null ist und keines der Bits aus dem aufgezeichneten MatchAnyKeyword enthält, d. h. ein Ereignis sollte nur geschrieben werden, wenn

eventDescriptor.Keyword == 0 || (eventDescriptor.Keyword & recorded.MatchAnyKeyword) != 0

MatchAnyKeyword in der Benachrichtigung ist die Union (OR) der Match-any-Keywords (Enable Flags), die von Ablaufverfolgungscontrollern in Aufrufen von EnableTrace, EnableTraceEx und EnableTraceEx2 für die GUID dieses Ereignisanbieters angegeben werden. Anders ausgedrückt: Wenn mehrere Sitzungen Ereignisse von diesem Ereignisanbieter mit unterschiedlichen Match-any-Schlüsselwort (keyword)-Filtern aufzeichnen, wird der MatchAnyKeyword-Parameter für die EnableCallback-Benachrichtigung auf den bitweisen -ORFilter der Match-any-Schlüsselwort (keyword) der Sitzungen festgelegt.

MatchAllKeyword

Eine Bitmaske, die Kategorien von Ereignissen angibt, die der Anbieter schreiben soll. Wenn er mit dem Steuerungscode EVENT_CONTROL_CODE_ENABLE_PROVIDER benachrichtigt wird, sollte der Anbieter den MatchAllKeyword-Wert aufzeichnen und anschließend Ereignisse überspringen, bei denen die Schlüsselwort (keyword) des Ereignisses ungleich null ist und nicht alle Bits aus dem aufgezeichneten MatchAllKeyword enthalten, d. h. ein Ereignis sollte nur geschrieben werden, wenn

eventDescriptor.Keyword == 0 || (eventDescriptor.Keyword & recorded.MatchAllKeyword) == recorded.MatchAllKeyword

MatchAllKeyword in der Benachrichtigung ist die Disjunktion (AND) der Match-all-Keywords, die von Ablaufverfolgungscontrollern in Aufrufen von EnableTraceEx und EnableTraceEx2 für die GUID dieses Ereignisanbieters angegeben werden. Anders ausgedrückt: Wenn mehrere Sitzungen Ereignisse von diesem Ereignisanbieter mit unterschiedlichen Match-all-Schlüsselwort (keyword)-Filtern aufzeichnen, wird der MatchAllKeyword-Parameter für die EnableCallback-Benachrichtigung auf den bitweisen derAND Match-all-Schlüsselwort (keyword)-Filter der Sitzungen festgelegt.

[in, optional] FilterData

Ein Zeiger auf eine EVENT_FILTER_DESCRIPTOR mit Filterdaten für den Ereignisanbieter.

Jede Sitzung kann nur einen Filter angeben. Der Filterdeskriptor in der Rückrufbenachrichtigung enthält einen Filter aus jeder Sitzung, der beim Aktivieren des Anbieters Filterdaten angegeben hat.

Die Filterdaten sind nur innerhalb des Rückrufs gültig. Anbieter sollten eine lokale Kopie der Daten erstellen, wenn die Daten nach der Rückgabe des Rückrufs benötigt werden.

[in, optional] CallbackContext

Kontext für den Rückruf. Dies ist der Wert des CallbackContext-Parameters , der verwendet wurde, wenn der Ereignisanbieter EventRegister aufgerufen hat.

Rückgabewert

Keine

Bemerkungen

ETW-Ereignisanbieter, die Konfigurationsänderungsbenachrichtigungen benötigen, sollten bei der Registrierung über EventRegister einen Zeiger auf ihre EnableCallback-Implementierung bereitstellen. ETW ruft die EnableCallback-Funktion des Anbieters auf, wenn eine Änderung an der Konfiguration einer Ablaufverfolgungssitzung vorgenommen wird, die den Anbieter einbezieht. Wenn beispielsweise ein Ablaufverfolgungssitzungscontroller eine Ablaufverfolgung über EnableTraceEx2 konfiguriert oder eine Ablaufverfolgung über ControlTrace beendet, ruft ETW die EnableCallback-Funktion des Anbieters mit der daraus resultierenden aktualisierten Konfiguration auf.

Hinweis

Die meisten Ereignisanbieter implementieren EnableCallback nicht direkt. Stattdessen werden die meisten Ereignisanbieter mithilfe eines ETW-Frameworks implementiert, das eine eigene EnableCallback-Implementierung bereitstellt und die Aufrufe von EventRegister, EventWrite und EventUnregister umschließt. Sie können beispielsweise ein Ereignismanifest schreiben und dann den Nachrichtencompiler verwenden, um C/C++-Code für die Ereignisse zu generieren, oder Sie können TraceLogging verwenden, um die Notwendigkeit eines Manifests zu vermeiden. Das ETW-Framework implementiert in der Regel eine EnableCallback-Funktion, die die Werte , MatchAnyKeywordund MatchAllKeyword der Benachrichtigung Levelaufzeichnet, und das Framework verwendet automatisch die aufgezeichneten Werte, um Ereignisse zu filtern. Das ETW-Framework unterstützt in der Regel das Aufrufen eines vom Benutzer bereitgestellten Rückrufs, wenn der Benutzer eine benutzerdefinierte Benachrichtigungsbehandlung benötigt. Beispielsweise ermöglicht TraceLoggingProvider.h das Angeben eines Benachrichtigungsrückrufs über TraceLoggingRegisterEx.

Wichtig

Die EnableCallback-Funktion des Anbieters sollte so einfach wie möglich sein. Sie sollte die erforderlichen Informationen aufzeichnen und schnell zurückgeben. Eine Rückruffunktion mit langer Ausführungsdauer kann zu Verzögerungen in ETW-Sitzungssteuerungs-APIs wie EnableTraceEx2 oder ControlTrace führen. Die Rückruffunktion darf keine Aktionen ausführen, die die Ladesperre des Prozesses erfordern, d. h. sie darf LoadLibrary oder FreeLibrary nicht direkt oder indirekt aufrufen. Die Rückruffunktion darf für Sperren nicht blockiert werden. Die Rückruffunktion kann einen Deadlock verursachen, wenn sie Sperren blockiert oder ETW-Sitzungssteuerungs-APIs wie StartTrace, ControlTrace oder EnableTrace aufruft.

Der Benachrichtigungsrückruf ermöglicht es dem Ereignisanbieter, effizienter auszuführen, da der Anbieter eine eigene Nachverfolgung der Ebene, der Schlüsselwörter und anderer Filter durchführen kann. Durch die Nachverfolgung der Filter kann der Anbieter Ereignisse, die nicht aktiviert sind, effizient überspringen (d. h. der Anbieter muss die Ereignisdaten nicht vorbereiten oder EventWrite für Ereignisse aufrufen, die von keiner Ablaufverfolgungssitzung benötigt werden).

Beachten Sie, dass die Filternachverfolgung für den ordnungsgemäßen Betrieb eines Anbieters nicht erforderlich ist: ETW stellt EventEnabled - und EventProviderEnabled-Funktionen bereit, die ein Anbieter verwenden kann, und die ETW EventWrite-APIs ignorieren alle deaktivierten Ereignisse automatisch. Die vom Anbieter implementierte Filternachverfolgung kann jedoch effizienter sein als Aufrufe von EventEnabled oder EventProviderEnabled.

Der Benachrichtigungsrückruf ermöglicht es dem Anbieter auch, "capture-state"-Anforderungen aus Ablaufverfolgungssitzungen zu verarbeiten. Aufzeichnungszustandsanforderungen werden in der Regel von einer Ablaufverfolgungssitzung gesendet, wenn mit der Aufzeichnung von Ereignissen von einem Anbieter begonnen wird. Wenn capture-state von einem Anbieter unterstützt wird, kann er auf die Anforderung zum Erfassungszustand reagieren, indem Zustandsinformationen protokolliert werden, z. B. Konfigurationsinformationen oder zusammenfassende Statistiken zum Vorgang der Komponente vor der Anforderung.

Der Level-Wert , den ETW an den Rückruf übergibt, ist der höchste (ausführlichste) Ebenenwert, der für diesen Ereignisanbieter von jeder ausgeführten Ablaufverfolgungssitzung angegeben wird. Wenn beispielsweise Sitzung A diesen Anbieter für Warnungsereignisse (Ebene 3) aktiviert hat und Sitzung B den Anbieter für kritische Ereignisse (Ebene 1) aktiviert, ist der Level-Wert für den Rückruf 3, nicht 1.

Auf ähnliche Weise sind die Werte MatchAnyKeyword und MatchAllKeyword zusammengesetzte Werte, die aus der Konfiguration aller Sitzungen berechnet werden, die den Ereignisanbieter aktiviert haben. MatchAnyKeyword ist das OR der Einstellungen EnableFlags/MatchAnyKeyword der Sitzungen. MatchAllKeyword ist das AND der MatchAllKeyword-Einstellungen der Sitzungen.

Wenn die EnableCallback-Funktion des Anbieters den Status Enabled, Level, MatchAnyKeyword und MatchAllKeyword des Anbieters erfasst hat, kann der Anbieter mithilfe einer Funktion wie der folgenden bestimmen, ob ein Ereignis geschrieben werden soll:

BOOL MyProviderEventEnabled(
    _In_ const MY_PROVIDER_STATE* pProvider,
    _In_ const EVENT_DESCRIPTOR* pEvent)
{
    return
        pProvider->Enabled &&
        pEvent->Level <= pProvider->Level &&
        (pEvent->Keyword == 0 || (
            (pEvent->Keyword & pProvider->MatchAnyKeyword) != 0 &&
            (pEvent->Keyword & pProvider->MatchAllKeyword) == pProvider->MatchAllKeyword
        ));
}

Anforderungen

Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	evntprov.h

Weitere Informationen

EventRegister

EnableTrace

EnableTraceEx2