Bagikan melalui

Fungsi UpdateTraceA (evntrace.h)

  • Artikel

Fungsi UpdateTrace memperbarui pengaturan properti dari sesi pelacakan peristiwa yang ditentukan.

Fungsi ini usang. Fungsi ControlTrace menggantikan fungsi ini.

Sintaks

ULONG WMIAPI UpdateTraceA(
  CONTROLTRACE_ID         TraceId,
  LPCSTR                  InstanceName,
  PEVENT_TRACE_PROPERTIES Properties
);

Parameter

TraceId

InstanceName

Nama sesi pelacakan peristiwa yang akan diperbarui, atau NULL. Anda harus menentukan InstanceName jika TraceHandle adalah 0.

Untuk menentukan sesi NT Kernel Logger, atur InstanceName ke KERNEL_LOGGER_NAME.

Properties

Penunjuk ke struktur EVENT_TRACE_PROPERTIES yang diinisialisasi.

Pada input, anggota harus menentukan nilai baru untuk properti yang akan diperbarui. Untuk informasi tentang properti mana yang dapat Anda perbarui, lihat Keterangan.

Pada output, anggota struktur berisi pengaturan dan statistik yang diperbarui untuk sesi pelacakan peristiwa.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan ERROR_SUCCESS.

Jika fungsi gagal, nilai yang dikembalikan adalah salah satu kode kesalahan sistem. Tabel berikut ini mencakup beberapa kesalahan umum dan penyebabnya.

  • ERROR_BAD_LENGTH

    Anggota BufferSize dari anggota WnodeProperti menentukan ukuran yang salah.

  • ERROR_INVALID_PARAMETER

    Salah satu hal berikut ini benar:

    • Properti adalah NULL.
    • InstanceName dan TraceHandle keduanya NULL.
    • InstanceName adalah NULL dan TraceHandle bukan handel yang valid.
    • Anggota LogFileNameOffsetproperti tidak valid.
    • Anggota LoggerNameOffsetproperti tidak valid.

    Windows Server 2003 dan Windows XP: Anggota Guid dari struktur Wnode adalah SystemTraceControlGuid, tetapi parameter InstanceName tidak KERNEL_LOGGER_NAME.

  • ERROR_ACCESS_DENIED

    Hanya pengguna dengan hak istimewa administratif, pengguna di grup Pengguna Log Performa, dan layanan yang berjalan sebagai LocalSystem, LocalService, NetworkService yang dapat mengontrol sesi pelacakan peristiwa. Untuk memberi pengguna terbatas kemampuan untuk mengontrol sesi pelacakan, tambahkan mereka ke grup Pengguna Log Performa.

    Windows XP dan Windows 2000: Siapa pun dapat mengontrol sesi pelacakan.

Keterangan

Pengontrol pelacakan peristiwa memanggil fungsi ini.

Fungsi ini usang. Sebagai gantinya, gunakan ControlTrace dengan ControlCode diatur ke EVENT_TRACE_CONTROL_UPDATE.

Pada input, anggota harus menentukan nilai baru untuk properti yang akan diperbarui. Anda bisa memperbarui properti berikut ini.

  • EnableFlags: Atur anggota ini ke 0 untuk menonaktifkan semua penyedia kernel. Jika tidak, Anda harus menentukan penyedia kernel yang ingin Anda aktifkan atau tetap aktifkan. Hanya berlaku untuk sesi pencatat sistem.

  • FlushTimer: Atur anggota ini jika Anda ingin mengubah waktu untuk menunggu sebelum membersihkan buffer. Jika anggota ini adalah 0, anggota tidak diperbarui.

  • LogFileNameOffset: Atur anggota ini jika Anda ingin beralih ke file log lain. Jika anggota ini adalah 0, nama file tidak diperbarui. Jika offset bukan nol dan Anda tidak mengubah nama file log, fungsi mengembalikan kesalahan.

  • LogFileMode: Atur anggota ini jika Anda ingin mengaktifkan dan menonaktifkan EVENT_TRACE_REAL_TIME_MODE . Untuk menonaktifkan penggunaan real time, atur anggota ini ke 0. Untuk mengaktifkan penggunaan real time, atur anggota ini ke EVENT_TRACE_REAL_TIME_MODE dan itu akan or'd dengan mode saat ini.

  • MaximumBuffers: Atur anggota ini jika Anda ingin mengubah jumlah maksimum buffer yang digunakan ETW. Jika anggota ini adalah 0, anggota tidak diperbarui.

Untuk sesi pencatat privat, Anda hanya dapat memperbarui LogFileNameOffset dan FlushTimer.

Jika Anda menggunakan struktur EVENT_TRACE_PROPERTIES yang baru diinisialisasi, satu-satunya anggota yang perlu Anda tentukan, selain anggota yang Anda perbarui, adalah Wnode.BufferSize, Wnode.Guid, dan Wnode.Flags.

Jika Anda menggunakan struktur properti yang Anda berikan ke StartTrace, pastikan anggota LogFileNameOffset adalah 0 kecuali Anda mengubah nama file log.

Jika Anda memanggil fungsi ControlTrace untuk mengkueri properti sesi saat ini lalu memperbarui properti tersebut untuk memperbarui sesi, pastikan Anda mengatur LogFileNameOffset ke 0 (kecuali Anda mengubah nama file log) dan mengatur EVENT_TRACE_PROPERTIES. Wnode.Flags ke WNODE_FLAG_TRACED_GUID.

Untuk mendapatkan pengaturan properti dan statistik sesi untuk sesi pelacakan peristiwa, panggil fungsi ControlTrace .

Contoh

Untuk contoh yang menggunakan UpdateTrace, lihat Memperbarui Sesi Pelacakan Peristiwa.

Catatan

Header evntrace.h mendefinisikan UpdateTrace sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung Windows 2000 Server [hanya aplikasi desktop]
Target Platform Windows
Header evntrace.h
Pustaka Advapi32.lib
DLL Advapi32.dll

Lihat juga

ControlTrace