Fungsi EtwWrite (wdm.h)

Fungsi EtwWrite adalah fungsi pelacakan untuk menerbitkan peristiwa dalam kode driver mode kernel Anda.

Sintaksis

NTSTATUS EtwWrite(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in, optional] LPCGUID                ActivityId,
  [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, optional] ActivityId

Pengidentifikasi yang menunjukkan aktivitas yang terkait dengan peristiwa. ActivityID menyediakan cara untuk mengelompokkan peristiwa terkait dan digunakan dalam pelacakan end-to-end.

[in] UserDataCount

Jumlah struktur EVENT_DATA_DESCRIPTOR di UserData.

[in, optional] UserData

Penunjuk ke array struktur EVENT_DATA_DESCRIPTOR.

Mengembalikan nilai

Jika peristiwa berhasil diterbitkan, EtwWrite mengembalikan STATUS_SUCCESS.

Jika penunjuk ke handel pendaftaran penyedia peristiwa tidak valid, EtwWrite mengembalikan STATUS_INVALID_HANDLE. Penyedia peristiwa harus didaftarkan sebelum EtwWrite dipanggil. EtwWrite juga dapat mengembalikan STATUS_INVALID_HANDLE jika tidak dapat mencatat peristiwa.

Jika jumlah struktur EVENT_DATA_DESCRIPTOR yang ditentukan dalam UserDataCount lebih besar dari maksimum yang diizinkan (128), EtwWrite mengembalikan STATUS_INVALID_PARAMETER.

Jika ActivityID ditentukan, tetapi tidak ada cukup memori yang tersedia untuk mencatat data yang terkait dengan peristiwa, EtwWrite mengembalikan STATUS_NO_MEMORY.

Jika penyedia tidak diaktifkan untuk sesi apa pun, EtwWrite mengembalikan STATUS_SUCCESS dan peristiwa tidak dicatat.

Peristiwa dapat hilang karena beberapa alasan; misalnya, jika tingkat peristiwa terlalu tinggi atau jika ukuran peristiwa lebih besar dari ukuran buffer. Dalam kasus ini, penghitung EventsLost, anggota struktur EVENT_TRACE_PROPERTIES untuk pencatat yang sesuai, diperbarui dengan jumlah peristiwa yang tidak direkam.

Komentar

Fungsi EtwWrite setara dengan mode pengguna fungsi EventWrite. Untuk memastikan bahwa ada konsumen untuk peristiwa yang Anda terbitkan, Anda dapat mendahului panggilan ke EtwWrite dengan panggilan ke EtwEventEnabled atau EtwProviderEnabled.

Sebelum Anda dapat memanggil fungsi EtwWrite untuk menerbitkan peristiwa, Anda harus mendaftarkan penyedia dengan EtwRegister. Tidak ada panggilan pelacakan yang harus dilakukan yang berada di luar kode yang dibatasi oleh EtwRegister dan fungsi EtwUnregister. Untuk performa terbaik, Anda dapat memanggil fungsi EtwRegister dalam rutinitas DriverEntry dan fungsi EtwUnregister dalam rutinitas DriverUnload Anda.

Jika Anda menggunakan parameter UserData opsional dalam fungsi Etwrite untuk mencatat data peristiwa tambahan, Anda dapat menggunakan makro EventDataDescreate untuk menyederhanakan pembuatan struktur EVENT_DATA_DESCRIPTOR. Contoh berikut menggunakan makro EventDataDescreate untuk menginisialisasi struktur EVENT_DATA_DESCRIPTOR dengan nama perangkat dan statusnya. Makro EventDataDescreate menyimpan pointer ke data (artinya, tidak menyimpan salinan data). Pointer harus tetap valid sampai panggilan ke EtwWrite kembali.

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

Contoh

 
 //
 // Register the provider with ETW in DriverEntry
 // Unregister the provider in DriverUnload 
    //
 //  Build the EVENT_DATA_DESCRIPTOR structures using 
 //   the EventDataDescCreate macros 
 
 if (RegHandle != (REGHANDLE)NULL) {
 //
 // Log an Event with : DeviceNameLength
 //                      DeviceName
 //                      Status
 //
 
 EventDataDescCreate(&EventDataDescriptor[0],
                            (PVOID)&DeviceName.Length,
 sizeof(USHORT));
 

 EventDataDescCreate(&EventDataDescriptor[1],
                            (PVOID)DeviceName.Buffer,
 DeviceName.Length);
 
 EventDataDescCreate(&EventDataDescriptor[2],
                            (PVOID)&Status,
 sizeof(ULONG));
 
 EtwWrite(RegHandle,            // Handle from EtwRegister
                 &StartEvent,          // EventDescriptor
                 NULL,                 // Activity ID
                 3,                    // Number of data items
 EventDataDescriptor); // Array of data descriptors
    }              

//

Persyaratan

Lihat juga

EtwEventEnabled

EtwProviderEnabled

EtwRegister

EtwUnregister

EtwWriteEx

EtwriteString

EtwWriteTransfer

EventDataDescBuat