Bagikan melalui

Fungsi TraceMessageVa (evntrace.h)

  • Artikel

Penyedia peristiwa berbasis RegisterTraceGuids ("Klasik") menggunakan fungsi TraceMessageVa untuk mengirim peristiwa berbasis pesan (WPP berbasis TMF) ke sesi pelacakan peristiwa menggunakan parameter va_list.

Sintaks

ULONG TraceMessageVa(
  [in] TRACEHANDLE LoggerHandle,
  [in] ULONG       MessageFlags,
  [in] LPCGUID     MessageGuid,
  [in] USHORT      MessageNumber,
  [in] va_list     MessageArgList
);

Parameter

[in] LoggerHandle

Tangani ke sesi pelacakan peristiwa yang merekam peristiwa. Penyedia memperoleh handel ketika memanggil fungsi GetTraceLoggerHandle dalam implementasi ControlCallback-nya .

[in] MessageFlags

Menambahkan informasi tambahan ke awal bagian data khusus penyedia dari peristiwa. Bagian data khusus penyedia dari peristiwa hanya akan berisi data untuk bendera yang ditetapkan. Daftar variabel data argumen akan mengikuti informasi ini. Parameter ini bisa menjadi satu atau beberapa nilai berikut.

  • TRACE_MESSAGE_GUID: Sertakan GUID kelas pelacakan peristiwa dalam pesan. Parameter MessageGuid berisi GUID kelas pelacakan peristiwa.

  • TRACE_MESSAGE_SEQUENCE: Sertakan nomor urut dalam pesan. Nomor urut dimulai dari satu. Untuk menggunakan bendera ini, pengontrol harus mengatur mode file log EVENT_TRACE_USE_GLOBAL_SEQUENCE atau EVENT_TRACE_USE_LOCAL_SEQUENCE saat membuat sesi.

  • TRACE_MESSAGE_SYSTEMINFO: Sertakan pengidentifikasi utas dan pengidentifikasi proses dalam pesan.

  • TRACE_MESSAGE_TIMESTAMP: Sertakan stempel waktu dalam pesan.

Informasi disertakan dalam data peristiwa dalam urutan berikut:

  • Nomor urut
  • GUID kelas pelacakan peristiwa
  • Stempel waktu
  • Pengidentifikasi utas
  • Pengidentifikasi proses

[in] MessageGuid

GUID kelas yang mengidentifikasi pesan pelacakan peristiwa.

[in] MessageNumber

Angka yang secara unik mengidentifikasi setiap kemunculan pesan. Anda harus menentukan nilai yang ditentukan untuk parameter ini; nilai harus bermakna bagi aplikasi.

[in] MessageArgList

Daftar argumen variabel yang akan ditambahkan ke pesan. Daftar harus terdiri dari pasangan argumen, sebagai berikut.

  • PVOID: Penunjuk ke data argumen.
  • size_t: Ukuran data argumen, dalam byte.

Hentikan daftar menggunakan pasangan argumen yang terdiri dari pointer ke NULL dan nol.

Pemanggil harus memastikan bahwa jumlah ukuran argumen + 72 tidak melebihi ukuran buffer sesi pelacakan peristiwa.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah 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_HANDLE

    Baik LoggerHandle adalah NULL atau menentukan handel sesi NT Kernel Logger.

  • ERROR_NOT_ENOUGH_MEMORY

    Sesi kehabisan buffer gratis untuk ditulis. Ini dapat terjadi selama tingkat peristiwa tinggi karena subsistem disk kelebihan beban atau jumlah buffer terlalu kecil. Daripada memblokir hingga lebih banyak buffer tersedia, TraceMessage membuang peristiwa.

    Windows 2000 dan Windows XP: Tidak didukung.

  • ERROR_OUTOFMEMORY

    Kejadian ini dibuang karena, meskipun kumpulan buffer belum mencapai ukuran maksimumnya, memori yang tersedia tidak cukup untuk mengalokasikan buffer tambahan dan tidak ada buffer yang tersedia untuk menerima acara.

  • ERROR_INVALID_PARAMETER

    MessageFlags berisi nilai yang tidak valid.

  • ERROR_MORE_DATA

    Data dari satu peristiwa tidak dapat menjangkau beberapa buffer. Peristiwa pelacakan terbatas pada ukuran buffer sesi pelacakan peristiwa dikurangi ukuran struktur EVENT_TRACE_HEADER .

Keterangan

Penyedia WPP berbasis TMF memanggil fungsi ini.

Catatan

Sebagian besar pengembang tidak akan memanggil fungsi ini secara langsung. Penyedia WPP menggunakan fungsi pembungkus yang dihasilkan oleh tracewpp.exe alih-alih memanggil API ETW.

Jika Anda tidak perlu mengakses fungsionalitas pelacakan pesan dari fungsi pembungkus, Anda dapat memanggil versi TraceMessage dari fungsi ini.

Konsumen harus menggunakan panggilan balik EventCallback untuk menerima dan memproses peristiwa jika parameter MessageFlags tidak berisi bendera TRACE_MESSAGE_GUID. Jika Anda tidak menentukan bendera TRACE_MESSAGE_GUID, konsumen tidak akan dapat menggunakan EventClassCallback karena anggota Header.Guid dari struktur EVENT_TRACE tidak akan berisi GUID kelas pelacakan peristiwa.

Perhatikan bahwa anggota struktur EVENT_TRACE dan EVENT_TRACE_HEADER yang sesuai dengan bendera MessageFlags diatur hanya jika bendera yang sesuai ditentukan. Misalnya, anggota ThreadId dan ProcessIdEVENT_TRACE_HEADER diisi hanya jika Anda menentukan bendera TRACE_MESSAGE_SYSTEMINFO.

Persyaratan

   
Klien minimum yang didukung Windows XP [hanya aplikasi desktop]
Server minimum yang didukung Windows Server 2003 [hanya aplikasi desktop]
Target Platform Windows
Header evntrace.h
Pustaka Advapi32.lib
DLL Advapi32.dll

Lihat juga

TraceEvent

TraceEventInstance

TraceMessage