EventRegister-Funktion (evntprov.h)

Registriert einen ETW-Ereignisanbieter, der zum Schreiben von ETW-Ereignissen verwendet werden kann.

Syntax

ULONG EVNTAPI EventRegister(
  [in]           LPCGUID         ProviderId,
  [in, optional] PENABLECALLBACK EnableCallback,
  [in, optional] PVOID           CallbackContext,
  [out]          PREGHANDLE      RegHandle
);

Parameter

[in] ProviderId

GUID, die den Anbieter eindeutig identifiziert, manchmal als Steuerelement-GUID bezeichnet. Dies muss ein stabiler Bezeichner sein, damit Ablaufverfolgungscontroller die GUID verwenden können, um Ereignisse von diesem Anbieter zu abonnieren.

[in, optional] EnableCallback

Optional EnableCallback , das ETW aufruft, wenn eine Ablaufverfolgungssitzung diesen Anbieter aktiviert oder deaktiviert. Verwenden Sie NULL , wenn kein Rückruf erforderlich ist.

[in, optional] CallbackContext

Optionale Kontextdaten, die ETW beim Aufrufen von EnableCallback bereitstellen. Verwenden Sie NULL , wenn kein Rückrufkontext erforderlich ist.

[out] RegHandle

Empfängt den Registrierungshandpunkt des Ereignisanbieters. Das Handle wird in nachfolgenden Aufrufen von Anbieter-APIs wie EventWrite, EventProviderEnabled und EventRegister verwendet.

Bevor Ihr Anbieter das Laden oder Beenden beendet, geben Sie den Anbieterregistrierungshandpunkt durch Aufrufen von EventUnregister frei. Eine DLL, die entladen wird, ohne alle vom Anbieter registrierten Handle freizuladen, kann dazu führen, dass der Prozess abstürzt.

Rückgabewert

Gibt ERROR_SUCCESS zurück, wenn dies erfolgreich ist.

Der von EventRegister zurückgegebene Fehlercode ist in erster Linie für die Verwendung in Debug- und Diagnoseszenarien vorgesehen. Die meisten Produktionscode sollten weiterhin ausgeführt werden, auch wenn ein ETW-Anbieter nicht registriert wurde, sodass Releasebuilds normalerweise den von EventRegister zurückgegebenen Fehlercode ignorieren sollten.

Hinweise

EventRegister erstellt einen Handle, mit dem Sie ETW-Ereignisse über EventWrite, EventWriteTransfer oder EventWriteEx schreiben können.

Hinweis

Die meisten Ereignisanbieter rufen eventRegister nicht direkt auf. Stattdessen werden die meisten Ereignisanbieter mithilfe eines ETW-Frameworks implementiert, das die Aufrufe von EventRegister, EventWrite und EventUnregister umschließt. Sie können z. B. ein Ereignismanifest schreiben und dann den Nachrichten compiler verwenden, um C/C++-Code für die Ereignisse zu generieren, oder Sie können TraceLogging verwenden, um die Notwendigkeit eines Manifests zu vermeiden.

Die Registrierung eines Ereignisanbieters sollte nicht mit der Installation des Manifests eines Ereignisanbieters verwechselt werden.

  • Die EventRegister-API führt die Registrierung eines Ereignisanbieters durch, um ein Anbieterhandle zu erstellen. Dies ist ein Prozessbereichsvorgang (der Handle ist nur innerhalb des Prozesses gültig). Das Handle kann zum Schreiben von ETW-Ereignissen verwendet werden. Alle Ereignisse, die mithilfe des Handles geschrieben wurden, werden mit der Anbieter-ID markiert, die während der Anbieterregistrierung angegeben wurde. Es ist nicht erforderlich, ein Manifest zu installieren, um Ereignisse zu schreiben oder Ablaufverfolgungen zu erfassen (obwohl die Installation des Manifests möglicherweise erforderlich ist, um die Ereignisse des Anbieters zu decodieren oder für die Arbeit mit dem Ereignisprotokoll zu verwenden).
  • Das toolwevtutil.exe wird verwendet, um das Manifest eines Ereignisanbieters zu installieren oder zu deinstallieren. Die Installation eines Ereignisanbietermanifests bedeutet, dass Informationen aus dem Manifest im System aufgezeichnet werden. Die aufgezeichneten Informationen sind system-global und bleiben erhalten, bis das Manifest deinstalliert wird. Die aufgezeichneten Informationen umfassen die Namen, GUIDs, Kanäle und Ressourcen-DLL-Pfade der im Manifest definierten Anbieter. Die Informationen aus dem Manifest werden von Ablaufverfolgungsdecodierungstools und Ereignisprotokollen verwendet.

Die meisten Komponenten registrieren ihren Ereignisanbieter bei der Komponenteninitialisierung und heben die Registrierung ihres Ereignisanbieters beim Herunterfahren der Komponente auf. Beispielsweise kann sich eine Anwendung (EXE) während des Anwendungsstarts registrieren und die Registrierung während des Anwendungsausgangs aufheben. Eine dynamische Bibliothek (DLL) kann sich während DllMain der Prozessanfügung registrieren und die Registrierung DllMain während der Prozessablösung aufheben.

Da die Ereignisablaufverfolgung ein Debugging-/Diagnoseproblem ist und normalerweise keine anwendungskritische Funktionalität ist, sollten die meisten Einzelhandelsanwendungen Fehler ignorieren, die von EventRegister zurückgegeben werden. Im Falle eines Fehlers legt EventRegister den RegHandle-Parameter auf Null fest, sodass nachfolgende Verwendungen des RegHandle (d. h. in Aufrufen von EventWrite und EventUnregister) keine Auswirkung haben.

Jeder Prozess kann bis zu 1.024 Anbieter registrieren. Sie sollten jedoch die Anzahl der Anbieter einschränken, die Ihre Komponente auf ein oder zwei registriert. Dieser Grenzwert umfasst Anbieter, die mit dieser Funktion registriert sind, und Anbieter, die mit RegisterTraceGuids registriert sind.

Vor Windows Vista: Es gibt keine spezifische Grenze für die Anzahl der Anbieter, die ein Prozess registrieren kann.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows Vista [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile evntprov.h
Bibliothek Advapi32.lib
DLL Advapi32.dll

Weitere Informationen

EnableCallback

EventWrite

EventUnregister