UpdateTraceW-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 UpdateTraceW(
CONTROLTRACE_ID TraceId,
LPCWSTR InstanceName,
PEVENT_TRACE_PROPERTIES Properties
);
Parameter
TraceId
InstanceName
Name der zu aktualisierenden Ereignisablaufverfolgungssitzung oder NULL. Sie müssen InstanceName angeben, wenn TraceHandle den Wert 0 hat.
Um die NT Kernel Logger-Sitzung 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 dazu, welche Eigenschaften 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
Der BufferSize-Member des Wnode-Elements von Properties gibt eine falsche Größe an.
ERROR_INVALID_PARAMETER
Es trifft eine der folgenden Bedingungen zu:
- Eigenschaften sind NULL.
- InstanceName und TraceHandle sind beide 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 dieses Element 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 Zeit ändern möchten, um vor dem Leeren von Puffern zu warten. 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 null 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. Um echtzeitaufwendig zu deaktivieren, legen Sie dieses Element auf 0 fest. Um echtzeitaufwendig zu aktivieren, legen Sie dieses Element auf EVENT_TRACE_REAL_TIME_MODE fest, und es wird MIT den aktuellen Modi als OR'd festgelegt.
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 Membern nur Wnode.BufferSize, Wnode.Guid und Wnode.Flags angeben.
Wenn Sie die an StartTrace übergebene Eigenschaftenstruktur verwenden, 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 zum Aktualisieren der Sitzung zu aktualisieren, stellen Sie sicher, dass Sie LogFileNameOffset auf 0 festlegen (es sei denn, Sie ändern den Protokolldateinamen), und legen Sie EVENT_TRACE_PROPERTIES fest. Wnode.Flags für WNODE_FLAG_TRACED_GUID.
Rufen Sie die ControlTrace-Funktion auf, um die Eigenschafteneinstellungen und Sitzungsstatistiken für eine Ereignisablaufverfolgungssitzung abzurufen.
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 Code, der nicht Codierungsneutral ist, 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 |