Fungsi WdfWmiInstanceCreate (wdfwmi.h)

Artikel
03/08/2023

[Hanya berlaku untuk KMDF]

Metode WdfWmiInstanceCreate membuat objek instans WMI yang mewakili instans penyedia data WMI.

Sintaks

NTSTATUS WdfWmiInstanceCreate(
  [in]            WDFDEVICE                Device,
  [in]            PWDF_WMI_INSTANCE_CONFIG InstanceConfig,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES   InstanceAttributes,
  [out, optional] WDFWMIINSTANCE           *Instance
);

Parameter

[in] Device

Handel ke objek perangkat kerangka kerja yang mewakili perangkat tempat instans dibuat. Objek perangkat tidak bisa menjadi objek perangkat kontrol.

[in] InstanceConfig

Penunjuk ke struktur WDF_WMI_INSTANCE_CONFIG yang diinisialisasi penelepon, yang berisi informasi konfigurasi untuk instans penyedia data WMI.

[in, optional] InstanceAttributes

Penunjuk ke struktur WDF_OBJECT_ATTRIBUTES yang dialokasikan penelepon yang berisi atribut objek yang disediakan driver untuk objek instans WMI baru. (Anggota ParentObject struktur harus NULL.) Parameter ini bersifat opsional dan dapat WDF_NO_OBJECT_ATTRIBUTES.

[out, optional] Instance

Penunjuk ke lokasi yang menerima handel ke objek instans WMI baru. Parameter ini bersifat opsional dan dapat berupa NULL.

Nilai kembali

WdfWmiInstanceCreate mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode ini mungkin mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Parameter yang tidak valid terdeteksi.
STATUS_INFO_LENGTH_MISMATCH	Ukuran struktur WDF_WMI_INSTANCE_CONFIG yang dirujuk parameter InstanceConfig salah.
STATUS_INSUFFICIENT_RESOURCES	Memori tidak cukup.
STATUS_INTEGER_OVERFLOW	Driver mengatur anggota UseContextForQuery dari struktur WDF_WMI_INSTANCE_CONFIG ke TRUE tetapi menentukan ukuran ruang konteks yang lebih besar dari ULONG_MAX dalam struktur WDF_OBJECT_ATTRIBUTES parameter InstanceAttributes.

Untuk daftar nilai pengembalian lain yang mungkin dikembalikan oleh metode WdfWmiInstanceCreate , lihat Kesalahan Pembuatan Objek Kerangka Kerja.

Metode ini juga dapat mengembalikan nilai NTSTATUS lainnya.

Pemeriksaan bug terjadi jika driver menyediakan handel objek yang tidak valid.

Keterangan

Jika driver membuat beberapa instans penyedia, driver harus memanggil WdfWmiProviderCreate untuk membuat objek penyedia sebelum memanggil WdfWmiInstanceCreate. Driver meneruskan handel objek penyedia ke WdfWmiInstanceCreate dengan menempatkan handel dalam struktur WDF_WMI_INSTANCE_CONFIG . (Jika driver menyediakan handel objek penyedia, parameter Perangkat tidak digunakan dan dapat NULL.)

Jika driver membuat satu instans penyedia, driver tidak perlu memanggil WdfWmiInstanceCreate sebelum memanggil WdfWmiInstanceCreate. Dalam hal ini, WdfWmiInstanceCreate juga membuat objek penyedia WMI. Oleh karena itu, struktur WDF_WMI_INSTANCE_CONFIG driver harus menyertakan pointer ke struktur WDF_WMI_PROVIDER_CONFIG yang menjelaskan penyedia data WMI.

Kerangka kerja menginstruksikan WMI untuk membuat nama instans dinamis, yang dapat digunakan aplikasi, dari ID instans perangkat objek perangkat fisik (PDO) driver. (Kerangka kerja tidak mendukung nama instans statis yang diatur driver Windows Driver Model (WDM) dalam struktur IRP_MN_REGINFO atau IRP_MN_REGINFO_EX .)

Induk objek instans WMI adalah objek penyedia WMI. Driver tidak dapat mengubah induk ini, dan anggota ParentObject atau struktur WDF_OBJECT_ATTRIBUTES harus NULL.

Setelah driver memanggil WdfWmiInstanceCreate, driver dapat memanggil WdfWmiInstanceGetProvider untuk mendapatkan handel ke objek penyedia induk dan WdfWmiInstanceGetDevice untuk mendapatkan handel ke perangkat penyedia.

Untuk informasi selengkapnya tentang metode WdfWmiInstanceCreate , lihat Mendukung WMI di driver Framework-Based.

Jika anggota Register dari struktur WDF_WMI_INSTANCE_CONFIG yang ditunjuk instanceConfig adalah TRUE, WdfWmiInstanceCreatemendaftarkan instans penyedia secara sinkron (yaitu, sebelum mengembalikan) jika metode ini dipanggil di IRQL = PASSIVE_LEVEL dan secara asinkron jika dipanggil di IRQL > PASSIVE_LEVEL.

Contoh

Contoh kode berikut berasal dari driver sampel PCIDRV . Contoh ini mendaftarkan nama sumber daya MOF untuk perangkat, menginisialisasi struktur WDF_WMI_PROVIDER_CONFIG dan struktur WDF_WMI_INSTANCE_CONFIG, dan memanggil WdfWmiInstanceCreate.

NTSTATUS
PciDrvWmiRegistration(
    WDFDEVICE  Device
    )
{
    WDF_WMI_PROVIDER_CONFIG  providerConfig;
    WDF_WMI_INSTANCE_CONFIG  instanceConfig;
    NTSTATUS  status;
    DECLARE_CONST_UNICODE_STRING(mofRsrcName, MOFRESOURCENAME);

    status = WdfDeviceAssignMofResourceName(
                                            Device,
                                            &mofRsrcName
                                            );
    if (!NT_SUCCESS(status)) {
        return status;
    }
    WDF_WMI_PROVIDER_CONFIG_INIT(
                                 &providerConfig,
                                 &PCIDRV_WMI_STD_DATA_GUID
                                 );
    providerConfig.MinInstanceBufferSize = sizeof(PCIDRV_WMI_STD_DATA);

    WDF_WMI_INSTANCE_CONFIG_INIT_PROVIDER_CONFIG(
                                                 &instanceConfig,
                                                 &providerConfig
                                                 );
    instanceConfig.Register = TRUE;
    instanceConfig.EvtWmiInstanceQueryInstance = EvtWmiDeviceInfoQueryInstance;
    instanceConfig.EvtWmiInstanceSetInstance = EvtWmiDeviceInfoSetInstance;

    status = WdfWmiInstanceCreate(
                                  Device,
                                  &instanceConfig,
                                  WDF_NO_OBJECT_ATTRIBUTES,
                                  WDF_NO_HANDLE
                                  );
    if (!NT_SUCCESS(status)) {
        return status;
    }
    return status;
}

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Header	wdfwmi.h (termasuk Wdf.h)
Pustaka	Wdf01000.sys (lihat Penerapan Versi Pustaka Kerangka Kerja.)
IRQL	<=DISPATCH_LEVEL
Aturan kepatuhan DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)