Fungsi ProcessTrace (evntrace.h)

Artikel
08/23/2023

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