Bagikan melalui

Fungsi TraceMessage (evntrace.h)

  • Artikel

Penyedia acara berbasis RegisterTraceGuids ("Klasik") menggunakan fungsi TraceMessage untuk mengirim peristiwa berbasis pesan (WPP berbasis TMF) ke sesi pelacakan peristiwa.

Sintaks

ULONG TraceMessage(
  [in] TRACEHANDLE LoggerHandle,
  [in] ULONG       MessageFlags,
  [in] LPCGUID     MessageGuid,
  [in] USHORT      MessageNumber,
       ...         
);

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_COMPONENTID

    Sertakan pengidentifikasi komponen dalam pesan. Parameter MessageGuid berisi pengidentifikasi komponen.

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

TRACE_MESSAGE_COMPONENTID dan TRACE_MESSAGE_GUID saling eksklusif.

Informasi disertakan dalam data peristiwa dalam urutan berikut:

  • Nomor urut
  • GUID kelas pelacakan peristiwa (atau pengidentifikasi komponen)
  • Stempel waktu
  • Pengidentifikasi utas
  • Pengidentifikasi proses

[in] MessageGuid

GUID kelas atau ID komponen yang mengidentifikasi pesan. Tergantung apakah MessageFlags berisi bendera TRACE_MESSAGE_COMPONENTID atau TRACE_MESSAGE_GUID .

[in] MessageNumber

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

...

Daftar argumen variabel yang akan ditambahkan ke pesan. Gunakan daftar ini untuk menentukan data peristiwa khusus penyedia Anda. 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. Berikut ini adalah 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 perlu mengakses fungsionalitas pelacakan pesan dari fungsi pembungkus, panggil versi TraceMessageVa 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 [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

TraceEvent

TraceEventInstance

TraceMessageVa