EnableTrace-Funktion (evntrace.h)

Artikel
06/12/2024

Ein Ablaufverfolgungssitzungscontroller ruft EnableTrace auf, um zu konfigurieren, wie ein ETW-Ereignisanbieter Ereignisse in einer Ablaufverfolgungssitzung protokolliert.

Diese Funktion ist veraltet. Die Funktion EnableTraceEx2 ersetzt diese Funktion.

Syntax

ULONG WMIAPI EnableTrace(
  [in] ULONG           Enable,
  [in] ULONG           EnableFlag,
  [in] ULONG           EnableLevel,
  [in] LPCGUID         ControlGuid,
       CONTROLTRACE_ID TraceId
);

Parameter

[in] Enable

Legen Sie auf 1 fest, um den Empfang von Ereignissen vom Anbieter zu aktivieren oder die Einstellungen anzupassen, die beim Empfangen von Ereignissen vom Anbieter verwendet werden (z. B. zum Ändern der Ebene und der Schlüsselwörter). Legen Sie auf 0 fest, um den Empfang von Ereignissen vom Anbieter zu deaktivieren.

[in] EnableFlag

32-Bit-Bit-Bitmaske von Schlüsselwörtern, die die Kategorien von Ereignissen bestimmen, die der Anbieter schreiben soll. Der Anbieter schreibt in der Regel ein Ereignis, wenn die Schlüsselwortbits des Ereignisses mit einem der in diesem Wert festgelegten Bits übereinstimmen oder wenn für das Ereignis keine Schlüsselwortbits festgelegt sind, zusätzlich zum Erfüllen der EnableLevel-Critera .

Hinweis

EventRegister-basierte Anbieter unterstützen 64-Bit-Schlüsselwörter. Verwenden Sie EnableTraceEx2, um Anbieter mit einer 64-Bit-MatchAnyKeyword-Maske zu aktivieren.

[in] EnableLevel

Ein Wert, der die maximale Ereignisebene angibt, die der Anbieter schreiben soll. Der Anbieter schreibt in der Regel ein Ereignis, wenn die Ebene des Ereignisses kleiner oder gleich diesem Wert ist, zusätzlich zur Erfüllung der EnableFlag-Kriterien .

Dieser Wert sollte im Bereich 1 bis 255 liegen. Microsoft definiert die Semantik der Ebenen 1 bis 5, wie unten gezeigt. Niedrigere Werte weisen auf schwerwiegendere Ereignisse hin. Jeder Wert von EnableLevel aktiviert die angegebene Ebene und alle schwereren Ebenen. Wenn Sie beispielsweise angeben TRACE_LEVEL_WARNING, erhält Ihr Consumer Warnungen, Fehler und kritische Ereignisse.

Wert	Bedeutung
TRACE_LEVEL_CRITICAL (1)	Ungewöhnliche Beendigungs- oder Beendigungsereignisse
TRACE_LEVEL_ERROR (2)	Schwerwiegende Fehlerereignisse
TRACE_LEVEL_WARNING (3)	Warnungsereignisse wie Zuordnungsfehler
TRACE_LEVEL_INFORMATION (4)	Nicht fehlerfreie Informationsereignisse
TRACE_LEVEL_VERBOSE (5)	Detaillierte Diagnoseereignisse

Die TRACE_LEVEL Konstanten sind in evntrace.h definiert. Entsprechende WINMETA_LEVEL Konstanten werden in winmeta.h definiert.

[in] ControlGuid

Die Steuerelement-GUID (Anbieter-ID) des Ereignisanbieters, den Sie aktivieren oder deaktivieren möchten.

TraceId

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.

ERROR_INVALID_PARAMETER

Es trifft eine der folgenden Bedingungen zu:
- ControlGuid ist NULL.
- TraceHandle ist NULL.
ERROR_INVALID_FUNCTION

Sie können die Aktivierungsflags und die Ebene nicht ändern, wenn der Anbieter nicht registriert ist.
ERROR_WMI_GUID_NOT_FOUND

Der Anbieter ist nicht registriert. Tritt auf, wenn KB307331 oder Windows 2000 Service Pack 4 installiert ist und der Anbieter nicht registriert ist. Um diesen Fehler zu vermeiden, muss der Anbieter zuerst registriert werden.
ERROR_NO_SYSTEM_RESOURCES

Die Anzahl der Ablaufverfolgungssitzungen, die den Anbieter aktivieren können, wurde überschritten.
ERROR_ACCESS_DENIED

Nur Benutzer mit Administratorrechten, Benutzer in der Gruppe und Dienste, die Performance Log Users als LocalSystem, LocalServiceoder NetworkService ausgeführt werden, können Ereignisanbieter für eine prozessübergreifende Sitzung aktivieren. Um einem eingeschränkten Benutzer die Möglichkeit zu gewähren, einen Ereignisanbieter zu aktivieren, fügen Sie diesen der Performance Log Users Gruppe hinzu, oder sehen Sie sich EventAccessControl an.

Windows XP und Windows 2000: Jeder kann einen Ereignisanbieter aktivieren.

Hinweise

Ereignisablaufverfolgungscontroller rufen diese Funktion auf, um die Ereignisanbieter zu konfigurieren, die Ereignisse in die Sitzung schreiben. Beispielsweise kann ein Controller diese Funktion aufrufen, um mit der Erfassung von Ereignissen von einem Anbieter zu beginnen, die Ebene oder schlüsselwörter der von einem Anbieter erfassten Ereignisse anzupassen oder um die Erfassung von Ereignissen von einem Anbieter zu beenden.

Diese Funktion ist veraltet. Für zusätzliche Funktionen sollte neuer Code EnableTraceEx2 verwenden.

Die folgenden beiden Funktionsaufrufe sind gleichwertig:

// Obsolete:
Status = EnableTrace(
    Enable,
    EnableFlag,
    EnableLevel,
    ControlGuid,
    TraceHandle);

// Updated equivalent code:
Status = EnableTraceEx2(
    TraceHandle,
    ControlGuid,
    Enable,      // ControlCode
    EnableLevel,
    EnableFlag,  // MatchAnyKeyword
    0,           // MatchAllKeyword
    0,           // Timeout
    NULL);       // EnableParameters

Weitere Details zur Semantik der Konfiguration von Anbietern für eine Sitzung finden Sie in der Dokumentation zu EnableTraceEx2.

Anforderungen

Anforderung	Wert
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	Advapi32.lib
DLL	Advapi32.dll

Weitere Informationen

StartTrace

EnableTraceEx2

Freigeben über