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

Lihat juga

CloseTrace

EVENT_TRACE_LOGFILE

ProcessTrace