UpdateTraceA-Funktion (evntrace.h)

Die UpdateTrace-Funktion aktualisiert die Eigenschaftseinstellung der angegebenen Ereignisablaufverfolgungssitzung.

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

Syntax

ULONG WMIAPI UpdateTraceA(
  TRACEHANDLE             TraceHandle,
  LPCSTR                  InstanceName,
  PEVENT_TRACE_PROPERTIES Properties
);

Parameter

TraceHandle

Behandeln Sie die zu aktualisierende Ereignisablaufverfolgungssitzung oder 0. Sie müssen eine TraceHandle-Instanz ohne Null angeben, wenn InstanceNameNULL ist. Dieser Parameter wird nur verwendet, wenn InstanceNameNULL ist. Das Handle wird vom StartTrace zurückgegeben.

InstanceName

Name der zu aktualisierenden Ereignisablaufverfolgungssitzung oder NULL. Sie müssen InstanceName angeben, wenn TraceHandle 0 ist.

Um die NT-Kernelprotokollierungssitzung anzugeben, legen Sie InstanceName auf KERNEL_LOGGER_NAME fest.

Properties

Zeiger auf eine initialisierte EVENT_TRACE_PROPERTIES-Struktur .

Bei der Eingabe müssen die Member die neuen Werte für die zu aktualisierenden Eigenschaften angeben. Informationen zu den Eigenschaften, die Sie aktualisieren können, finden Sie unter Hinweise.

In der Ausgabe enthalten die Strukturmember die aktualisierten Einstellungen und Statistiken für die Ereignisablaufverfolgungssitzung.

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. Die folgende Tabelle enthält einige häufige Fehler und deren Ursachen.

• ERROR_BAD_LENGTH

  Das BufferSize-Element des Wnode-Members von Properties gibt eine falsche Größe an.

• ERROR_INVALID_PARAMETER

  Es trifft eine der folgenden Bedingungen zu:

  • Eigenschaften sind NULL.
  • InstanceName und TraceHandlesind null.
  • InstanceName ist NULL und TraceHandle ist kein gültiges Handle.
  • Das LogFileNameOffset-Element von Properties ist ungültig.
  • Das LoggerNameOffset-Element von Properties ist ungültig.

  Windows Server 2003 und Windows XP: Das Guid-Element der Wnode-Struktur ist SystemTraceControlGuid, aber der Parameter InstanceName ist nicht KERNEL_LOGGER_NAME.

• ERROR_ACCESS_DENIED

  Nur Benutzer mit Administratorrechten, Benutzer in der Gruppe Leistungsprotokollbenutzer und Dienste, die als LocalSystem, LocalService und NetworkService ausgeführt werden, können Ereignisablaufverfolgungssitzungen steuern. Um einem eingeschränkten Benutzer die Möglichkeit zu gewähren, Ablaufverfolgungssitzungen zu steuern, fügen Sie sie der Gruppe Leistungsprotokollbenutzer hinzu.

  Windows XP und Windows 2000: Jeder kann eine Ablaufverfolgungssitzung steuern.

Hinweise

Ereignisablaufverfolgungscontroller rufen diese Funktion auf.

Diese Funktion ist veraltet. Verwenden Sie stattdessen ControlTrace , wobei ControlCode auf EVENT_TRACE_CONTROL_UPDATE festgelegt ist.

Bei der Eingabe müssen die Member die neuen Werte für die zu aktualisierenden Eigenschaften angeben. Sie können die folgenden Eigenschaften aktualisieren.

• EnableFlags: Legen Sie diesen Member auf 0 fest, um alle Kernelanbieter zu deaktivieren. Andernfalls müssen Sie die Kernelanbieter angeben, die Sie aktivieren oder aktivieren möchten. Gilt nur für Systemprotokollierungssitzungen.

• FlushTimer: Legen Sie diesen Member fest, wenn Sie die Wartezeit vor dem Leeren von Puffern ändern möchten. Wenn dieser Member 0 ist, wird das Element nicht aktualisiert.

• LogFileNameOffset: Legen Sie dieses Element fest, wenn Sie zu einer anderen Protokolldatei wechseln möchten. Wenn dieser Member 0 ist, wird der Dateiname nicht aktualisiert. Wenn der Offset nicht 0 ist und Sie den Namen der Protokolldatei nicht ändern, gibt die Funktion einen Fehler zurück.

• LogFileMode: Legen Sie dieses Element fest, wenn Sie EVENT_TRACE_REAL_TIME_MODE aktivieren und deaktivieren möchten. Legen Sie dieses Element auf 0 fest, um den Echtzeitaufwand zu deaktivieren. Legen Sie dieses Element auf EVENT_TRACE_REAL_TIME_MODE fest, und es wird MIT den aktuellen Modi OR'd sein, um echtzeitaufwendig zu schalten.

• MaximumBuffers: Legen Sie diesen Member fest, wenn Sie die maximale Anzahl von Puffern ändern möchten, die ETW verwendet. Wenn dieser Member 0 ist, wird das Element nicht aktualisiert.

Für private Protokollierungssitzungen können Sie nur LogFileNameOffset und FlushTimer aktualisieren.

Wenn Sie eine neu initialisierte EVENT_TRACE_PROPERTIES Struktur verwenden, müssen Sie neben den zu aktualisierenden Elementen nur Wnode.BufferSize, Wnode.Guid und Wnode.Flags angeben.

Wenn Sie die Eigenschaftenstruktur verwenden, die Sie an StartTrace übergeben haben, stellen Sie sicher, dass das LogFileNameOffset-Element 0 ist, es sei denn, Sie ändern den Namen der Protokolldatei.

Wenn Sie die ControlTrace-Funktion aufrufen, um die aktuellen Sitzungseigenschaften abzufragen und diese Eigenschaften dann zu aktualisieren, um die Sitzung zu aktualisieren, stellen Sie Sicher, dass Sie LogFileNameOffset auf 0 festlegen (es sei denn, Sie ändern den Namen der Protokolldatei), und legen Sie EVENT_TRACE_PROPERTIES fest. Wnode.Flags to WNODE_FLAG_TRACED_GUID.

Um die Eigenschafteneinstellungen und Sitzungsstatistiken für eine Ereignisablaufverfolgungssitzung abzurufen, rufen Sie die ControlTrace-Funktion auf.

Beispiele

Ein Beispiel, das UpdateTrace verwendet, finden Sie unter Aktualisieren einer Ereignisablaufverfolgungssitzung.

Hinweis

Der evntrace.h-Header definiert UpdateTrace 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

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	evntrace.h
Bibliothek	Advapi32.lib
DLL	Advapi32.dll

Weitere Informationen

ControlTrace