Bagikan melalui

Fungsi FlushTraceW (evntrace.h)

  • Artikel

Fungsi FlushTrace menyebabkan sesi pelacakan peristiwa segera mengirimkan peristiwa buffer untuk sesi yang ditentukan. Secara default, sesi pelacakan peristiwa akan mengirimkan peristiwa ketika buffer penuh, FlushTimer sesi kedaluwarsa, atau sesi ditutup.

Fungsi ini usang. Fungsi ControlTrace menggantikan fungsi ini.

Sintaks

ULONG WMIAPI FlushTraceW(
            CONTROLTRACE_ID         TraceId,
  [in]      LPCWSTR                 InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

Parameter

TraceId

[in] InstanceName

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

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

[in, out] Properties

Penunjuk ke struktur EVENT_TRACE_PROPERTIES yang diinisialisasi.

Jika Anda menggunakan struktur yang baru diinisialisasi, Anda hanya perlu mengatur anggota Wnode.BufferSize, Wnode.Guid, LoggerNameOffset, dan LogFileNameOffset dari struktur. Anda dapat menggunakan nama sesi maksimum (1024 karakter) dan panjang nama file log maksimum (1024 karakter) untuk menghitung ukuran buffer dan offset jika tidak diketahui.

Pada output, struktur menerima pengaturan properti dan statistik sesi sesi pelacakan peristiwa, yang mencerminkan status sesi setelah flush.

Mengembalikan nilai

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_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.

  • ERROR_BAD_LENGTH

    Salah satu hal berikut ini benar:

    • Anggota Properti Wnode.BufferSizemenentukan ukuran yang salah.
    • Properti tidak memiliki cukup ruang yang dialokasikan untuk menyimpan salinan nama sesi dan nama file log (jika digunakan).

  • 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_FLUSH.

Fungsi ini dapat digunakan dengan sesi dalam memori (sesi yang dimulai dengan bendera EVENT_TRACE_BUFFERING_MODE ) untuk menulis data dari jejak ke file.

Anda biasanya tidak perlu menghapus sesi berbasis file atau real-time karena ETW akan secara otomatis membersihkan buffer ketika penuh (yaitu ketika tidak memiliki ruang untuk peristiwa berikutnya), ketika FlushTimer sesi pelacakan kedaluwarsa, atau ketika sesi pelacakan ditutup.

Jangan panggil FlushTrace dari DllMain (dapat menyebabkan kebuntuan).

Catatan

Header evntrace.h mendefinisikan FlushTrace 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 XP [aplikasi desktop | Aplikasi UWP]
Server minimum yang didukung Windows Server 2003 [aplikasi desktop | Aplikasi UWP]
Target Platform Windows
Header evntrace.h
Pustaka Advapi32.lib
DLL Advapi32.dll

Lihat juga

ControlTrace