RegisterTraceGuidsA-Funktion (evntrace.h)

Die RegisterTraceGuids--Funktion registriert einen Klassischen (Windows 2000-Stil) ETW-Ereignisablaufverfolgungsanbieter 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]     TRACEGUID_HANDLE         *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 durch RequestAddressangegebene Funktion übergibt.

[in] ControlGuid

Steuern der GUID (Anbieter-ID) des Registrierensanbieters.

[in] GuidCount

Anzahl der Elemente im TraceGuidReg Array. Wenn TraceGuidReg-NULL-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 eingaben enthält das Guid Member jeder Struktur eine vom Registrierenanbieter 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- Mitglied ein Handle für die Klassen-GUID-Registrierung des Ereignisses. Wenn der Anbieter die TraceEventInstance--Funktion aufruft, verwenden Sie das RegHandle- Mitglied der TRACE_GUID_REGISTRATION, um das RegHandle- Mitglied von EVENT_INSTANCE_HEADERfestzulegen.

Dieser Parameter kann NULL- werden, 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-werden.

[in] MofImagePath

Dieser Parameter wird nicht unterstützt. Wird auf NULL-festgelegt. Sie sollten Mofcomp.exe verwenden, um die MOF-Ressource während des Setups Ihrer Anwendung zu registrieren. Weitere Informationen finden Sie unter Veröffentlichen des 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, die die durch MofResourceNameangegebene Ressource enthält. Dieser Parameter kann NULL- werden, wenn der Ereignisanbieter und der Consumer einen anderen Mechanismus verwenden, um Informationen zu den vom Anbieter verwendeten Ereignisablaufverfolgungsklassen zu teilen.

[in] MofResourceName

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

Windows XP mit SP1, Windows XP und Windows 2000: Zeiger auf eine optionale Zeichenfolge, die die Zeichenfolgenressource von MofImagePathangibt. 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.

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.

• ERROR_INVALID_PARAMETER

  Eine der folgenden Punkte ist wahr:

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

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

Bemerkungen

Diese Funktion öffnet ein Classic (Windows 2000-Style)-Ereignisanbieterhandle, das zum Schreiben von MOF- und TMF-basierten WPP ETW-Ereignissen über TraceEvent-, TraceEventInstance, TraceMessageund TraceMessageVaverwendet werden kann.

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

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

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

Beispiele

Ein Beispiel, das RegisterTraceGuidsverwendet, finden Sie unter Writing Classic Events.

Anforderungen

Siehe auch

EnableTrace-

UnregisterTraceGuids-