Fungsi ProcessTrace (evntrace.h)
Fungsi ProcessTrace memberikan peristiwa dari satu atau beberapa sesi pemrosesan jejak ETW kepada konsumen.
Sintaks
ETW_APP_DECLSPEC_DEPRECATED ULONG WMIAPI ProcessTrace(
[in] PTRACEHANDLE HandleArray,
[in] ULONG HandleCount,
[in] LPFILETIME StartTime,
[in] LPFILETIME EndTime
);
Parameter
[in] HandleArray
Penunjuk ke array handel sesi pemrosesan pelacakan yang diperoleh dari panggilan sebelumnya ke fungsi OpenTrace .
Array dapat berisi hingga 64 handel ke sesi pemrosesan file atau dapat berisi satu handel ke sesi pemrosesan real time. Array tidak boleh berisi handel sesi pemrosesan file dan handel sesi pemrosesan real time.
[in] HandleCount
Jumlah elemen dalam HandleArray.
[in] StartTime
Penunjuk ke struktur FILETIME opsional yang menentukan periode waktu awal yang ingin Anda terima peristiwanya. Fungsi ini tidak mengirimkan peristiwa dengan tanda waktu sebelum StartTime.
[in] EndTime
Penunjuk ke struktur FILETIME opsional yang menentukan periode waktu akhir yang ingin Anda terima peristiwanya. Fungsi ini tidak mengirimkan peristiwa dengan tanda waktu setelah EndTime.
Windows Server 2003: Nilai ini diabaikan untuk pengiriman peristiwa real time.
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_BAD_LENGTH
HandleCount tidak valid atau jumlah handel lebih besar dari 64.
ERROR_INVALID_HANDLE
Elemen HandleArray bukan handel sesi pelacakan peristiwa yang valid.
ERROR_INVALID_TIME
EndTime kurang dari StartTime.
ERROR_INVALID_PARAMETER
HandleArray adalah NULL, berisi sesi pemrosesan file dan sesi pemrosesan real-time, atau berisi lebih dari satu sesi pemrosesan real time.
ERROR_NOACCESS
Pengecualian terjadi di salah satu fungsi panggilan balik yang menerima peristiwa.
ERROR_CANCELLED
Menunjukkan konsumen membatalkan pemrosesan dengan mengembalikan FALSE dalam fungsi BufferCallback mereka.
ERROR_WMI_INSTANCE_NOT_FOUND
Sesi pengumpulan jejak tempat Anda mencoba mengonsumsi peristiwa secara real time tidak berjalan atau tidak mengaktifkan mode pelacakan real time.
Keterangan
Konsumen pelacakan memanggil fungsi ini untuk memproses peristiwa dari satu atau beberapa sesi pemrosesan jejak. Fungsi ini memblokir hingga pemrosesan berakhir.
Sebelum memanggil ProcessTrace, gunakan OpenTrace untuk membuka handel untuk melacak sesi pemrosesan.
Fungsi ProcessTrace memberikan peristiwa dari sesi dengan memanggil fungsi panggilan balik BufferCallback, EventCallback, dan EventRecordCallback konsumen.
Fungsi ProcessTrace mencoba mengirimkan peristiwa secara berurutan berdasarkan tanda waktu peristiwa (yaitu mencoba mengirimkan peristiwa terlama ke yang terbaru). Dalam kasus tertentu, ProcessTrace mungkin mengirimkan peristiwa secara tidak berurutan.
- Jika jam yang digunakan untuk tanda waktu peristiwa disesuaikan mundur selama pengumpulan jejak, urutan pengiriman peristiwa tidak dapat diprediksi. Untuk menghindari masalah ini, gunakan jam QPC alih-alih jam waktu sistem saat mengumpulkan jejak.
- Jika beberapa peristiwa dikumpulkan dengan tanda waktu yang sama pada CPU yang berbeda, urutan pengiriman peristiwa tidak dapat diprediksi.
- Jika suatu peristiwa memiliki tanda waktu yang tidak valid (misalnya karena kerusakan file), urutan pengiriman peristiwa tersebut dan peristiwa lain dalam jejak mungkin tidak dapat diprediksi.
Fungsi ProcessTrace memblokir utas hingga mengirimkan semua peristiwa, fungsi BufferCallback mengembalikan FALSE, atau Anda memanggil CloseTrace. Selain itu, jika konsumen mengonsumsi peristiwa secara real time, fungsi ProcessTrace akan kembali setelah pengontrol menghentikan sesi pelacakan. (Perhatikan bahwa mungkin ada penundaan beberapa detik sebelum fungsi kembali.)
Windows Server 2003: Anda dapat memanggil CloseTrace hanya setelah ProcessTrace kembali.
Contoh
Untuk contoh yang menggunakan ProcessTrace, lihat Menggunakan TdhFormatProperty untuk Mengonsumsi Data Peristiwa.
Persyaratan
| Klien minimum yang didukung | Windows 2000 Professional [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows 2000 Server [aplikasi desktop | Aplikasi UWP] |
| Target Platform | Windows |
| Header | evntrace.h |
| Pustaka | Sechost.lib pada Windows 8.1 dan Windows Server 2012 R2; Advapi32.lib di Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, dan Windows XP |
| DLL | Sechost.dll pada Windows 8.1 dan Windows Server 2012 R2; Advapi32.dll pada Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, dan Windows XP |