Fungsi EventRegister (evntprov.h)

  • Artikel

Mendaftarkan penyedia peristiwa ETW, membuat handel yang dapat digunakan untuk menulis peristiwa ETW.

Sintaks

ULONG EVNTAPI EventRegister(
  [in]           LPCGUID         ProviderId,
  [in, optional] PENABLECALLBACK EnableCallback,
  [in, optional] PVOID           CallbackContext,
  [out]          PREGHANDLE      RegHandle
);

Parameter

[in] ProviderId

GUID yang secara unik mengidentifikasi penyedia, kadang-kadang disebut GUID kontrol. Ini harus menjadi pengidentifikasi yang stabil sehingga pengontrol pelacakan dapat menggunakan GUID untuk berlangganan peristiwa dari penyedia ini.

[in, optional] EnableCallback

EnableCallback opsional yang akan dipanggil ETW ketika sesi pelacakan mengaktifkan atau menonaktifkan penyedia ini. Gunakan NULL jika tidak ada panggilan balik yang diperlukan.

[in, optional] CallbackContext

Data konteks opsional yang akan diberikan ETW saat memanggil EnableCallback. Gunakan NULL jika tidak ada konteks panggilan balik yang diperlukan.

[out] RegHandle

Menerima handel pendaftaran penyedia peristiwa. Handel digunakan dalam panggilan berikutnya ke API penyedia seperti EventWrite, EventProviderEnabled, dan EventRegister.

Sebelum penyedia Anda membongkar atau keluar, bebaskan handel pendaftaran penyedia dengan memanggil EventUnregister. DLL yang membongkar tanpa membebaskan semua handel penyedia yang terdaftar dapat menyebabkan proses crash.

Mengembalikan nilai

Mengembalikan ERROR_SUCCESS jika berhasil.

Kode kesalahan yang dikembalikan oleh EventRegister terutama ditujukan untuk digunakan dalam skenario penelusuran kesalahan dan diagnostik. Sebagian besar kode produksi harus terus berjalan meskipun penyedia ETW gagal mendaftar, jadi build rilis biasanya harus mengabaikan kode kesalahan yang dikembalikan oleh EventRegister.

Keterangan

EventRegister membuat handel yang dapat Anda gunakan untuk menulis peristiwa ETW melalui EventWrite, EventWriteTransfer, atau EventWriteEx.

Catatan

Sebagian besar penyedia peristiwa tidak akan memanggil EventRegister secara langsung. Sebagai gantinya, sebagian besar penyedia peristiwa diimplementasikan menggunakan kerangka kerja ETW yang membungkus panggilan ke EventRegister, EventWrite, dan EventUnregister. Misalnya, Anda dapat menulis manifes peristiwa lalu menggunakan Pengkompilasi Pesan untuk menghasilkan kode C/C++ untuk peristiwa tersebut, atau Anda dapat menggunakan TraceLogging untuk menghindari kebutuhan akan manifes.

Pendaftaran penyedia peristiwa tidak boleh dikacaukan dengan penginstalan manifes penyedia peristiwa.

  • API EventRegister melakukan pendaftaran penyedia peristiwa untuk membuat handel penyedia. Ini adalah operasi cakupan proses (handel hanya valid dalam proses). Handel dapat digunakan untuk menulis peristiwa ETW. Semua peristiwa yang ditulis menggunakan handel akan ditandai dengan ProviderId yang ditentukan selama pendaftaran penyedia. Tidak perlu menginstal manifes untuk menulis peristiwa atau menangkap jejak (meskipun menginstal manifes mungkin diperlukan untuk mendekode peristiwa penyedia atau agar penyedia bekerja dengan Log Peristiwa).
  • Alat wevtutil.exe digunakan untuk menginstal atau menghapus manifes penyedia peristiwa. Penginstalan manifes penyedia peristiwa berarti bahwa informasi dari manifes dicatat pada sistem. Informasi yang direkam adalah system-global dan bertahan sampai manifes dihapus instalannya. Informasi yang direkam mencakup nama, GUID, saluran, dan jalur DLL sumber daya penyedia yang ditentukan dalam manifes. Informasi dari manifes digunakan oleh alat pendekodean jejak dan Log Peristiwa.

Sebagian besar komponen akan mendaftarkan penyedia peristiwa mereka di inisialisasi komponen dan akan membatalkan pendaftaran penyedia peristiwa mereka saat penonaktifan komponen. Misalnya, aplikasi (EXE) mungkin mendaftar selama pengaktifan aplikasi dan membatalkan pendaftaran selama aplikasi keluar. Pustaka dinamis (DLL) mungkin mendaftar selama DllMain lampiran proses dan mungkin membatalkan pendaftaran DllMain selama proses dicopot.

Karena pelacakan peristiwa adalah masalah debugging/diagnostik dan biasanya bukan fungsionalitas penting aplikasi, sebagian besar aplikasi ritel harus secara diam-diam mengabaikan kegagalan yang dikembalikan oleh EventRegister. Jika terjadi kegagalan, EventRegister akan mengatur parameter RegHandle ke nol sehingga penggunaan RegHandle berikutnya (yaitu dalam panggilan ke EventWrite dan EventUnregister) tidak akan berpengaruh.

Setiap proses dapat mendaftar hingga 1.024 penyedia. Namun, Anda harus membatasi jumlah penyedia yang didaftarkan komponen Anda menjadi satu atau dua. Batas ini mencakup penyedia yang terdaftar menggunakan fungsi ini dan penyedia yang terdaftar menggunakan RegisterTraceGuids.

Sebelum Windows Vista: Tidak ada batasan khusus untuk jumlah penyedia yang dapat didaftarkan oleh proses.

Persyaratan

   
Klien minimum yang didukung Windows Vista [aplikasi desktop | Aplikasi UWP]
Server minimum yang didukung Windows Server 2008 [aplikasi desktop | Aplikasi UWP]
Target Platform Windows
Header evntprov.h
Pustaka Advapi32.lib
DLL Advapi32.dll

Lihat juga

EnableCallback

EventWrite

EventUnregister