Fungsi EtwWriteEx (wdm.h)

  • Artikel

Fungsi EtwWriteEx adalah fungsi pelacakan untuk menerbitkan peristiwa yang mendukung pemfilteran dalam kode driver mode kernel Anda.

Sintaks

NTSTATUS EtwWriteEx(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in]           ULONG64                Filter,
  [in]           ULONG                  Flags,
  [in, optional] LPCGUID                ActivityId,
  [in, optional] LPCGUID                RelatedActivityId,
  [in]           ULONG                  UserDataCount,
  [in, optional] PEVENT_DATA_DESCRIPTOR UserData
);

Parameter

[in] RegHandle

Penunjuk ke handel pendaftaran penyedia peristiwa, yang dikembalikan oleh fungsi EtwRegister jika pendaftaran penyedia peristiwa berhasil.

[in] EventDescriptor

Penunjuk ke struktur EVENT_DESCRIPTOR .

[in] Filter

Pengidentifikasi instans yang mengidentifikasi sesi tempat peristiwa tidak akan ditulis. Artinya, nilainya adalah masker sesi yang harus dikecualikan dari pengelogan (difilter). Gunakan bitwise OR untuk menentukan beberapa pengidentifikasi. Atur ke nol jika Anda tidak mendukung filter atau jika peristiwa sedang ditulis ke semua sesi (tidak ada filter yang gagal). Untuk informasi tentang mendapatkan pengidentifikasi untuk sesi, lihat parameter FilterData dari panggilan balik EtwEnableCallback Anda.

[in] Flags

Dicadangkan. Harus nol (0).

[in, optional] ActivityId

Pengidentifikasi yang menunjukkan aktivitas yang terkait dengan peristiwa. ActivityID menyediakan cara untuk mengelompokkan peristiwa terkait dan digunakan dalam pelacakan end-to-end. Jika NULL, ETW mendapatkan pengidentifikasi dari penyimpanan lokal utas. Untuk detail tentang mendapatkan pengidentifikasi ini, lihat EtwActivityIdControl.

[in, optional] RelatedActivityId

Pengidentifikasi aktivitas dari komponen sebelumnya. Gunakan parameter ini untuk menautkan peristiwa komponen Anda ke peristiwa komponen sebelumnya. Untuk mendapatkan pengidentifikasi aktivitas yang ditetapkan untuk komponen sebelumnya, lihat deskripsi untuk parameter ControlCode dari fungsi EtwActivityIdControl .

[in] UserDataCount

Jumlah struktur EVENT_DATA_DESCRIPTOR di UserData. Jumlah maksimum adalah 128.

[in, optional] UserData

Penunjuk ke array struktur EVENT_DATA_DESCRIPTOR. Atur parameter ini ke NULL jika UserDataCount adalah nol. Data harus dalam urutan yang ditentukan dalam manifes.

Mengembalikan nilai

Mengembalikan ERROR_SUCCESS jika berhasil atau salah satu nilai berikut pada kesalahan.

Keterangan

Fungsi EtwWriteEx setara dengan fungsi EventWriteEx mode pengguna. Data peristiwa yang ditulis dengan fungsi ini memerlukan manifes. Manifes disematkan di penyedia, sehingga penyedia harus tersedia bagi konsumen untuk menggunakan data. Untuk memastikan bahwa ada konsumen untuk peristiwa yang Anda terbitkan, Anda dapat mendahului panggilan ke EtwWrite dengan panggilan ke EtwEventEnabled atau EtwProviderEnabled.

Gunakan parameter ActivityId dan RelatedActivityId saat Anda ingin menghubungkan peristiwa dalam komponen yang berbeda dalam skenario pelacakan end-to-end. Misalnya, komponen A, B, dan C melakukan pekerjaan pada aktivitas terkait dan ingin menautkan peristiwa mereka sehingga konsumen dapat mengonsumsi semua peristiwa yang terkait dengan aktivitas tersebut.

Anda dapat memanggil EtwWriteEx di IRQL apa pun. Namun, ketika IRQL lebih besar dari APC_LEVEL, data apa pun yang diteruskan ke fungsi EtwWrite, EtwWriteEx, EtwWriteString, EtwWriteTransfer tidak boleh dapat dipaginasi. Artinya, rutinitas mode kernel apa pun yang berjalan di IRQL yang lebih besar dari APC_LEVEL tidak dapat mengakses memori yang dapat dipaginasi. Data yang diteruskan ke fungsi EtwWrite, EtwWriteEx, EtwWriteString, dan EtwWriteTransfer harus berada di memori ruang sistem, terlepas dari apa itu IRQL.

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows 7
Server minimum yang didukung Windows Server 2008 R2
Target Platform Universal
Header wdm.h
Pustaka NtosKrnl.lib
DLL NtosKrnl.exe

Lihat juga

EtwWrite

EventWrite

EventWriteEx