Fungsi OpenTraceA (evntrace.h)
Fungsi OpenTrace membuka handel pemrosesan jejak ETW untuk mengonsumsi peristiwa dari sesi pelacakan real time ETW atau file log ETW.
Sintaks
PROCESSTRACE_HANDLE WMIAPI OpenTraceA(
[in, out] PEVENT_TRACE_LOGFILEA Logfile
);
Parameter
[in, out] Logfile
Arahkan ke struktur EVENT_TRACE_LOGFILE . Struktur menentukan sumber untuk menggunakan peristiwa (dari file log ETW atau sesi ETW real time) dan menentukan panggilan balik yang ingin digunakan konsumen untuk menerima peristiwa. Setelah berhasil, OpenTrace akan memperbarui struktur dengan informasi dari file atau sesi yang dibuka.
Mengembalikan nilai
Jika fungsi berhasil, fungsi akan mengembalikan handel pemrosesan pelacakan. Handel harus ditutup menggunakan CloseTrace.
Jika fungsi gagal, fungsi akan mengembalikan INVALID_PROCESSTRACE_HANDLE.
(INVALID_PROCESSTRACE_HANDLE setara (UINT64)UINTPTR_MAXdengan .)
Catatan
Sebelum Windows Vista, OpenTrace ditampilkan UINT64_MAX jika terjadi kegagalan. Jika kode Anda mendukung sistem operasi yang lebih lama (Windows XP atau Windows Server 2003) dan versi Windows yang lebih baru (Windows Vista dan yang lebih baru), Anda harus menentukan sistem operasi tempat Anda menjalankan dan membandingkan nilai kembali dengan nilai yang sesuai.
| Sistem operasi | Jenis Proses | Nilai yang menunjukkan kegagalan |
|---|---|---|
| Sebelum Windows Vista | 32- atau 64-bit | 0XFFFFFFFFFFFFFFFF = UINT64_MAX |
| Windows Vista atau yang lebih baru | 32-bit | 0x00000000FFFFFFFF = (UINT64)UINTPTR_MAX |
| Windows Vista atau yang lebih baru | 64-bit | 0XFFFFFFFFFFFFFFFF = (UINT64)UINTPTR_MAX |
Jika fungsi gagal, Anda dapat menggunakan fungsi GetLastError untuk mendapatkan informasi kesalahan yang diperluas. Berikut ini adalah beberapa kesalahan umum dan penyebabnya.
ERROR_INVALID_PARAMETER
Parameter Logfile adalah NULL.
ERROR_BAD_PATHNAME
Jika Anda tidak menentukan anggota LoggerNamedari EVENT_TRACE_LOGFILE, Anda harus menentukan nama file log yang valid.
ERROR_ACCESS_DENIED
Hanya pengguna dengan hak administratif, pengguna di grup Pengguna Log Performa, dan layanan yang berjalan sebagai LocalSystem, LocalService, NetworkService yang dapat mengonsumsi peristiwa secara real time. Untuk memberi pengguna terbatas kemampuan untuk menggunakan peristiwa secara real time, tambahkan ke grup Pengguna Log Performa.
Windows XP dan Windows 2000: Siapa pun dapat mengonsumsi peristiwa real time.
Keterangan
Konsumen pelacakan memanggil fungsi ini untuk membuka sesi pemrosesan jejak.
Setelah memanggil OpenTrace, panggil fungsi ProcessTrace untuk memproses peristiwa. Setelah Anda selesai memproses peristiwa, panggil fungsi CloseTrace untuk menutup handel pemrosesan jejak.
Contoh
Untuk contoh yang menggunakan OpenTrace, lihat Menggunakan TdhFormatProperty untuk Mengonsumsi Data Peristiwa.
Catatan
Header evntrace.h mendefinisikan OpenTrace sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| 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 di 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 di Windows 8.1 dan Windows Server 2012 R2; Advapi32.dll di Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista dan Windows XP |