struktur PCW_REGISTRATION_INFORMATION (wdm.h)

Artikel
03/01/2024

Struktur PCW_REGISTRATION_INFORMATION memasok detail tentang penyedia dan counterset. Sebagian besar pengembang akan menggunakan fungsi RegisterXxx atau InitRegistrationInformationXxx yang dihasilkan CTRPP alih-alih menggunakan struktur ini secara langsung.

Sintaks

typedef struct _PCW_REGISTRATION_INFORMATION {
  ULONG                   Version;
  PCUNICODE_STRING        Name;
  ULONG                   CounterCount;
  PPCW_COUNTER_DESCRIPTOR Counters;
  PPCW_CALLBACK           Callback;
  PVOID                   CallbackContext;
  PCW_REGISTRATION_FLAGS  Flags;
} PCW_REGISTRATION_INFORMATION, *PPCW_REGISTRATION_INFORMATION;

Anggota

Version

Nilai numerik yang menentukan versi Penghitung Kinerja untuk Windows (PCW) yang diperlukan penyedia.

Saat berjalan pada Windows sebelum 10.0.19645 (NTDDI_VERSION < NTDDI_VERSION_MN), Version bidang harus diatur ke PCW_VERSION_1 (0x100). Saat berjalan pada Windows 10.0.19645 dan yang lebih baru (NTDDI_VERSION >= NTDDI_VERSION_MN), ini dapat diatur ke PCW_VERSION_1 (0x100) atau PCW_VERSION_2 (0x200). Version Jika bidang diatur ke nilai yang tidak dikenal, PcwRegister akan mengembalikan STATUS_INVALID_PARAMETER_2.

Saat menggunakan fungsi RegisterXxx atau InitRegistrationInformationXxx yang dihasilkan CTRPP, Version bidang akan diatur ke PCW_CURRENT_VERSION, yang setara dengan salah satu nilai berikut, tergantung pada nilai waktu kompilasi NTDDI_VERSION:

Kondisi	nilai PCW_CURRENT_VERSION
`NTDDI_VERSION < NTDDI_WIN10_FE`	PCW_VERSION_1 (0x0100)
`NTDDI_VERSION >= NTDDI_WIN10_FE`	PCW_VERSION_2 (0x0200)

Jika kode Anda dibuat dengan NTDDI_VERSION >= NTDDI_WIN10_FE tetapi perlu berjalan pada versi Windows yang lebih lama, Anda harus mengatur Version = PCW_VERSION_1 seperti yang dijelaskan dalam dokumentasi untuk PcwRegister.

Name

Penunjuk ke string yang berisi nama counterset untuk didaftarkan. String ini tidak boleh NULL atau kosong.

Perhatikan bahwa perbandingan nama penghitung tidak peka huruf besar/kecil. Jika nama counterset yang sama digunakan dalam dua pendaftaran counterset, konsumen akan mengumpulkan data dari kedua pendaftaran.

CounterCount

Jumlah deskriptor yang disediakan dalam Counters parameter .

Counters

Array deskriptor untuk penghitung counterset ini. Informasi dari deskriptor akan digunakan saat mengekstrak nilai penghitung dari blok data yang disediakan oleh panggilan ke PcwCreateInstance atau PcwAddInstance.

Callback

Penunjuk ke fungsi panggilan balik PCW_CALLBACK opsional yang memberi tahu penyedia tentang peristiwa yang terkait dengan penghitung ini. Bidang ini mungkin NULL jika panggilan balik tidak diperlukan (yaitu jika instans counterset akan dikelola melalui PcwCreateInstance dan PcwCloseInstance).

CallbackContext

Nilai pointer yang akan diteruskan ke fungsi panggilan balik yang ditentukan PCW_CALLBACK penyedia setiap kali dipanggil.

Flags

Bidang Flags hanya tersedia saat NTDDI_VERSION >= NTDDI_WIN10_MN.

Bidang Flags akan diabaikan jika Version bidang kurang dari PCW_VERSION_2.

Bidang ini Flags memungkinkan perilaku khusus .PcwRegister Atur ke kombinasi satu atau beberapa PCW_REGISTRATION_FLAGS nilai:

PCW_REGISTRATION_FLAGS	Makna
PcwRegistrationNone (0x0)	Default (tidak ada perilaku khusus yang diperlukan).
PcwRegistrationSiloNeutral (0x1)	Menunjukkan bahwa pendaftaran ini harus terlihat oleh konsumen di semua silo server. Secara default, pendaftaran hanya terlihat oleh konsumen di silo server yang aktif ketika pendaftaran dibuat (yaitu pendaftaran yang dilampirkan ke utas ketika `PcwRegister` dipanggil).

Keterangan

Fungsi PcwRegister mengambil Info parameter yang merupakan penunjuk ke struktur ini.

Fungsi InitRegistrationInformationXxx yang dihasilkan CTRPP

Sebagian besar pengembang tidak perlu menggunakan PCW_REGISTRATION_INFORMATION secara langsung. Sebaliknya, mereka akan mengkompilasi manifes dengan alat CTRPP dan menggunakan fungsi RegisterXxx atau InitRegistrationInformationXxx dari header yang dihasilkan CTRPP. Fungsi Register yang dihasilkan memanggil InitRegistrationInformation lalu memanggil PcwRegister (lihat PcwRegister untuk detailnya). Fungsi InitRegistrationInformation yang dihasilkan akan terlihat seperti ini:

EXTERN_C FORCEINLINE VOID
InitRegistrationInformationMyCounterset(
    __in_opt PPCW_CALLBACK Callback,
    __in_opt PVOID CallbackContext,
    __out PCW_REGISTRATION_INFORMATION* RegInfo
    )
{
    static const UNICODE_STRING Name = RTL_CONSTANT_STRING(L"My Counterset Name");
    static const PCW_COUNTER_DESCRIPTOR Descriptors[] = {
        { 0, 0, FIELD_OFFSET(MY_COUNTER_DATA, MyData1), RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData1)},
        { 1, 0, FIELD_OFFSET(MY_COUNTER_DATA, MyData2), RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData2)},
    };

#if CTRPP_VERIFY_COUNTER_SIZES

    //
    // Verify that structure member size matches manifest counter size.
    //

    C_ASSERT(RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData1) == sizeof(ULONGLONG));
    C_ASSERT(RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData2) == sizeof(ULONG));

#endif // CTRPP_VERIFY_COUNTER_SIZES

    PAGED_CODE();

    RtlZeroMemory(RegInfo, sizeof(*RegInfo));
    RegInfo->Version = PCW_CURRENT_VERSION;
    RegInfo->Name = &Name;
    RegInfo->CounterCount = RTL_NUMBER_OF(Descriptors);
    RegInfo->Counters = (PCW_COUNTER_DESCRIPTOR*)Descriptors;
    RegInfo->Callback = Callback;
    RegInfo->CallbackContext = CallbackContext;
}

Fungsi InitRegistrationInformation yang dihasilkan CTRPP akan diberi nama PrefixInitRegistrationInformationCounterset. Awalan biasanya kosong, tetapi mungkin ada jika -prefix parameter digunakan pada baris perintah CTRPP. Counterset adalah nama counterset, seperti yang ditentukan dalam manifes. Fungsi InitRegistrationInformation yang dihasilkan akan menginisialisasi struktur yang disediakan PCW_REGISTRATION_INFORMATION dengan nilai dari parameter fungsi dan manifes.

Fungsi InitRegistrationInformation yang dihasilkan CTRPP dapat secara opsional memverifikasi bahwa ukuran anggota struktur cocok dengan ukuran yang dideklarasikan dalam manifes. Secara default, CTRPP_VERIFY_COUNTER_SIZES diatur ke 0, menonaktifkan pemeriksaan ini. Untuk mengaktifkan pemeriksaan ini, #define CTRPP_VERIFY_COUNTER_SIZES 1 sebelum menyertakan header yang dihasilkan CTRPP. Jika pemeriksaan diaktifkan, ketidakcocokan ukuran akan memicu kesalahan kompilasi karena kegagalan kondisi C_ASSERT.