TraceLoggingRegister-Funktion (traceloggingprovider.h)

Registriert einen TraceLogging-Anbieter, damit er zum Protokollieren von Ereignissen verwendet werden kann. Die Registrierung ist gültig, bis der Anbieter die Registrierung aufgehoben oder der Prozess beendet wird.

Syntax

TLG_STATUS TraceLoggingRegister(
  TraceLoggingHProvider hProvider
);

Parameter

hProvider

Das Handle des zu registrierenden TraceLogging-Anbieters. Das Handle darf nicht bereits registriert sein.

Rückgabewert

Wenn Sie diese Funktion über Code im Benutzermodus aufrufen, gibt die Funktion einen HRESULTzurück. Verwenden Sie das SUCCEEDED() Makro, um zu bestimmen, ob die Funktion erfolgreich ist.

Wenn Sie diese Funktion im Kernelmoduscode aufrufen, gibt die Funktion einen NTSTATUSzurück. Verwenden Sie das NT_SUCCESS() Makro, um zu bestimmen, ob die Funktion erfolgreich ist.

Hinweis

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

Hinweise

Wenn eine Komponente ausgeführt wird, befindet sich jedes TraceLogging-Anbieterhandle in der Komponente in einem nicht registrierten Zustand, und alle Versuche, das Handle des Anbieters zum Generieren von Ereignissen zu verwenden, werden unbeaufsichtigt ignoriert. Bevor der Anbieter Ereignisse schreiben kann, müssen Sie den Anbieter mithilfe von TraceLoggingRegister registrieren. Dies geschieht in der Regel während des Komponentenstarts, z. B. in main, wmain, WinMain, DllMain(DLL_PROCESS_ATTACH)oder DriverEntry. Heben Sie beim Herunterfahren der Komponente die Registrierung des Anbieters auf, indem Sie TraceLoggingUnregister aufrufen.

Rufen Sie Nicht TraceLoggingRegister für ein Anbieterhandle auf, das bereits registriert ist. Sie können die Registrierung eines Handles aufheben und es dann bei Bedarf erneut registrieren, obwohl das wiederholte Registrieren und Aufheben der Registrierung des Handle zu Leistungsproblemen führen kann und vermieden werden sollte (d. h. nicht registrieren, einige Ereignisse schreiben und dann die Registrierung aufheben; stattdessen registrieren Sie sich einmal beim Starten der Komponente und aufheben Sie die Registrierung beim Herunterfahren der Komponente).

TraceLoggingRegister ist nicht threadsicher in Bezug auf andere Aufrufe von TraceLoggingRegister oder TraceLoggingUnregister für dasselbe Handle. Rufen Sie TraceLoggingRegister nicht auf, wenn es möglich ist, dass ein anderer Thread TraceLoggingRegister oder TraceLoggingUnregister für dasselbe Handle zur gleichen Zeit aufruft.

Wenn TraceLoggingRegister fehlschlägt, bleibt das Anbieterhandle nicht registriert, und alle Verwendungen des Anbieterhandles sind sichere No-Ops. Insbesondere ist es ein sicherer Nichtbetrieb, TraceLoggingWrite oder TraceLoggingUnregister mit einem nicht registrierten Anbieterhandle aufzurufen.

Wichtig

Wenn Ihre DLL oder Ihr Treiber TraceLoggingRegister für ein Anbieterhandle aufruft, musstraceLoggingUnregister für dieses Anbieterhandle aufgerufen werden, bevor die DLL oder der Treiber entladen wird. Wenn eine DLL entladen wird, ohne TraceLoggingUnregister aufzurufen, kann der Prozess anschließend abstürzen. Wenn ein Treiber entladen wird, ohne TraceLoggingUnregister aufzurufen, kann das System anschließend abstürzen. Die Funktion TraceLoggingRegister richtet einen ETW-Konfigurationsrückruf ein, und TraceLoggingUnregister bricht den Rückruf ab. Wenn der Rückruf nicht abgebrochen wird und das Modul entladen wird, tritt ein Absturz auf, wenn ETW das nächste Mal versucht, den Rückruf aufzurufen.

Warnung

Wenn Ihr Treiber TraceLoggingRegister aufruft und dann während DriverEntry einen Fehler auftritt, muss er TraceLoggingUnregister aufrufen, bevor er den Fehler von DriverEntry zurückgibt. Normale Treiberbereinigungsroutinen werden nicht aufgerufen, wenn der Treiber einen Fehler von DriverEntry zurückgibt, und ein Fehler beim Aufrufen von TraceLoggingUnregister führt zum Absturz des Systems.

TraceLoggingRegister führt folgendes aus:

• Ruft EventRegister auf, um die Verbindung mit ETW zu öffnen.
• Wenn EventRegister erfolgreich ist, ruft TraceLoggingSetInformation mit InformationClassEventProviderSetTraits auf, um den Anbieter für die TraceLogging-Unterstützung zu konfigurieren.

Ein Aufruf von TraceLoggingRegister ist identisch mit einem Aufruf von TraceLoggingRegisterEx mit NULL für die Rückruf - und Kontextparameter . Verwenden Sie TraceLoggingRegisterEx , wenn Sie einen ETW Enable Callback erhalten müssen, wenn Sitzungen Ihren Anbieter aktivieren oder deaktivieren.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [Desktop-Apps | UWP-Apps]
Kopfzeile	traceloggingprovider.h
Bibliothek	Advapi32.lib

Weitere Informationen

EventRegister

TraceLoggingRegisterEx

TraceLoggingUnregister

TraceLoggingWrite

TRACELOGGING_DEFINE_PROVIDER