EnableTrace-Funktion (evntrace.h)

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

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

Syntax

ULONG WMIAPI EnableTrace(
  [in] ULONG       Enable,
  [in] ULONG       EnableFlag,
  [in] ULONG       EnableLevel,
  [in] LPCGUID     ControlGuid,
  [in] TRACEHANDLE TraceHandle
);

Parameter

[in] Enable

Legen Sie diese Einstellung 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üsselwort (keyword) Bits des Ereignisses mit einem der in diesem Wert festgelegten Bits übereinstimmen oder wenn für das Ereignis keine Schlüsselwort (keyword) Bits festgelegt sind, zusätzlich zur Erfüllung 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 Ebene von Ereignissen 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 von 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 schwerwiegenderen 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 fehlerbezogene Informationsereignisse
TRACE_LEVEL_VERBOSE (5)	Detaillierte Diagnoseereignisse

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

[in] ControlGuid

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

[in] TraceHandle

Handle der Ereignisablaufverfolgungssitzung, für die Sie den Anbieter konfigurieren. Die StartTrace-Funktion gibt dieses Handle zurück, wenn eine neue Ablaufverfolgung gestartet wird. Um das Handle einer vorhandenen Ablaufverfolgung abzurufen, verwenden Sie ControlTrace , um die Ablaufverfolgungseigenschaften basierend auf dem Namen der Ablaufverfolgung abzufragen und dann das Handle aus dem Wnode.HistoricalContext-Feld der zurückgegebenen EVENT_TRACE_PROPERTIES Daten abzurufen.

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

  Es trifft eine der folgenden Bedingungen zu:

  • ControlGuid ist NULL.
  • TraceHandle ist NULL.

• ERROR_INVALID_FUNCTION

  Sie können die Aktivierungsflags und den Level 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 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 lesen Sie EventAccessControl.

  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 dem Sammeln von Ereignissen von einem Anbieter zu beginnen, die Ebene oder schlüsselwörter der ereignisse anzupassen, die von einem Anbieter erfasst werden, oder um das Sammeln von Ereignissen von einem Anbieter zu beenden.

Diese Funktion ist veraltet. Für zusätzliche Funktionen sollte für neuen Code EnableTraceEx2 verwendet werden.

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 Informationen zur Semantik der Konfiguration von Anbietern für eine Sitzung finden Sie in der Dokumentation zu EnableTraceEx2.

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

Weitere Informationen

StartTrace

EnableTraceEx2