RegisterTraceGuidsW-Funktion (evntrace.h)

  • Artikel

Die RegisterTraceGuids-Funktion registriert einen klassischen ETW-Ereignisablaufverfolgungsanbieter (Windows 2000-Format) und die Ereignisablaufverfolgungsklassen, die zum Generieren von Ereignissen verwendet werden. Diese Funktion gibt auch die Rückruffunktion an, die das System verwendet, um die Ablaufverfolgung vom Anbieter zu aktivieren und zu deaktivieren.

Diese Funktion ist veraltet. Neuer Code sollte EventRegister verwenden, um einen ETW-Ereignisablaufverfolgungsanbieter im Windows Vista-Stil (Crimson) zu registrieren.

Syntax

ULONG WMIAPI RegisterTraceGuidsW(
  [in]      WMIDPREQUEST             RequestAddress,
  [in]      PVOID                    RequestContext,
  [in]      LPCGUID                  ControlGuid,
  [in]      ULONG                    GuidCount,
  [in, out] PTRACE_GUID_REGISTRATION TraceGuidReg,
  [in]      LPCWSTR                  MofImagePath,
  [in]      LPCWSTR                  MofResourceName,
  [out]     PTRACEHANDLE             RegistrationHandle
);

Parameter

[in] RequestAddress

Zeiger auf eine ControlCallback-Funktion , die eine Benachrichtigung empfängt, wenn der Anbieter durch eine Ereignisablaufverfolgungssitzung aktiviert oder deaktiviert wird. Die EnableTrace-Funktion löst diesen Rückruf aus.

[in] RequestContext

Zeiger auf einen optionalen vom Anbieter definierten Kontext, den ETW an die von RequestAddress angegebene Funktion übergibt.

[in] ControlGuid

Steuerungs-GUID (Anbieter-ID) des registrierenden Anbieters.

[in] GuidCount

Anzahl der Elemente im TraceGuidReg-Array . Wenn TraceGuidRegNULL ist, legen Sie diesen Parameter auf 0 fest.

[in, out] TraceGuidReg

Zeiger auf ein Array von
TRACE_GUID_REGISTRATION Strukturen.

Jedes Element identifiziert eine Kategorie von Ereignissen, die der Anbieter bereitstellt.

Bei der Eingabe enthält das Guid-Element jeder Struktur eine vom registrierenden Anbieter zugewiesene Ereignisablaufverfolgungsklassen-GUID. Die Klassen-GUID identifiziert eine Kategorie von Ereignissen, die der Anbieter bereitstellt. Anbieter verwenden dieselbe Klassen-GUID, um den Guid-Member von EVENT_TRACE_HEADER festzulegen, wenn die TraceEvent-Funktion zum Protokollieren des Ereignisses aufgerufen wird.

Bei der Ausgabe empfängt das RegHandle-Element ein Handle für die GUID-Registrierung des Ereignisses. Wenn der Anbieter die TraceEventInstance-Funktion aufruft , verwenden Sie das RegHandle-Element von TRACE_GUID_REGISTRATION , um das RegHandle-Element von EVENT_INSTANCE_HEADER festzulegen.

Dieser Parameter kann NULL sein, wenn der Anbieter nur die TraceEvent-Funktion aufruft, um Ereignisse zu protokollieren. Wenn der Anbieter die TraceEventInstance-Funktion aufruft , um Ereignisse zu protokollieren, kann dieser Parameter nicht NULL sein.

[in] MofImagePath

Dieser Parameter wird nicht unterstützt. Auf NULL festgelegt. Sie sollten Mofcomp.exe verwenden, um die MOF-Ressource während der Einrichtung Ihrer Anwendung zu registrieren. Weitere Informationen finden Sie unter Veröffentlichen Ihres Ereignisschemas.

Windows XP mit SP1, Windows XP und Windows 2000: Zeiger auf eine optionale Zeichenfolge, die den Pfad der DLL oder des ausführbaren Programms angibt, das die durch MofResourceName angegebene Ressource enthält. Dieser Parameter kann NULL sein, wenn der Ereignisanbieter und der Consumer einen anderen Mechanismus verwenden, um Informationen zu den vom Anbieter verwendeten Ereignisablaufverfolgungsklassen gemeinsam zu nutzen.

[in] MofResourceName

Dieser Parameter wird nicht unterstützt. Auf NULL festgelegt. Sie sollten Mofcomp.exe verwenden, um die MOF-Ressource während der Einrichtung Ihrer Anwendung zu registrieren. Weitere Informationen finden Sie unter Veröffentlichen Ihres Ereignisschemas.

Windows XP mit SP1, Windows XP und Windows 2000: Zeiger auf eine optionale Zeichenfolge, die die Zeichenfolgenressource von MofImagePath angibt. Die Zeichenfolgenressource enthält den Namen der binären MOF-Datei, die die vom Anbieter unterstützten Ereignisablaufverfolgungsklassen beschreibt.

[out] RegistrationHandle

Empfängt das Registrierungshandle des Anbieters. Verwenden Sie das zurückgegebene Handle, wenn Sie die UnregisterTraceGuids-Funktion aufrufen.

Wichtig

Alle von einer DLL oder einem Treiber erstellten Registrierungshandles müssen vor dem Entladen der DLL oder des Treibers nicht registriert werden. Wenn die Registrierung des Anbieters nicht aufgehoben wird, tritt ein Absturz auf, wenn ETW versucht, den Rückruf des Anbieters aufzurufen.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS.

Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der Systemfehlercodes. Im Folgenden finden Sie einige häufige Fehler und deren Ursachen.

Wichtig

 Diese Funktion kann auch den von ControlCallback zurückgegebenen Wert zurückgeben, wenn ein Controller EnableTrace aufruft , um den Anbieter zu aktivieren und der Anbieter noch nicht RegisterTraceGuids aufgerufen hat. In diesem Fall gibt RegisterTraceGuids den Rückgabewert des Rückrufs zurück, wenn die Registrierung erfolgreich war.

  • ERROR_INVALID_PARAMETER

    Es trifft eine der folgenden Bedingungen zu:

    • RequestAddress ist NULL.
    • ControlGuid ist NULL.
    • RegistrationHandle ist NULL.

    Windows XP und Windows 2000:TraceGuidReg ist NULL oder GuidCount ist kleiner oder gleich Null.

Hinweise

Hinweis

Die meisten Entwickler rufen diese Funktion nicht direkt auf. Stattdessen verwenden Entwickler in der Regel ein ETW-Framework. Beispielsweise verwaltet das TMF-basierte WPP die Aufrufe von RegisterTraceGuids, TraceMessage und UnregisterTraceGuids in Ihrem Namen.

Diese Funktion öffnet ein Ereignisanbieterhandle im klassischen Stil (Windows 2000), das zum Schreiben von MOF- und TMF-basierten WPP ETW-Ereignissen über TraceEvent, TraceEventInstance, TraceMessage und TraceMessageVa verwendet werden kann.

Hinweis

Verwenden Sie EventRegister, um ein Anbieterhandle im Windows Vista-Stil zu öffnen, das manifestbasierte ETW-Ereignisse oder TraceLogging-basierte ETW-Ereignisse über EventWrite schreibt.

Wenn die ControlGuid des Anbieters zuvor registriert und aktiviert wurde, werden nachfolgende Registrierungen, die auf dieselbe ControlGuid verweisen, automatisch aktiviert.

Ein Prozess kann bis zu 1.024 Anbieter-GUIDs registrieren. Sie sollten jedoch die Anzahl der Anbieter, die Ihr Prozess registriert, auf einen oder zwei beschränken. Dieser Grenzwert gilt für diejenigen, die mit dieser Funktion und der EventRegister-Funktion registriert wurden.

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

Beispiele

Ein Beispiel, das RegisterTraceGuids verwendet, finden Sie unter Schreiben klassischer Ereignisse.

Hinweis

Der evntrace.h-Header definiert RegisterTraceGuids als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows 2000 Professional [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile evntrace.h
Bibliothek Sechost.lib unter Windows 8.1 und Windows Server 2012 R2; Advapi32.lib unter Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista und Windows XP
DLL Sechost.dll unter Windows 8.1 und Windows Server 2012 R2; Advapi32.dll unter Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista und Windows XP

Weitere Informationen

EnableTrace

UnregisterTraceGuids