Fungsi panggilan balik PENABLECALLBACK (evntprov.h)

Artikel
08/23/2023

Penyedia peristiwa ETW secara opsional menentukan fungsi EnableCallback untuk menerima pemberitahuan perubahan konfigurasi. Jenis PENABLECALLBACK mendefinisikan penunjuk ke fungsi panggilan balik ini. EnableCallback adalah tempat penampung untuk nama fungsi yang ditentukan aplikasi.

Sintaks

PENABLECALLBACK Penablecallback;

void Penablecallback(
  [in]           LPCGUID SourceId,
  [in]           ULONG IsEnabled,
  [in]           UCHAR Level,
  [in]           ULONGLONG MatchAnyKeyword,
                 ULONGLONG MatchAllKeyword,
  [in, optional] PEVENT_FILTER_DESCRIPTOR FilterData,
  [in, optional] PVOID CallbackContext
)
{...}

Parameter

[in] SourceId

GUID yang ditentukan oleh pemanggil yang mengaktifkan atau menonaktifkan penyedia.

Nilai berasal dari parameter SourceIdEnableTraceEx atau bidang SourceIddari ENABLE_TRACE_PARAMETERS yang diteruskan ke EnableTraceEx2.

Catatan

SourceId adalah nilai sesi yang ditentukan dalam panggilan ke API EnableTraceEx atau EnableTraceEx2. Ini mungkin atau mungkin tidak sama dengan GUID sesi.

SourceId akan diatur ke GUID_NULL dalam beberapa skenario di mana pemberitahuan tidak memiliki pengidentifikasi sumber. Misalnya, ini dapat terjadi ketika sesi pelacakan diaktifkan penyedia sebelum penyedia dimulai, ketika penyedia berhenti, atau ketika pengontrol pelacakan memanggil API EnableTrace tanpa menentukan SourceId.

[in] IsEnabled

Menunjukkan ControlCode yang sesuai dengan pemberitahuan ini. Ini bisa menjadi salah satu nilai berikut:

Nilai	Makna
EVENT_CONTROL_CODE_DISABLE_PROVIDER (0)	Tidak ada sesi yang mengaktifkan penyedia.
EVENT_CONTROL_CODE_ENABLE_PROVIDER (1)	Satu atau beberapa sesi telah mengaktifkan penyedia.
EVENT_CONTROL_CODE_CAPTURE_STATE (2)	Sesi meminta penyedia mencatat informasi statusnya. Penyedia biasanya akan merespons dengan menulis peristiwa yang berisi status penyedia.

Catatan

Nilai IsEnabled mungkin tidak sama dengan ControlCode yang diteruskan ke API EnableTrace yang memicu peristiwa ini. Misalnya, jika dua sesi telah mengaktifkan penyedia ini dan satu sesi menonaktifkan penyedia ini dengan memanggil EnableTraceEx2(..., EVENT_CONTROL_CODE_DISABLE_PROVIDER, ...), penyedia akan menerima pemberitahuan dengan IsEnabled diatur ke EVENT_CONTROL_CODE_ENABLE_PROVIDER karena penyedia masih diaktifkan oleh sesi lain.

Setelah menerima pemberitahuan DISABLE_PROVIDER , penyedia dapat mengoptimalkan performanya dengan menonaktifkan semua peristiwa. Setelah menerima pemberitahuan ENABLE_PROVIDER , penyedia harus mengaktifkan penulisan peristiwa. Ini juga dapat mengoptimalkan performanya dengan merekam nilai filter Level, MatchAnyKeyword, dan MatchAllKeyword, lalu hanya menulis peristiwa yang melewati filter (seperti yang dijelaskan dalam keterangan). Setelah menerima pemberitahuan CAPTURE_STATE , penyedia dapat mengambil tindakan apa pun yang tampaknya sesuai, biasanya menulis peristiwa yang menjelaskan konfigurasi atau status komponen.

Penyedia harus mengabaikan pemberitahuan dengan nilai IsEnabled yang tidak dikenali atau didukungnya.

[in] Level

Nilai yang menentukan verbositas peristiwa yang harus ditulis penyedia. Ketika dipanggil dengan kode kontrol EVENT_CONTROL_CODE_ENABLE_PROVIDER, penyedia harus merekam nilai Level dan selanjutnya harus melewati peristiwa di mana tingkat verbositas peristiwa lebih besar dari Tingkat yang direkam, yaitu peristiwa hanya boleh ditulis jika

eventDescriptor.Level <= recorded.Level

Tingkat dalam pemberitahuan adalah maksimum tingkat yang ditentukan oleh pengontrol pelacakan dalam panggilan ke EnableTrace, EnableTraceEx, atau EnableTraceEx2 menggunakan GUID penyedia peristiwa ini. Dengan kata lain, jika beberapa sesi merekam peristiwa dari penyedia peristiwa ini pada tingkat verbositas yang berbeda, parameter Tingkat untuk pemberitahuan EnableCallback akan diatur ke tingkat tertinggi (paling verbose).

[in] MatchAnyKeyword

Nilai bitmask yang menentukan kategori peristiwa yang harus ditulis penyedia. Ketika dipanggil dengan kode kontrol EVENT_CONTROL_CODE_ENABLE_PROVIDER, penyedia harus merekam nilai MatchAnyKeyword dan kemudian harus melewati peristiwa di mana kata kunci peristiwa nonzero dan tidak memiliki bit apa pun dari MatchAnyKeyword yang direkam, yaitu peristiwa hanya boleh ditulis jika

eventDescriptor.Keyword == 0 || (eventDescriptor.Keyword & recorded.MatchAnyKeyword) != 0

MatchAnyKeyword dalam pemberitahuan adalah union (OR) dari match-any-keywords (aktifkan bendera) yang ditentukan oleh pengontrol pelacakan dalam panggilan ke EnableTrace, EnableTraceEx, dan EnableTraceEx2 untuk GUID penyedia peristiwa ini. Dengan kata lain, jika beberapa sesi merekam peristiwa dari penyedia peristiwa ini dengan filter match-any-keyword yang berbeda, parameter MatchAnyKeyword untuk pemberitahuan EnableCallback akan diatur ke bitwise-OR dari filter match-any-keyword sesi.

MatchAllKeyword

Nilai bitmask yang menentukan kategori peristiwa yang harus ditulis penyedia. Ketika diberi tahu dengan kode kontrol EVENT_CONTROL_CODE_ENABLE_PROVIDER, penyedia harus merekam nilai MatchAllKeyword dan kemudian harus melewati peristiwa di mana kata kunci peristiwa bukan nol dan tidak memiliki semua bit dari MatchAllKeyword yang direkam, yaitu peristiwa hanya boleh ditulis jika

eventDescriptor.Keyword == 0 || (eventDescriptor.Keyword & recorded.MatchAllKeyword) == recorded.MatchAllKeyword

MatchAllKeyword dalam pemberitahuan adalah disjunction (AND) dari match-all-keywords yang ditentukan oleh pengontrol pelacakan dalam panggilan ke EnableTraceEx dan EnableTraceEx2 untuk GUID penyedia kejadian ini. Dengan kata lain, jika beberapa sesi merekam peristiwa dari penyedia peristiwa ini dengan filter match-all-keyword yang berbeda, parameter MatchAllKeyword untuk pemberitahuan EnableCallback akan diatur ke bitwise-AND dari filter match-all-keyword sesi.

[in, optional] FilterData

Penunjuk ke EVENT_FILTER_DESCRIPTOR dengan data filter untuk penyedia peristiwa.

Setiap sesi hanya dapat menentukan satu filter. Deskriptor filter dalam pemberitahuan panggilan balik akan berisi satu filter dari setiap sesi yang menentukan data filter saat mengaktifkan penyedia.

Data filter hanya valid dalam panggilan balik. Penyedia harus membuat salinan lokal data jika data akan diperlukan setelah panggilan balik kembali.

[in, optional] CallbackContext

Konteks untuk panggilan balik. Ini adalah nilai parameter CallbackContext yang digunakan saat penyedia peristiwa bernama EventRegister.

Mengembalikan nilai

Tidak ada

Keterangan

Penyedia peristiwa ETW yang memerlukan pemberitahuan perubahan konfigurasi harus memberikan penunjuk ke implementasi EnableCallback saat mereka mendaftar melalui EventRegister. ETW akan memanggil fungsi EnableCallback penyedia ketika perubahan dilakukan pada konfigurasi sesi pelacakan yang melibatkan penyedia. Misalnya, ketika pengontrol sesi pelacakan mengonfigurasi jejak melalui EnableTraceEx2 atau menghentikan jejak melalui ControlTrace, ETW akan memanggil fungsi EnableCallback penyedia dengan konfigurasi yang diperbarui yang dihasilkan.

Catatan

Sebagian besar penyedia peristiwa tidak akan menerapkan EnableCallback secara langsung. Sebagai gantinya, sebagian besar penyedia peristiwa diimplementasikan menggunakan kerangka kerja ETW yang menyediakan implementasi EnableCallback sendiri dan 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. Kerangka kerja ETW biasanya mengimplementasikan fungsi EnableCallback yang merekam nilai , , MatchAnyKeyword, dan MatchAllKeyword pemberitahuanLevel, dan kerangka kerja secara otomatis menggunakan nilai yang direkam untuk memfilter peristiwa. Kerangka kerja ETW biasanya mendukung pemanggilan panggilan balik yang disediakan pengguna jika pengguna memerlukan penanganan pemberitahuan kustom. Misalnya, TraceLoggingProvider.h memungkinkan panggilan balik pemberitahuan ditentukan melalui TraceLoggingRegisterEx.

Penting

Fungsi EnableCallback penyedia harus sesingkat mungkin. Ini harus merekam informasi yang diperlukan dan kembali dengan cepat. Fungsi panggilan balik yang berjalan lama dapat menyebabkan penundaan dalam API kontrol sesi ETW seperti EnableTraceEx2 atau ControlTrace. Fungsi panggilan balik tidak boleh melakukan apa pun yang memerlukan kunci pemuat proses, yaitu tidak boleh secara langsung atau tidak langsung memanggil LoadLibrary atau FreeLibrary. Fungsi panggilan balik tidak boleh memblokir kunci. Fungsi panggilan balik dapat menyebabkan kebuntuan jika memblokir kunci atau jika memanggil API kontrol sesi ETW seperti StartTrace, ControlTrace, atau EnableTrace.

Panggilan balik pemberitahuan memungkinkan penyedia acara berjalan lebih efisien karena penyedia dapat melakukan pelacakan sendiri dari tingkat, kata kunci, dan filter lainnya. Dengan melacak filter, penyedia dapat secara efisien melewati peristiwa yang tidak diaktifkan (yaitu penyedia tidak perlu menyiapkan data peristiwa atau memanggil EventWrite untuk peristiwa yang tidak diperlukan oleh sesi pelacakan apa pun).

Perhatikan bahwa pelacakan filter tidak diperlukan untuk pengoperasian penyedia yang benar: ETW menyediakan fungsi EventEnabled dan EventProviderEnabled yang dapat digunakan penyedia, dan API ETW EventWrite akan secara diam-diam mengabaikan peristiwa yang dinonaktifkan. Namun, pelacakan filter yang diterapkan penyedia bisa lebih efisien daripada panggilan ke EventEnabled atau EventProviderEnabled.

Panggilan balik pemberitahuan juga memungkinkan penyedia untuk menangani permintaan "capture-state" dari sesi pelacakan. Permintaan capture-state biasanya dikirim oleh sesi pelacakan saat mulai merekam peristiwa dari penyedia. Jika capture-state didukung oleh penyedia, ia mungkin menanggapi permintaan capture-state dengan mencatat informasi status, misalnya informasi konfigurasi atau statistik ringkasan mengenai operasi komponen sebelum permintaan.

Nilai Tingkat yang diteruskan ETW ke panggilan balik adalah nilai tingkat tertinggi (paling verbose) yang ditentukan untuk penyedia peristiwa ini oleh sesi pelacakan yang sedang berjalan. Misalnya, jika sesi A telah mengaktifkan penyedia ini untuk peristiwa peringatan (tingkat 3) dan kemudian sesi B memungkinkan penyedia untuk peristiwa penting (tingkat 1), nilai Tingkat untuk panggilan balik akan menjadi 3, bukan 1.

Demikian pula, nilai MatchAnyKeyword dan MatchAllKeyword adalah nilai komposit yang dihitung dari konfigurasi semua sesi yang telah mengaktifkan penyedia peristiwa. MatchAnyKeyword adalah OR dari pengaturan EnableFlags/MatchAnyKeyword dari sesi. MatchAllKeyword adalah AND dari pengaturan MatchAllKeyword dari sesi.

Jika fungsi EnableCallback penyedia telah menangkap status Enabled, Level, MatchAnyKeyword, dan MatchAllKeyword penyedia, penyedia dapat menentukan apakah peristiwa harus ditulis menggunakan fungsi seperti berikut:

BOOL MyProviderEventEnabled(
    _In_ const MY_PROVIDER_STATE* pProvider,
    _In_ const EVENT_DESCRIPTOR* pEvent)
{
    return
        pProvider->Enabled &&
        pEvent->Level <= pProvider->Level &&
        (pEvent->Keyword == 0 || (
            (pEvent->Keyword & pProvider->MatchAnyKeyword) != 0 &&
            (pEvent->Keyword & pProvider->MatchAllKeyword) == pProvider->MatchAllKeyword
        ));
}

Persyaratan


Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	evntprov.h

Lihat juga

EventRegister

EnableTrace

EnableTraceEx2

Bagikan melalui

Fungsi panggilan balik PENABLECALLBACK (evntprov.h)

Sintaks

Parameter

Mengembalikan nilai

Keterangan

Persyaratan

Lihat juga

Saran dan Komentar

Sumber Daya Tambahan: