Fungsi RegisterTraceGuidsA (evntrace.h)
Fungsi RegisterTraceGuids mendaftarkan penyedia pelacakan peristiwa ETW Klasik (bergaya Windows 2000) dan kelas pelacakan peristiwa yang digunakannya untuk menghasilkan peristiwa. Fungsi ini juga menentukan fungsi panggilan balik yang digunakan sistem untuk mengaktifkan dan menonaktifkan pelacakan dari penyedia.
Fungsi ini sudah usang. Kode baru harus menggunakan EventRegister untuk mendaftarkan penyedia pelacakan peristiwa ETW gaya Windows Vista (Crimson).
Sintaks
ULONG WMIAPI RegisterTraceGuidsA(
[in] WMIDPREQUEST RequestAddress,
[in] PVOID RequestContext,
[in] LPCGUID ControlGuid,
[in] ULONG GuidCount,
[in, out] PTRACE_GUID_REGISTRATION TraceGuidReg,
[in] LPCSTR MofImagePath,
[in] LPCSTR MofResourceName,
[out] PTRACEHANDLE RegistrationHandle
);
Parameter
[in] RequestAddress
Penunjuk ke fungsi ControlCallback yang menerima pemberitahuan saat penyedia diaktifkan atau dinonaktifkan oleh sesi pelacakan peristiwa. Fungsi EnableTrace memicu panggilan balik ini.
[in] RequestContext
Penunjuk ke konteks opsional yang ditentukan penyedia yang diteruskan ETW ke fungsi yang ditentukan oleh RequestAddress.
[in] ControlGuid
Mengontrol GUID (ID Penyedia) dari penyedia pendaftaran.
[in] GuidCount
Jumlah elemen dalam array TraceGuidReg . Jika TraceGuidReg adalah NULL, atur parameter ini ke 0.
[in, out] TraceGuidReg
Penunjuk ke array dari
TRACE_GUID_REGISTRATION struktur.
Setiap elemen mengidentifikasi kategori peristiwa yang disediakan penyedia.
Pada input, anggota Guid dari setiap struktur berisi GUID kelas pelacakan peristiwa yang ditetapkan oleh penyedia pendaftaran. GUID kelas mengidentifikasi kategori peristiwa yang disediakan penyedia. Penyedia menggunakan GUID kelas yang sama untuk mengatur anggota Guid EVENT_TRACE_HEADER saat memanggil fungsi TraceEvent untuk mencatat peristiwa.
Pada output, anggota RegHandle menerima handel ke pendaftaran GUID kelas peristiwa. Jika penyedia memanggil fungsi TraceEventInstance , gunakan anggota regHandleTRACE_GUID_REGISTRATION untuk mengatur anggota RegHandledari EVENT_INSTANCE_HEADER.
Parameter ini dapat berupa NULL jika penyedia hanya memanggil fungsi TraceEvent untuk mencatat peristiwa. Jika penyedia memanggil fungsi TraceEventInstance untuk mencatat peristiwa, parameter ini tidak boleh NULL.
[in] MofImagePath
Parameter ini tidak didukung. Atur ke NULL. Anda harus menggunakan Mofcomp.exe untuk mendaftarkan sumber daya MOF selama penyiapan aplikasi Anda. Untuk informasi selengkapnya, lihat Menerbitkan Skema Peristiwa Anda.
Windows XP dengan SP1, Windows XP, dan Windows 2000: Penunjuk ke string opsional yang menentukan jalur DLL atau program yang dapat dieksekusi yang berisi sumber daya yang ditentukan oleh MofResourceName. Parameter ini dapat berupa NULL jika penyedia peristiwa dan konsumen menggunakan mekanisme lain untuk berbagi informasi tentang kelas pelacakan peristiwa yang digunakan oleh penyedia.
[in] MofResourceName
Parameter ini tidak didukung. Atur ke NULL. Anda harus menggunakan Mofcomp.exe untuk mendaftarkan sumber daya MOF selama penyiapan aplikasi Anda. Untuk informasi selengkapnya, lihat Menerbitkan Skema Peristiwa Anda.
Windows XP dengan SP1, Windows XP, dan Windows 2000: Penunjuk ke string opsional yang menentukan sumber daya string MofImagePath. Sumber daya string berisi nama file MOF biner yang menjelaskan kelas pelacakan peristiwa yang didukung oleh penyedia.
[out] RegistrationHandle
Menerima handel pendaftaran penyedia. Gunakan handel yang dikembalikan saat Anda memanggil fungsi UnregisterTraceGuids .
Penting
Semua handel pendaftaran yang dibuat oleh DLL atau driver harus tidak terdaftar sebelum DLL atau driver dibongkar. Jika penyedia tidak terdaftar, crash akan terjadi ketika ETW mencoba memanggil panggilan balik penyedia.
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.
Penting
Fungsi ini juga dapat mengembalikan nilai yang dikembalikan oleh ControlCallback jika pengontrol memanggil EnableTrace untuk mengaktifkan penyedia dan penyedia belum disebut RegisterTraceGuids. Ketika ini terjadi, RegisterTraceGuids akan mengembalikan nilai pengembalian panggilan balik jika pendaftaran berhasil.
ERROR_INVALID_PARAMETER
Salah satu hal berikut ini benar:
- RequestAddress adalah NULL.
- ControlGuid adalah NULL.
- RegistrationHandle adalah NULL.
Windows XP dan Windows 2000:TraceGuidReg adalah NULL atau GuidCount kurang dari atau sama dengan nol.
Keterangan
Catatan
Sebagian besar pengembang tidak akan memanggil fungsi ini secara langsung. Sebagai gantinya, pengembang biasanya akan menggunakan kerangka kerja ETW. Misalnya, WPP berbasis TMF mengelola panggilan ke RegisterTraceGuids, TraceMessage, dan UnregisterTraceGuids atas nama Anda.
Fungsi ini membuka handel penyedia acara Klasik (gaya Windows 2000) yang dapat digunakan untuk menulis peristiwa ETW WPP berbasis MOF dan TMF melalui TraceEvent, TraceEventInstance, TraceMessage, dan TraceMessageVa.
Catatan
Untuk membuka handel penyedia gaya Windows Vista yang menulis peristiwa ETW berbasis manifes atau berbasis TraceLogging melalui EventWrite, gunakan EventRegister.
Jika ControlGuid penyedia sebelumnya telah terdaftar dan diaktifkan, pendaftaran berikutnya yang mereferensikan ControlGuid yang sama diaktifkan secara otomatis.
Proses dapat mendaftar hingga 1.024 GUID penyedia; namun, Anda harus membatasi jumlah penyedia yang didaftarkan proses Anda ke satu atau dua. Batas ini termasuk yang terdaftar menggunakan fungsi ini dan fungsi EventRegister .
Sebelum Windows Vista: Tidak ada batasan jumlah penyedia yang dapat didaftarkan oleh proses.
Contoh
Untuk contoh yang menggunakan RegisterTraceGuids, lihat Menulis Peristiwa Klasik.
Catatan
Header evntrace.h mendefinisikan RegisterTraceGuids 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
| 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 |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk