Fungsi TraceLoggingRegister (traceloggingprovider.h)

  • Artikel

Mendaftarkan penyedia TraceLogging sehingga dapat digunakan untuk mencatat peristiwa. Pendaftaran berlaku sampai penyedia tidak terdaftar atau proses keluar.

Sintaks

TLG_STATUS TraceLoggingRegister(
  TraceLoggingHProvider hProvider
);

Parameter

hProvider

Handel penyedia TraceLogging untuk mendaftar. Handel belum boleh didaftarkan.

Mengembalikan nilai

Jika Anda memanggil fungsi ini dari kode mode pengguna, fungsi mengembalikan HRESULT. SUCCEEDED() Gunakan makro untuk menentukan apakah fungsi berhasil.

Jika Anda memanggil fungsi ini dari kode mode kernel, fungsi mengembalikan NTSTATUS. NT_SUCCESS() Gunakan makro untuk menentukan apakah fungsi berhasil.

Catatan

Kode kesalahan yang dikembalikan oleh TraceLoggingRegister 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 TraceLoggingRegister.

Keterangan

Ketika komponen mulai berjalan, setiap handel penyedia TraceLogging dalam komponen akan berada dalam status tidak terdaftar dan setiap upaya untuk menggunakan handel penyedia untuk menghasilkan peristiwa akan diabaikan secara diam-diam. Sebelum penyedia dapat menulis peristiwa apa pun, Anda perlu mendaftarkan penyedia menggunakan TraceLoggingRegister. Anda biasanya akan melakukan ini selama startup komponen, misalnya dalam main, , wmain, WinMainDllMain(DLL_PROCESS_ATTACH), atau DriverEntry. Pada penonaktifan komponen, batalkan pendaftaran penyedia dengan memanggil TraceLoggingUnregister.

Jangan panggil TraceLoggingRegister pada handel penyedia yang sudah terdaftar. Anda dapat membatalkan pendaftaran handel dan kemudian mendaftarkannya lagi jika perlu, meskipun berulang kali mendaftarkan dan membatalkan pendaftaran handel dapat menyebabkan masalah performa dan harus dihindari (yaitu jangan mendaftar, menulis beberapa peristiwa, dan kemudian membatalkan pendaftaran; sebaliknya, mendaftar sekali pada startup komponen dan membatalkan pendaftaran pada pematian komponen).

TraceLoggingRegister tidak aman untuk alur sehubungan dengan panggilan lain ke TraceLoggingRegister atau TraceLoggingUnregister pada handel yang sama. Jangan panggil TraceLoggingRegister jika ada kemungkinan bahwa utas lain mungkin memanggil TraceLoggingRegister atau TraceLoggingUnregister pada handel yang sama pada saat yang sama.

Jika TraceLoggingRegister gagal, handel penyedia akan tetap tidak terdaftar dan semua penggunaan handel penyedia akan aman tanpa operasi. Secara khusus, ini adalah no-op yang aman untuk memanggil TraceLoggingWrite atau TraceLoggingUnregister dengan handel penyedia yang tidak terdaftar.

Penting

Jika DLL atau driver Anda memanggil TraceLoggingRegister pada handel penyedia, itu harus memanggil TraceLoggingUnregister pada handel penyedia tersebut sebelum DLL atau driver dibongkar. Jika DLL dibongkar tanpa memanggil TraceLoggingUnregister, proses tersebut kemudian dapat mengalami crash. Jika driver dibongkar tanpa memanggil TraceLoggingUnregister, sistem kemudian dapat mengalami crash. Fungsi TraceLoggingRegister menetapkan panggilan balik konfigurasi ETW, dan TraceLoggingUnregister membatalkan panggilan balik. Jika panggilan balik tidak dibatalkan dan modul dibongkar, crash akan terjadi saat ETW mencoba memanggil panggilan balik.

Peringatan

Jika driver Anda memanggil TraceLoggingRegister dan kemudian mengalami kesalahan selama DriverEntry, driver harus memanggil TraceLoggingUnregister sebelum mengembalikan kesalahan dari DriverEntry. Rutinitas pembersihan driver normal tidak akan dipanggil jika driver mengembalikan kesalahan dari DriverEntry, dan kegagalan untuk memanggil TraceLoggingUnregister akan menyebabkan sistem mengalami crash.

TraceLoggingRegister melakukan hal berikut:

Panggilan ke TraceLoggingRegister sama dengan panggilan ke TraceLoggingRegisterEx dengan NULL untuk parameter panggilan balik dan konteks . Gunakan TraceLoggingRegisterEx jika Anda perlu menerima Panggilan Balik Aktifkan ETW saat sesi mengaktifkan atau menonaktifkan penyedia Anda.

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows Vista [aplikasi desktop | Aplikasi UWP]
Server minimum yang didukung Windows Server 2008 [aplikasi desktop | Aplikasi UWP]
Header traceloggingprovider.h
Pustaka Advapi32.lib

Lihat juga

EventRegister

TraceLoggingRegisterEx

TraceLoggingUnregister

TraceLoggingWrite

TRACELOGGING_DEFINE_PROVIDER