Fungsi PcwCreateInstance (wdm.h)

Artikel
03/08/2023

Fungsi ini PcwCreateInstance membuat instans counterset baru. Sebagian besar pengembang akan menggunakan fungsi CreateXxx yang dihasilkan CTRPP alih-alih memanggil fungsi ini secara langsung.

Sintaks

NTSTATUS PcwCreateInstance(
  [out] PPCW_INSTANCE     *Instance,
  [in]  PPCW_REGISTRATION Registration,
  [in]  PCUNICODE_STRING  Name,
  [in]  ULONG             Count,
  [in]  PPCW_DATA         Data
);

Parameter

[out] Instance

Penunjuk untuk menerima instans yang baru dibuat. Instans harus ditutup menggunakan PcwCloseInstance.

[in] Registration

Pointer ke pendaftaran counterset yang memiliki instans ini. Pendaftaran dibuat menggunakan PcwRegister.

[in] Name

Penunjuk ke string Unicode yang berisi nama instans penghitung. Ini tidak boleh NULL.

Nilai instans Name HARUS stabil dari waktu ke waktu (instans logis yang sama harus menggunakan nilai yang sama Name untuk semua pemanggilan panggilan balik) dan HARUS unik. Jika counterset terdaftar sebagai instans tunggal, instans Name harus kosong (panjang 0). Jika counterset yang terdaftar sebagai multi-instans, instans Name tidak boleh kosong. Pencocokan nama instans tidak peka huruf besar/kecil, sehingga Name nilai tidak boleh berbeda hanya menurut kasus.

[in] Count

Jumlah deskriptor yang disediakan dalam Data parameter .

[in] Data

Array deskriptor untuk blok data penyedia yang berisi nilai penghitung instans ini. Blok data yang direferensikan oleh deskriptor dapat diakses kapan saja dan harus tetap valid sampai instans ditutup oleh PcwCloseInstance atau PcwUnregister.

Nilai kembali

PcwCreateInstance mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
`STATUS_SUCCESS`	Instans berhasil dibuat.
`STATUS_INVALID_PARAMETER_4`	Jumlah struktur, yang ditentukan oleh `Count`, tidak valid untuk penyedia terdaftar.
`STATUS_INVALID_BUFFER_SIZE`	Salah satu blok data penyedia terlalu kecil. Misalnya, selama panggilan ke PcwRegister, penyedia menentukan bahwa penghitung `X` berada di offset 100 dari blok data pertama dengan ukuran 4 byte. Jika panggilan ke `PcwCreateInstance` menentukan bahwa blok data pertama adalah 50 byte, status kesalahan ini dikembalikan.
`STATUS_INTEGER_OVERFLOW`	Ukuran struktur, yang ditentukan oleh `Count`, meluapkan buffer data.

Keterangan

Penyedia counterset dapat menyediakan informasi kepada konsumen melalui dua sistem yang berbeda:

Penyedia dapat menyediakan PCW_CALLBACK fungsi yang akan dipanggil oleh Pustaka Penghitung Kinerja sesuai kebutuhan untuk mengumpulkan data. Untuk informasi selengkapnya tentang sistem ini, lihat dokumentasi untuk PCW_CALLBACK.
Penyedia dapat menggunakan PcwCreateInstance dan PcwCloseInstance untuk mempertahankan daftar instans yang tersedia dan data penghitung yang sesuai. Sistem ini mudah diterapkan tetapi terbatas pada fleksibilitas.

Sebelum penyedia menggunakan fungsi ini, penyedia harus memanggil PcwRegister fungsi untuk membuat pendaftaran.

Ketika instans baru tiba (misalnya ketika perangkat dicolokkan), penyedia harus mengalokasikan dan menginisialisasi blok data untuk instans, memanggil PcwCreateInstance dengan nama dan blok data untuk instans, lalu menjaga nilai di blok data diperbarui dengan nilai penghitung untuk instans. Ketika instans menjadi tidak valid (misalnya ketika perangkat dilepas), penyedia harus memanggil PcwCloseInstance lalu menghapus blok data.

Penyedia harus mempertahankan blok data (biasanya di kumpulan halaman atau tidak di-halaman) yang berisi nilai penghitung saat ini untuk setiap instans.

PcwCreateInstance akan secara otomatis menetapkan id unik untuk instans. Untuk memberikan nilai tertentu untuk id instans, terapkan PCW_CALLBACK fungsi alih-alih menggunakan PcwCreateInstance.

Gunakan fungsi PcwCloseInstance untuk menutup instans.

Fungsi CreateXxx yang dihasilkan CTRPP

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

EXTERN_C __inline NTSTATUS
CreateMyCounterset(
    __deref_out PPCW_INSTANCE *Instance,
    __in PCUNICODE_STRING Name,
    __in const MY_COUNTER_DATA *MyCounterData
    )
{
    PCW_DATA Data[1];

    PAGED_CODE();

    Data[0].Data = MyCounterData;
    Data[0].Size = sizeof(MY_COUNTER_DATA);

    return PcwCreateInstance(Instance,
                             MyCounterset,
                             Name,
                             1,
                             Data);
}

Fungsi Buat yang dihasilkan CTRPP akan diberi nama PrefixCreateCounterset. Awalan biasanya kosong, tetapi mungkin ada jika -prefix parameter digunakan pada baris perintah CTRPP. Counterset adalah nama counterset, seperti yang ditentukan dalam manifes. Fungsi ini akan memiliki parameter Data berdasarkan struktur yang ditentukan dalam manifes. Fungsi ini akan membungkus blok data yang disediakan pengguna ke dalam array PCW_DATA struktur dan kemudian memanggil PcwCreateInstance. Perhatikan bahwa fungsi mereferensikan variabel Counterset (MyCounterset dalam contoh), yang merupakan variabel global yang menyimpan handel pendaftaran counterset yang diinisialisasi oleh fungsi RegisterXxx yang dihasilkan CTRPP.

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

Fungsi PcwCloseInstance

Fungsi PcwRegister

Bagikan melalui