Fungsi WdfDeviceAddQueryInterface (wdfqueryinterface.h)

Artikel
08/08/2023

[Berlaku untuk KMDF saja]

Metode WdfDeviceAddQueryInterface membuat antarmuka yang ditentukan driver yang dapat dikueri dan digunakan driver lain.

Sintaks

NTSTATUS WdfDeviceAddQueryInterface(
  [in] WDFDEVICE                   Device,
  [in] PWDF_QUERY_INTERFACE_CONFIG InterfaceConfig
);

Parameter

[in] Device

Handel ke objek perangkat kerangka kerja.

[in] InterfaceConfig

Penunjuk ke struktur WDF_QUERY_INTERFACE_CONFIG yang dialokasikan driver yang menjelaskan antarmuka.

Nilai kembali

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

Menampilkan kode	Deskripsi
STATUS_INVALID_DEVICE_REQUEST	Metode ini dipanggil pada IRQL yang salah.
STATUS_INVALID_PARAMETER	Parameter input (mungkin termasuk anggota struktur WDF_QUERY_INTERFACE_CONFIG) tidak valid.
STATUS_INFO_LENGTH_MISMATCH	Ukuran struktur WDF_QUERY_INTERFACE_CONFIG salah.
STATUS_INSUFFICIENT_RESOURCES	Memori tidak cukup.

Untuk daftar nilai pengembalian tambahan, lihat Kesalahan Pembuatan Objek Kerangka Kerja.

Metode ini mungkin juga mengembalikan nilai NTSTATUS lainnya.

Pemeriksaan bug sistem terjadi jika driver memasok handel objek yang tidak valid.

Keterangan

Catatan

WdfDeviceAddQueryInterface tidak dapat dipanggil untuk perangkat kontrol.

Driver yang membuat antarmuka yang ditentukan driver biasanya memanggil fungsi panggilan balik WdfDeviceAddQueryInterface dari dalam fungsi panggilan balik EvtDriverDeviceAdd atau EvtDevicePrepareHardware .

Setelah driver memanggil WdfDeviceAddQueryInterface untuk membuat antarmuka yang ditentukan driver, driver berbasis kerangka kerja lain dapat mengakses antarmuka dengan memanggil WdfFdoQueryForInterface.

Untuk informasi selengkapnya tentang antarmuka yang ditentukan driver, lihat Menggunakan Antarmuka Driver-Defined.

Contoh

Contoh kode berikut berasal dari contoh sopir bus Toaster . Contoh ini membuat antarmuka yang ditentukan driver yang menggunakan struktur TOASTER_INTERFACE_STANDARD sampel pemangsa.

typedef struct _TOASTER_INTERFACE_STANDARD {
 INTERFACE  InterfaceHeader;
  PTOASTER_GET_CRISPINESS_LEVEL  GetCrispinessLevel;
  PTOASTER_SET_CRISPINESS_LEVEL  SetCrispinessLevel;
  PTOASTER_IS_CHILD_PROTECTED  IsSafetyLockEnabled;
} TOASTER_INTERFACE_STANDARD, *PTOASTER_INTERFACE_STANDARD;

TOASTER_INTERFACE_STANDARD  ToasterInterface;
WDF_QUERY_INTERFACE_CONFIG  qiConfig;

//
// Initialize the ToasterInterface structure.
//
RtlZeroMemory(
              &ToasterInterface,
              sizeof(ToasterInterface)
              );

ToasterInterface.InterfaceHeader.Size = sizeof(ToasterInterface);
ToasterInterface.InterfaceHeader.Version = 1;
ToasterInterface.InterfaceHeader.Context = (PVOID)hChild;

ToasterInterface.InterfaceHeader.InterfaceReference =
        WdfDeviceInterfaceReferenceNoOp;
ToasterInterface.InterfaceHeader.InterfaceDereference =
        WdfDeviceInterfaceDereferenceNoOp;

ToasterInterface.GetCrispinessLevel = Bus_GetCrispinessLevel;
ToasterInterface.SetCrispinessLevel = Bus_SetCrispinessLevel;
ToasterInterface.IsSafetyLockEnabled = Bus_IsSafetyLockEnabled;

//
// Initialize the qiConfig structure.
//
WDF_QUERY_INTERFACE_CONFIG_INIT(
                                &qiConfig,
                                (PINTERFACE)&ToasterInterface,
                                &GUID_TOASTER_INTERFACE_STANDARD,
                                NULL
                                );

//
// Create the interface.
//
status = WdfDeviceAddQueryInterface(
                                    hChild,
                                    &qiConfig
                                    );
if (!NT_SUCCESS(status)) {
    return status;
}

Persyaratan

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