Fungsi EventWriteTransfer (evntprov.h)
Menulis peristiwa ETW dengan ID aktivitas dan ID aktivitas terkait opsional.
Sintaks
ULONG EVNTAPI EventWriteTransfer(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in, optional] LPCGUID ActivityId,
[in, optional] LPCGUID RelatedActivityId,
[in] ULONG UserDataCount,
[in, optional] PEVENT_DATA_DESCRIPTOR UserData
);
Parameter
[in] RegHandle
Handel pendaftaran penyedia. Handel berasal dari EventRegister. Peristiwa yang dihasilkan akan menggunakan ProviderId yang terkait dengan handel.
[in] EventDescriptor
EVENT_DESCRIPTOR dengan informasi peristiwa (metadata) termasuk ID, Versi, Tingkat, Kata Kunci, Saluran, Opcode, dan Tugas.
Penting
ProviderId, Level, dan Keyword adalah sarana utama untuk memfilter peristiwa. Jenis pemfilteran lain dimungkinkan tetapi memiliki overhead yang jauh lebih tinggi. Selalu tetapkan tingkat bukan nol dan kata kunci untuk setiap peristiwa.
[in, optional] ActivityId
Penunjuk opsional ke ID aktivitas 128-bit untuk peristiwa ini. Jika ini non-NULL, EventWriteTransfer akan menggunakan nilai yang ditentukan untuk ID aktivitas peristiwa. Jika ini NULL, EventWriteTransfer akan menggunakan ID aktivitas utas saat ini.
Alat pemrosesan pelacakan dapat menggunakan ID aktivitas acara untuk mengatur peristiwa ke dalam grup yang disebut aktivitas. Untuk informasi tambahan tentang ID aktivitas, lihat EventActivityIdControl.
[in, optional] RelatedActivityId
Penunjuk opsional ke ID aktivitas 128-bit yang merupakan induk aktivitas acara ini. Jika ini non-NULL, EventWriteTransfer akan menggunakan nilai yang ditentukan untuk ID aktivitas terkait peristiwa. Jika ini NULL, peristiwa tidak akan memiliki ID aktivitas terkait. ID aktivitas terkait biasanya diatur pada peristiwa MULAI aktivitas (peristiwa pertama aktivitas, dicatat dengan Opcode = START).
Alat pemrosesan jejak dapat menggunakan ID aktivitas terkait peristiwa untuk menentukan hubungan antara aktivitas, misalnya aktivitas terkait adalah induk dari aktivitas yang baru dimulai. Untuk informasi tambahan tentang ID aktivitas terkait, lihat EventActivityIdControl.
[in] UserDataCount
Jumlah struktur EVENT_DATA_DESCRIPTOR di UserData. Jumlah maksimum adalah 128.
[in, optional] UserData
Array UserDataCountEVENT_DATA_DESCRIPTOR struktur yang menjelaskan data yang akan disertakan dalam peristiwa tersebut. UserData mungkin NULL jika UserDataCount adalah nol.
Setiap EVENT_DATA_DESCRIPTOR menjelaskan satu blok memori yang akan disertakan dalam peristiwa tersebut. Blok yang ditentukan akan digabungkan secara berurutan tanpa padding atau perataan untuk membentuk konten peristiwa. Jika menggunakan pendekodean berbasis manifes, konten peristiwa harus cocok dengan tata letak yang ditentukan dalam templat yang terkait dengan peristiwa dalam manifes.
Nilai kembali
Mengembalikan ERROR_SUCCESS jika berhasil atau kode kesalahan. Kode kesalahan yang mungkin termasuk yang berikut ini:
- ERROR_INVALID_PARAMETER: Satu atau beberapa parameter tidak valid.
- ERROR_INVALID_HANDLE: Handel pendaftaran penyedia tidak valid.
- ERROR_ARITHMETIC_OVERFLOW: Ukuran peristiwa lebih besar dari maksimum yang diizinkan (64KB - header).
- ERROR_MORE_DATA: Ukuran buffer sesi terlalu kecil untuk peristiwa tersebut.
- ERROR_NOT_ENOUGH_MEMORY: Terjadi ketika buffer yang diisi mencoba memerah ke disk, tetapi IO disk tidak terjadi cukup cepat. Ini terjadi ketika disk lambat dan lalu lintas peristiwa padat. Akhirnya, tidak ada lagi buffer gratis (kosong) dan peristiwa dihilangkan.
- STATUS_LOG_FILE_FULL: File pemutaran real-time penuh. Peristiwa tidak dicatat ke sesi sampai konsumen real-time mengonsumsi peristiwa dari file pemutaran.
Kode kesalahan terutama ditujukan untuk digunakan dalam skenario penelusuran kesalahan dan diagnostik. Sebagian besar kode produksi harus terus berjalan dan terus melaporkan peristiwa bahkan jika peristiwa ETW tidak dapat ditulis, sehingga build rilis biasanya harus mengabaikan kode kesalahan.
Keterangan
Sebagian besar penyedia peristiwa tidak akan memanggil EventWriteTransfer secara langsung. Sebagai gantinya, sebagian besar penyedia peristiwa diimplementasikan menggunakan kerangka kerja ETW yang membungkus panggilan ke EventRegister, EventWriteTransfer, 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.
EventWriteTransfer akan merutekan peristiwa ke sesi pelacakan yang sesuai berdasarkan ProviderId (ditentukan dari RegHandle), Level, Keyword, dan karakteristik peristiwa lainnya. Jika tidak ada sesi jejak yang merekam peristiwa ini, fungsi ini tidak akan melakukan apa pun dan mengembalikan ERROR_SUCCESS.
Untuk mengurangi dampak performa peristiwa yang tidak direkam oleh sesi pelacakan apa pun, Anda dapat memanggil EventEnabled untuk menentukan apakah ada sesi pelacakan yang merekam peristiwa Anda sebelum menyiapkan data dan memanggil EventWriteTransfer.
EventWriteTransfer setara dengan EventWriteEx dengan 0 untuk Filter dan 0 untuk Bendera.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| 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 |