Fungsi EvtFormatMessage (winevt.h)

Artikel
08/27/2023

Memformat string pesan.

Sintaks

BOOL EvtFormatMessage(
  [in]  EVT_HANDLE   PublisherMetadata,
  [in]  EVT_HANDLE   Event,
  [in]  DWORD        MessageId,
  [in]  DWORD        ValueCount,
  [in]  PEVT_VARIANT Values,
  [in]  DWORD        Flags,
  [in]  DWORD        BufferSize,
  [in]  LPWSTR       Buffer,
  [out] PDWORD       BufferUsed
);

Parameter

[in] PublisherMetadata

Handel ke metadata penyedia yang dikembalikan fungsi EvtOpenPublisherMetadata . Handel bertindak sebagai konteks pemformatan untuk pengidentifikasi peristiwa atau pesan.

Anda dapat mengatur parameter ini ke NULL jika layanan Windows Event Collector meneruskan peristiwa. Peristiwa yang diteruskan mencakup bagian RenderingInfo yang berisi string pesan yang dirender. Anda juga dapat mengatur parameter ini ke NULL jika properti peristiwa yang Anda format ditentukan dalam file Winmeta.xml (misalnya, jika tingkat diatur ke win:Error). Dalam kasus terakhir, layanan menggunakan penyedia Winmeta sebagai konteks pemformatan dan hanya akan memformat string pesan yang Anda referensikan dalam peristiwa Anda yang ditentukan dalam file Winmeta.xml.

[in] Event

Handel ke peristiwa. Parameter Bendera menentukan string pesan jika Anda ingin memformatnya. Parameter ini harus NULL jika parameter Flags diatur ke EvtFormatMessageId.

[in] MessageId

Pengidentifikasi sumber daya string pesan yang ingin Anda format. Untuk mendapatkan pengidentifikasi sumber daya untuk string pesan, panggil fungsi GetPublisherMetadataProperty . Atur parameter ini hanya jika parameter Bendera diatur ke EvtFormatMessageId.

[in] ValueCount

Jumlah nilai dalam parameter Nilai .

[in] Values

Array nilai penyisipan yang akan digunakan saat memformat string pesan peristiwa. Biasanya, Anda mengatur parameter ini ke NULL dan fungsi mendapatkan nilai penyisipan dari data peristiwa itu sendiri. Anda akan menggunakan parameter ini untuk mengambil alih perilaku default dan menyediakan nilai penyisipan untuk digunakan. Misalnya, Anda dapat menggunakan parameter ini jika Anda ingin menyelesaikan SID ke nama utama sebelum menyisipkan nilai.

Untuk mengganti nilai penyisipan, parameter Bendera harus diatur ke EvtFormatMessageEvent, EvtFormatMessageXML, atau EvtFormatMessageId. Jika Bendera diatur ke EvtFormatMessageId, pengidentifikasi sumber daya harus mengidentifikasi string pesan peristiwa.

[in] Flags

Bendera yang menentukan string pesan dalam peristiwa untuk diformat. Untuk nilai yang mungkin, lihat enumerasi EVT_FORMAT_MESSAGE_FLAGS .

[in] BufferSize

Ukuran buffer Buffer , dalam karakter.

[in] Buffer

Buffer yang dialokasikan penelepon yang akan menerima string pesan yang diformat. Anda dapat mengatur parameter ini ke NULL untuk menentukan ukuran buffer yang diperlukan.

[out] BufferUsed

Ukuran, dalam karakter buffer yang dialokasikan pemanggil yang digunakan fungsi atau ukuran buffer yang diperlukan jika fungsi gagal dengan ERROR_INSUFFICIENT_BUFFER.

Mengembalikan nilai

Mengembalikan kode/nilai	Deskripsi
TRUE	Fungsi berhasil.
FALSE	Fungsi gagal. Panggil fungsi GetLastError untuk mendapatkan kode kesalahan.

Keterangan

Saat layanan mencoba menemukan pesan untuk suatu peristiwa, layanan akan melihat sumber daya tabel pesan penerbit yang ditunjukkan oleh parameter PublisherMetadata . Setelah ID pesan ditemukan, algoritma pencarian berikut digunakan.

Untuk pesan peristiwa:

Cari file yang ditentukan dalam atribut messageFileName dari elemen penyedia .
Jika tidak ditemukan, cari pesan sistem.

Untuk atribut Level, Opcode, dan Keyword dari elemen peristiwa :

Cari sumber daya penyedia Winmeta.
Cari file yang ditentukan dalam atribut messageFileName dari elemen penyedia .

Untuk atribut Tugas dari elemen peristiwa :

Cari file yang ditentukan dalam atribut messageFileName dari elemen penyedia .
Jika tidak ditemukan, cari sumber daya penyedia Winmeta.

Untuk parameter yang dapat dilokalkan yang dirujuk sebagai %%n (di mana n adalah ID pesan) dalam pesan peristiwa:

File pencarian tercantum dalam atribut parameterFileName dari elemen penyedia dari kiri ke kanan.
Jika tidak ditemukan, cari pesan sistem.

Contoh

Untuk contoh yang memperlihatkan cara menggunakan fungsi ini, lihat Memformat Pesan Peristiwa dan Mendapatkan Metadata Penyedia.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	winevt.h
Pustaka	Wevtapi.lib
DLL	Wevtapi.dll

Lihat juga

FormatMessage

Bagikan melalui