Fungsi PcwAddInstance (wdm.h)

Artikel
02/27/2024

Fungsi ini PcwAddInstance menambahkan instans yang ditentukan dari counterset ke buffer konsumen. Sebagian besar pengembang akan menggunakan fungsi AddXxx yang dihasilkan CTRPP alih-alih memanggil fungsi ini secara langsung. Lihat Keterangan di bawah ini untuk informasi selengkapnya.

Sintaks

NTSTATUS PcwAddInstance(
  [in] PPCW_BUFFER      Buffer,
  [in] PCUNICODE_STRING Name,
  [in] ULONG            Id,
  [in] ULONG            Count,
  [in] PPCW_DATA        Data
);

Parameter

[in] Buffer

Handel ke buffer yang dikelola sistem tempat instans counterset akan ditambahkan. Ketika buffer berasal dari PcwCallbackEnumerateInstances pemberitahuan, PcwAddInstance hanya akan merekam Nama dan Id instans. Ketika buffer berasal dari PcwCallbackCollectData pemberitahuan, PcwAddInstance akan merekam Nama, Id, dan Data (nilai penghitung) instans.

[in] Name

Penunjuk ke string Unicode yang berisi nama instans counterset. 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] Id

Nilai numerik yang menentukan Id (pengidentifikasi) yang terkait dengan instans counterset.

Nilai instans Id HARUS stabil dari waktu ke waktu (instans yang sama harus menggunakan nilai yang sama Id untuk semua pemanggilan panggilan balik), harus unik (misalnya jangan gunakan 0 untuk semua instans), dan harus kurang dari 0xFFFFFFFE (jangan gunakan PCW_ANY_INSTANCE_ID untuk instans apa pun). Jika memungkinkan, instans Id harus bermakna (misalnya, penghitung Proses mungkin menggunakan PID sebagai Id) alih-alih arbitrer (misalnya nomor urut).

[in] Count

Jumlah deskriptor yang disediakan dalam Data parameter .

[in] Data

Array deskriptor untuk blok data penyedia yang berisi nilai penghitung instans ini.

Nilai kembali

PcwAddInstance mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
`STATUS_SUCCESS`	Instans berhasil ditambahkan ke buffer.
`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 `PcwAddInstance` menentukan bahwa blok data pertama adalah 50 byte, status kesalahan ini dikembalikan.

Keterangan

Fungsi PcwAddInstance harus dipanggil oleh rutinitas PCW_CALLBACK yang ditentukan penyedia ketika jenis pemberitahuan adalah PcwCallbackEnumerateInstances atau PcwCallbackCollectData. yang Buffer akan digunakan berasal dari Info parameter untuk PCW_CALLBACK rutinitas, misalnya Info->EnumerateInstances.Buffer atau Info->CollectData.Buffer.

Saat dipanggil untuk PcwCallbackEnumerateInstances pemberitahuan, PcwAddInstance menambahkan Name nilai dan Id ke buffer. Saat dipanggil untuk PcwCallbackCollectData pemberitahuan, PcwAddInstance menambahkan Namenilai data penghitung , Id, dan ke buffer.

Fungsi Add*** yang dihasilkan CTRPP

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

EXTERN_C __inline NTSTATUS
AddMyCounterset(
    __in PPCW_BUFFER Buffer,
    __in PCUNICODE_STRING Name,
    __in ULONG Id,
    __in_opt const MY_COUNTER_DATA *MyCounterData
    )
{
    PCW_DATA Data[1];

    PAGED_CODE();

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

    return PcwAddInstance(Buffer,
                          Name,
                          Id,
                          1,
                          Data);
}

Fungsi Tambahkan yang dihasilkan CTRPP akan diberi nama AwalanTambahkanCounterset. 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 PcwAddInstance.

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

PCW_CALLBACK fungsi panggilan balik

Bagikan melalui