EventRegister-Funktion (evntprov.h)

Registriert einen ETW-Ereignisanbieter und erstellt ein Handle, das 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 auch 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

Optionales 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 bereitstellt. Verwenden Sie NULL , wenn kein Rückrufkontext erforderlich ist.

[out] RegHandle

Empfängt das Ereignisanbieterregistrierungshandle. Das Handle wird in nachfolgenden Aufrufen von Anbieter-APIs wie EventWrite, EventProviderEnabled und EventRegister verwendet.

Bevor Ihr Anbieter entladen oder beendet wird, geben Sie das Registrierungshandle des Anbieters frei, indem Sie EventUnregister aufrufen. Eine DLL, die entladen wird, ohne alle registrierten Anbieterhandles frei zu geben, kann dazu führen, dass der Prozess abstürzt.

Rückgabewert

Gibt bei erfolgreicher Ausführung ERROR_SUCCESS zurück.

Der von EventRegister zurückgegebene Fehlercode ist in erster Linie für die Verwendung in Debug- und Diagnoseszenarien vorgesehen. Der meiste Produktionscode sollte auch dann weiterhin ausgeführt werden, wenn sich ein ETW-Anbieter nicht registrieren konnte. Daher sollten Releasebuilds den von EventRegister zurückgegebenen Fehlercode in der Regel ignorieren.

Hinweise

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

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 Vorgang im Prozessbereich (das Handle ist nur innerhalb des Prozesses gültig). Das Handle kann zum Schreiben von ETW-Ereignissen verwendet werden. Alle Mit dem Handle geschriebenen Ereignisse werden mit der ProviderId gekennzeichnet, die bei der Anbieterregistrierung angegeben wurde. Es ist nicht erforderlich, ein Manifest zu installieren, um Ereignisse zu schreiben oder Ablaufverfolgungen zu erfassen (die Installation des Manifests kann jedoch erforderlich sein, um die Ereignisse des Anbieters zu decodieren oder damit der Anbieter mit dem Ereignisprotokoll arbeitet).
• Das wevtutil.exe-Tool wird verwendet, um das Manifest eines Ereignisanbieters zu installieren oder zu deinstallieren. Die Installation eines Ereignisanbietermanifests bedeutet, dass Informationen aus dem Manifest auf dem System aufgezeichnet werden. Die aufgezeichneten Informationen sind system global und werden beibehalten, 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 Ablaufverfolgungs-Decodierungstools und dem Ereignisprotokoll 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 Beendens der Anwendung aufheben. Eine dynamische Bibliothek (DLL) kann sich während der Prozessanfügung in registrieren DllMain und die Registrierung DllMain während der Prozessablösung aufheben.

Da die Ereignisablaufverfolgung ein Debug-/Diagnoseproblem darstellt und normalerweise keine anwendungskritische Funktionalität ist, sollten die meisten Einzelhandelsanwendungen von EventRegister zurückgegebene Fehler im Hintergrund ignorieren. Im Falle eines Fehlers legt EventRegister den RegHandle-Parameter auf Null fest, sodass nachfolgende Verwendungen von RegHandle (d. h. bei Aufrufen von EventWrite und EventUnregister) keine Auswirkungen haben.

Jeder Prozess kann bis zu 1.024 Anbieter registrieren. Sie sollten jedoch die Anzahl der Anbieter, die Ihre Komponente registriert, auf einen oder zwei beschränken. Dieser Grenzwert gilt für Anbieter, die mit dieser Funktion registriert sind, und Anbieter, die mit RegisterTraceGuids registriert sind.

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

Anforderungen

Weitere Informationen

EnableCallback

EventWrite

EventUnregister