Fungsi PcwRegister (wdm.h)

Artikel
02/29/2024

Fungsi ini PcwRegister membuat pendaftaran counterset baru. Sebagian besar pengembang akan menggunakan fungsi RegisterXxx yang dihasilkan CTRPP alih-alih memanggil fungsi ini secara langsung.

Sintaks

NTSTATUS PcwRegister(
  [out] PPCW_REGISTRATION             *Registration,
  [in]  PPCW_REGISTRATION_INFORMATION Info
);

Parameter

[out] Registration

Penunjuk ke PPCW_REGISTRATION. Menerima handel ke pendaftaran baru. Pendaftaran harus ditutup menggunakan PcwUnregister.

[in] Info

Pointer ke struktur PCW_REGISTRATION_INFORMATION yang berisi detail tentang counterset yang didaftarkan.

Nilai kembali

PcwRegister mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
`STATUS_SUCCESS`	Counterset berhasil didaftarkan.
`STATUS_INTEGER_OVERFLOW`	Jumlah penghitung yang diekspos oleh pendaftaran ini melebihi maksimum yang didukung.
`STATUS_NO_MEMORY`	Tidak tersedia cukup ruang untuk mengalokasikan memori untuk penghitung.
`STATUS_INVALID_PARAMETER_2`	Masalah ditemukan dalam `Info` parameter . Lihat di bawah ini untuk beberapa kemungkinan penyebabnya.

PcwRegister dapat kembali STATUS_INVALID_PARAMETER_2 dalam kasus berikut:

Bidang Info->Name->Length adalah 0 atau bukan kelipatan .sizeof(WCHAR)
Bidang Info->Version tidak cocok dengan nilai yang didukung untuk versi Windows ini. Saat berjalan di 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).
Bidang Info->Flags berisi nilai yang tidak dikenali oleh versi Windows yang sedang berjalan.

Keterangan

Penyedia memanggil fungsi ini untuk membuat pendaftaran counterset baru. Semua argumen input diambil sehingga penelepon tidak perlu menyimpan salinannya.

Secara default, counterset baru hanya terlihat oleh silo server yang aktif pada saat pendaftaran (yaitu PcwRegister mengaitkan pendaftaran yang baru dibuat dengan silo server yang dilampirkan ke utas ketika PcwRegister dipanggil). Jika berjalan pada Windows 10.0.19645 dan yang lebih baru (NTDDI_VERSION >= NTDDI_VERSION_MN) Anda dapat membuat pendaftaran counterset yang terlihat oleh semua silo server dengan mengatur PCW_REGISTRATION_INFORMATION::Version ke PCW_VERSION_2 dan mengatur PCW_REGISTRATION_INFORMATION::Flags ke PcwRegistrationSiloNeutral.

Fungsi RegisterXxx yang dihasilkan CTRPP

Sebagian besar pengembang tidak perlu menelepon PcwRegister secara langsung. Sebaliknya, mereka akan mengkompilasi manifes dengan alat CTRPP dan menggunakan fungsi RegisterXxx dari header yang dihasilkan CTRPP. Fungsi yang dihasilkan akan terlihat seperti ini:

EXTERN_C FORCEINLINE NTSTATUS
RegisterMyCounterset(
    __in_opt PPCW_CALLBACK Callback,
    __in_opt PVOID CallbackContext
    )
{
    PCW_REGISTRATION_INFORMATION RegInfo;

    PAGED_CODE();

    InitRegistrationInformationMyCounterset(Callback, CallbackContext, &RegInfo);

    return PcwRegister(&MyCounterset, &RegInfo);
}

Fungsi Register yang dihasilkan CTRPP akan diberi nama PrefixRegisterCounterset. Awalan biasanya kosong, tetapi mungkin ada jika -prefix parameter digunakan pada baris perintah CTRPP. Counterset adalah nama penghitung, seperti yang ditentukan dalam manifes. Fungsi Register yang dihasilkan akan memanggil fungsi PrefixInitRegistrationInformationCounterset untuk menginisialisasi PCW_REGISTRATION_INFORMATION struktur dan kemudian memanggil PcwRegister untuk membuat pendaftaran baru dan menyimpan handel dalam variabel Counterset global (dinyatakan dalam header yang dihasilkan CTRPP, MyCounterset dalam contoh).

Dalam beberapa kasus, fungsi Tambahkan yang dihasilkan CTRPP mungkin tidak sesuai.

Jika Anda harus mengkompilasi dengan NTDDI_VERSION >= NTDDI_VERSION_FE tetapi harus berjalan pada versi Windows yang lebih lama, fungsi Register yang dihasilkan CTRPP tidak akan berfungsi karena mengatur RegInfo.Version = PCW_CURRENT_VERSION. Ketika NTDDI_VERSION >= NTDDI_VERSION_FE, PCW_CURRENT_VERSION akan diatur ke PCW_VERSION_2, menyebabkan PcwRegister kesalahan dikembalikan.
Jika Anda perlu mendukung beberapa pendaftaran counterset (misalnya untuk mendukung pendaftaran terpisah per silo server), fungsi Register yang dihasilkan CTRPP tidak akan berfungsi karena menyimpan handel yang dikembalikan dalam variabel global.
Jika Anda ingin membuat pendaftaran penghitung silo-netral, fungsi Register yang dihasilkan CTRPP tidak akan berfungsi karena tidak ada cara untuk mengubah nilai RegInfo.Flags sebelum memanggil PcwRegister.

Dalam kasus ini, gunakan kode seperti berikut ini alih-alih memanggil fungsi Register yang dihasilkan CTRPP:

PCW_REGISTRATION_INFORMATION RegInfo;
InitRegistrationInformationMyCounterset(Callback, CallbackContext, &RegInfo);

// Modify RegInfo as needed,
// e.g. RegInfo.Version = PCW_VERSION_1,
// or RegInfo.Flags = PcwRegistrationSiloNeutral.

// If needed, use another variable to store the handle instead of MyCounterset.
Status = PcwRegister(&MyCounterset, &RegInfo);

Fungsi InitRegistrationInformationXxx yang dihasilkan CTRPP menginisialisasi RegInfo struktur berdasarkan deklarasi dari manifes. Untuk informasi selengkapnya tentang fungsi InitRegistrationInformation yang dihasilkan, lihat dokumentasi untuk PCW_REGISTRATION_INFORMATION.

Jika menggunakan variabel handel Anda sendiri alih-alih Counterset untuk menyimpan handel, Anda mungkin juga perlu memanggil PcwUnregister dan PcwCreateInstance langsung alih-alih menggunakan fungsi UnregisterXxx yang dihasilkan CTRPP dan BuatXxx .

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia di Windows 7 dan versi Windows yang lebih baru.
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h, Ntddk.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL

Lihat juga

PcwUnregister

_PCW_REGISTRATION_INFORMATION

Bagikan melalui