Fungsi TraceEventInstance (evntrace.h)
Penyedia peristiwa berbasis RegisterTraceGuids ("Klasik") menggunakan fungsi TraceEventInstance untuk mengirim peristiwa terstruktur ke sesi pelacakan peristiwa dengan pengidentifikasi instans.
Peristiwa ini menggunakan pengidentifikasi instans untuk mengaitkan peristiwa dengan transaksi. Fungsi ini juga dapat digunakan untuk melacak hubungan hierarkis antara peristiwa terkait.
Sintaks
ULONG WMIAPI TraceEventInstance(
[in] TRACEHANDLE TraceHandle,
[in] PEVENT_INSTANCE_HEADER EventTrace,
[in] PEVENT_INSTANCE_INFO InstInfo,
[in] PEVENT_INSTANCE_INFO ParentInstInfo
);
Parameter
[in] TraceHandle
Tangani ke sesi pelacakan peristiwa yang merekam instans peristiwa. Penyedia memperoleh handel ketika memanggil fungsi GetTraceLoggerHandle dalam implementasi ControlCallback-nya .
[in] EventTrace
Arahkan ke struktur EVENT_INSTANCE_HEADER . Data khusus peristiwa secara opsional ditambahkan ke struktur. Peristiwa terbesar yang dapat Anda catat adalah 64K. Anda harus menentukan nilai untuk anggota struktur EVENT_INSTANCE_HEADER berikut.
- Ukuran
- Bendera
- RegHandle
Bergantung pada kompleksitas informasi yang disediakan penyedia Anda, Anda juga harus mempertimbangkan untuk menentukan nilai untuk anggota berikut.
- Class.Type
- Class.Level
Untuk melacak hubungan hierarkis antara peristiwa terkait, atur juga anggota ParentRegHandle .
[in] InstInfo
Penunjuk ke struktur EVENT_INSTANCE_INFO , yang berisi handel pendaftaran untuk kelas pelacakan peristiwa ini dan pengidentifikasi instans. Gunakan fungsi CreateTraceInstanceId untuk menginisialisasi struktur.
[in] ParentInstInfo
Arahkan ke struktur EVENT_INSTANCE_INFO , yang berisi handel pendaftaran untuk kelas pelacakan peristiwa induk dan pengidentifikasi instansnya. Gunakan fungsi CreateTraceInstanceId untuk menginisialisasi struktur. Atur ke NULL jika Anda tidak melacak hubungan hierarkis.
Menampilkan nilai
Jika fungsi berhasil, nilai yang dikembalikan adalah ERROR_SUCCESS.
Jika fungsi gagal, nilai yang dikembalikan adalah salah satu kode kesalahan sistem. Berikut ini adalah beberapa kesalahan umum dan penyebabnya.
ERROR_INVALID_FLAGS
Anggota BenderaEVENT_INSTANCE_HEADER tidak berisi WNODE_FLAG_TRACED_GUID.
ERROR_OUTOFMEMORY
Memori tidak cukup untuk menyelesaikan panggilan fungsi. Penyebab kode kesalahan ini dijelaskan di bagian Keterangan berikut.
ERROR_INVALID_PARAMETER
Salah satu hal berikut ini benar:
- EventTrace adalah NULL.
- pInstInfo adalah NULL.
- Anggota pInstInfo adalah NULL.
- TraceHandle adalah NULL.
- Anggota UkuranEVENT_INSTANCE_HEADER salah.
ERROR_INVALID_HANDLE
TraceHandle tidak valid atau menentukan handel sesi NT Kernel Logger.
ERROR_NOT_ENOUGH_MEMORY
Sesi kehabisan buffer gratis untuk ditulis. Ini dapat terjadi selama tingkat peristiwa tinggi karena subsistem disk kelebihan beban atau jumlah buffer terlalu kecil. Daripada memblokir hingga lebih banyak buffer tersedia, TraceEvent membuang peristiwa.
Windows 2000 dan Windows XP: Tidak didukung.
ERROR_OUTOFMEMORY
Kejadian ini dibuang karena, meskipun kumpulan buffer belum mencapai ukuran maksimumnya, memori yang tersedia tidak cukup untuk mengalokasikan buffer tambahan dan tidak ada buffer yang tersedia untuk menerima acara.
ERROR_MORE_DATA
Data dari satu peristiwa tidak dapat menjangkau beberapa buffer. Peristiwa pelacakan terbatas pada ukuran buffer sesi pelacakan peristiwa dikurangi ukuran struktur EVENT_INSTANCE_HEADER .
Keterangan
Penyedia ETW berbasis MOF memanggil fungsi ini.
Catatan
Sebagian besar pengembang tidak akan memanggil fungsi ini. API ini mendukung ETW berbasis MOF, tetapi ETW berbasis MOF tidak digunakan lagi demi mendukung ETW berbasis manifes. Selain itu, sebagian besar penyedia berbasis MOF menggunakan fungsi pembungkus yang dihasilkan oleh MC.exe alih-alih langsung memanggil API ETW.
Sebelum penyedia dapat memanggil fungsi ini, penyedia
- Harus memanggil fungsi RegisterTraceGuids untuk mendaftarkan dirinya sendiri dan kelas pelacakan peristiwa.
- Harus memanggil fungsi CreateTraceInstanceId untuk membuat pengidentifikasi instans untuk kelas pelacakan peristiwa terdaftar.
- Harus diaktifkan. Pengontrol memanggil fungsi EnableTrace untuk mengaktifkan penyedia.
Peristiwa ini ditulis ke file log, dikirim ke konsumen pelacakan peristiwa secara real time, atau keduanya. Anggota LogFileMode dari struktur EVENT_TRACE_PROPERTIES yang diteruskan ke StartTrace menentukan tempat peristiwa dikirim.
Peristiwa jejak ditulis dalam urutan terjadinya.
Untuk melacak peristiwa yang tidak terkait, gunakan fungsi TraceEvent .
Windows XP: Tidak berfungsi dengan benar.
Contoh
Untuk contoh pembuatan set peristiwa terkait menggunakan CreateTraceInstanceId dan TraceEventInstance, lihat Melacak Instans Peristiwa.
Persyaratan
| Klien minimum yang didukung | Windows 2000 Professional [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows 2000 Server [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | evntrace.h |
| Pustaka | Advapi32.lib |
| DLL | Advapi32.dll |