Fungsi ReportEventA (winbase.h)

Artikel
08/27/2023

Menulis entri di akhir log peristiwa yang ditentukan.

Sintaks

BOOL ReportEventA(
  [in] HANDLE hEventLog,
  [in] WORD   wType,
  [in] WORD   wCategory,
  [in] DWORD  dwEventID,
  [in] PSID   lpUserSid,
  [in] WORD   wNumStrings,
  [in] DWORD  dwDataSize,
  [in] LPCSTR *lpStrings,
  [in] LPVOID lpRawData
);

Parameter

[in] hEventLog

Handel ke log peristiwa. Fungsi RegisterEventSource mengembalikan handel ini.

Pada Windows XP dengan SP2, parameter ini tidak dapat menjadi handel untuk log Keamanan . Untuk menulis peristiwa ke log Keamanan , gunakan fungsi AuthzReportSecurityEvent .

[in] wType

Jenis peristiwa yang akan dicatat. Parameter ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
EVENTLOG_SUCCESS 0x0000	Peristiwa informasi
EVENTLOG_AUDIT_FAILURE 0x0010	Peristiwa Audit Kegagalan
EVENTLOG_AUDIT_SUCCESS 0x0008	Peristiwa Audit Keberhasilan
EVENTLOG_ERROR_TYPE 0x0001	Peristiwa kesalahan
EVENTLOG_INFORMATION_TYPE 0x0004	Peristiwa informasi
EVENTLOG_WARNING_TYPE 0x0002	Peristiwa peringatan

Untuk informasi selengkapnya tentang jenis peristiwa, lihat Jenis Peristiwa.

[in] wCategory

Kategori peristiwa. Ini adalah informasi khusus sumber; kategori dapat memiliki nilai apa pun. Untuk informasi selengkapnya, lihat Kategori Peristiwa.

[in] dwEventID

Pengidentifikasi peristiwa. Pengidentifikasi peristiwa menentukan entri dalam file pesan yang terkait dengan sumber peristiwa. Untuk informasi selengkapnya, lihat Pengidentifikasi Peristiwa.

[in] lpUserSid

Penunjuk ke pengidentifikasi keamanan pengguna saat ini. Parameter ini dapat berupa NULL jika pengidentifikasi keamanan tidak diperlukan.

[in] wNumStrings

Jumlah string sisipan dalam array yang ditujukkan oleh parameter lpStrings . Nilai nol menunjukkan bahwa tidak ada string yang ada.

[in] dwDataSize

Jumlah byte data mentah (biner) khusus peristiwa untuk ditulis ke log. Jika parameter ini nol, tidak ada data khusus peristiwa yang ada.

[in] lpStrings

Penunjuk ke buffer yang berisi array string yang dihentikan null yang digabungkan ke dalam pesan sebelum Pemantau Peristiwa menampilkan string kepada pengguna. Parameter ini harus berupa pointer yang valid (atau NULL), bahkan jika wNumStrings adalah nol. Setiap string dibatasi hingga 31.839 karakter.

Sebelum Windows Vista: Setiap string dibatasi hingga 32K karakter.

[in] lpRawData

Penunjuk ke buffer yang berisi data biner. Parameter ini harus berupa penunjuk yang valid (atau NULL), bahkan jika parameter dwDataSize adalah nol.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol, menunjukkan bahwa entri ditulis ke log.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, panggil GetLastError, yang mengembalikan salah satu kode kesalahan yang diperluas berikut.

Kode kesalahan	Makna
ERROR_INVALID_PARAMETER	Salah satu parameter tidak valid. Kesalahan ini dikembalikan pada Windows Server 2003 jika data pesan yang akan dicatat terlalu besar. Kesalahan ini dikembalikan oleh server RPC pada Windows Server 2003 jika parameter dwDataSize lebih besar dari 261.991 (0x3ff67).
ERROR_NOT_ENOUGH_MEMORY	Sumber daya memori tidak cukup tersedia untuk menyelesaikan operasi.
RPC_S_INVALID_BOUND	Batas array tidak valid. Kesalahan ini dikembalikan jika data pesan yang akan dicatat terlalu besar. Pada Windows Vista dan yang lebih baru, kesalahan ini dikembalikan jika parameter dwDataSize lebih besar dari 61.440 (0xf000).
RPC_X_BAD_STUB_DATA	Stub menerima data yang buruk. Kesalahan ini dikembalikan pada Windows XP jika data pesan yang akan dicatat terlalu besar. Kesalahan ini dikembalikan oleh server RPC pada Windows XP, jika parameter dwDataSize lebih besar dari 262.143 (0x3ffff).
Lainnya	Gunakan FormatMessage untuk mendapatkan string pesan untuk kesalahan yang dikembalikan.

Keterangan

Fungsi ini digunakan untuk mencatat peristiwa. Entri ditulis ke akhir log yang dikonfigurasi untuk sumber yang diidentifikasi oleh parameter hEventLog . Fungsi ReportEvent menambahkan waktu, panjang entri, dan offset sebelum menyimpan entri dalam log. Untuk mengaktifkan fungsi untuk menambahkan nama pengguna, Anda harus menyediakan SID pengguna di parameter lpUserSid .

Ada batas ukuran yang berbeda pada ukuran data pesan yang dapat dicatat tergantung pada versi Windows yang digunakan oleh klien tempat aplikasi dijalankan dan server tempat pesan dicatat. Server ditentukan oleh parameter lpUNCServerName yang diteruskan ke fungsi RegisterEventSource . Kesalahan yang berbeda dikembalikan ketika batas ukuran terlampaui yang bergantung pada versi Windows.

Jika string yang Anda catat berisi %n, di mana n adalah nilai bilangan bulat (misalnya, %1), penampil peristiwa memperlakukannya sebagai string penyisipan. Karena alamat IPv6 dapat berisi urutan karakter ini, Anda harus menyediakan penentu format (! S!) untuk mencatat pesan peristiwa yang berisi alamat IPv6. Penentu ini memberi tahu kode pemformatan untuk menggunakan string secara harfiah dan tidak melakukan ekspansi lebih lanjut (misalnya, "alamat IPv6 saya adalah: %1! S!").

Contoh

Misalnya, lihat Melaporkan Peristiwa.

Catatan

Header winbase.h mendefinisikan ReportEvent 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	winbase.h (termasuk Windows.h)
Pustaka	Advapi32.lib
DLL	Advapi32.dll