RegisterTraceGuidsA-Funktion (evntrace.h)

  • Artikel

Die Funktion RegisterTraceGuids 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 RegisterTraceGuidsA(
  [in]      WMIDPREQUEST             RequestAddress,
  [in]      PVOID                    RequestContext,
  [in]      LPCGUID                  ControlGuid,
  [in]      ULONG                    GuidCount,
  [in, out] PTRACE_GUID_REGISTRATION TraceGuidReg,
  [in]      LPCSTR                   MofImagePath,
  [in]      LPCSTR                   MofResourceName,
  [out]     PTRACEHANDLE             RegistrationHandle
);

Parameter

[in] RequestAddress

Zeiger auf eine ControlCallback-Funktion , die 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

Steuern Sie die 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 Ereignisablaufverfolgungsklasse-GUID. Die Klassen-GUID identifiziert eine Kategorie von Ereignissen, die der Anbieter bereitstellt. Anbieter verwenden dieselbe Klassen-GUID, um das Guid-Element von EVENT_TRACE_HEADER festzulegen, wenn die TraceEvent-Funktion aufgerufen wird, um das Ereignis zu protokollieren.

Bei der Ausgabe empfängt das RegHandle-Element ein Handle für die GUID-Registrierung der -Klasse des Ereignisses. Wenn der Anbieter die TraceEventInstance-Funktion aufruft , verwenden Sie das RegHandle-Member von TRACE_GUID_REGISTRATION , um das RegHandle-Elementvon 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. Verwenden Sie Mofcomp.exe, 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 von MofResourceName angegebene Ressource enthält. Dieser Parameter kann NULL sein, wenn der Ereignisanbieter und der Consumer einen anderen Mechanismus verwenden, um Informationen über die vom Anbieter verwendeten Ereignisablaufverfolgungsklassen auszutauschen.

[in] MofResourceName

Dieser Parameter wird nicht unterstützt. Auf NULL festgelegt. Verwenden Sie Mofcomp.exe, 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 Funktion UnregisterTraceGuids aufrufen.

Wichtig

Alle Registrierungshandles, die von einer DLL oder einem Treiber erstellt wurden, müssen vor dem Entladen der DLL oder des Treibers aufgehoben werden. Wenn der Anbieter die Registrierung nicht aufgehoben hat, 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 sind einige häufige Fehler und deren Ursachen aufgeführt.

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 0.

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 Klassisches Ereignisanbieterhandle (Windows 2000-Format), mit dem MOF- und TMF-basierte WPP ETW-Ereignisse über TraceEvent, TraceEventInstance, TraceMessage und TraceMessageVa geschrieben werden können.

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 umfasst diejenigen, die mit dieser Funktion und der EventRegister-Funktion registriert wurden.

Vor Windows Vista: Die Anzahl der Anbieter, die ein Prozess registrieren kann, ist nicht begrenzt.

Beispiele

Ein Beispiel, das RegisterTraceGuids verwendet, finden Sie unter Schreiben von klassischen Ereignissen.

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 nicht codierungsneutralem Code 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

Aufheben der RegistrierungTraceGuids