Bagikan melalui


Fungsi RegisterTraceGuidsA (evntrace.h)

Fungsi RegisterTraceGuids mendaftarkan penyedia pelacakan peristiwa ETW Classic (gaya 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 usang. Kode baru harus menggunakan EventRegister untuk mendaftarkan penyedia pelacakan peristiwa ETW gaya Windows Vista (Crimson) .

Sintaksis

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]     TRACEGUID_HANDLE         *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 TraceGuidRegNULL, 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, Guid anggota 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 RegHandle TRACE_GUID_REGISTRATION untuk mengatur anggota RegHandle EVENT_INSTANCE_HEADER.

Parameter ini dapat NULL jika penyedia hanya memanggil fungsi TraceEvent untuk mencatat peristiwa. Jika penyedia memanggil fungsi TraceEventInstance untuk mencatat peristiwa, parameter ini tidak dapat 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: Pointer ke string opsional yang menentukan jalur DLL atau program yang dapat dieksekusi yang berisi sumber daya yang ditentukan oleh MofResourceName. Parameter ini dapat 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: Pointer 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.

Mengembalikan 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 memanggil RegisterTraceGuids. Ketika ini terjadi, RegisterTraceGuids akan mengembalikan nilai pengembalian panggilan balik jika pendaftaran berhasil.

  • ERROR_INVALID_PARAMETER

    Salah satu hal berikut ini benar:

    • RequestAddress NULL .
    • ControlGuidNULL .
    • RegistrationHandleNULL .

    Windows XP dan Windows 2000:TraceGuidReg NULL atau GuidCount kurang dari atau sama dengan nol.

Komentar

Nota

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 Classic (gaya Windows 2000) yang dapat digunakan untuk menulis peristiwa ETW WPP berbasis MOF dan TMF melalui TraceEvent, TraceEventInstance, TraceMessage, dan TraceMessageVa.

Nota

Untuk membuka penanganan penyedia gaya Windows Vista yang menulis peristiwa ETW berbasis manifes atau berbasis TraceLogging melalui EventWrite, gunakan EventRegister.

Jika ControlGuid penyedia telah didaftarkan dan diaktifkan sebelumnya, 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 menggunakanRegisterTraceGuids , lihat Menulis Peristiwa Klasik.

Nota

Header evntrace.h mendefinisikan RegisterTraceGuids sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta preprosedur 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

Syarat Nilai
klien minimum yang didukung Windows 2000 Professional [aplikasi desktop | Aplikasi UWP]
server minimum yang didukung Windows 2000 Server [aplikasi desktop | Aplikasi UWP]
Platform Target Windows
Header evntrace.h
Pustaka Sechost.lib pada Windows 8.1 dan Windows Server 2012 R2; Advapi32.lib pada 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

EnableTrace

UnregisterTraceGuids