struktur WDF_QUERY_INTERFACE_CONFIG (wdfqueryinterface.h)

Artikel
08/08/2023

[Hanya berlaku untuk KMDF]

Struktur WDF_QUERY_INTERFACE_CONFIG menjelaskan antarmuka yang ditentukan driver.

Sintaks

typedef struct _WDF_QUERY_INTERFACE_CONFIG {
  ULONG                                          Size;
  PINTERFACE                                     Interface;
  const GUID                                     *InterfaceType;
  BOOLEAN                                        SendQueryToParentStack;
  PFN_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST EvtDeviceProcessQueryInterfaceRequest;
  BOOLEAN                                        ImportInterface;
} WDF_QUERY_INTERFACE_CONFIG, *PWDF_QUERY_INTERFACE_CONFIG;

Anggota

Size

Ukuran, dalam byte, dari struktur ini.

Interface

Penunjuk ke struktur ANTARMUKA yang menjelaskan antarmuka yang ditentukan driver.

InterfaceType

Penunjuk ke GUID yang mengidentifikasi antarmuka.

Catatan

Saat memperkenalkan versi baru antarmuka yang ada, buat GUID baru alih-alih merevisi bidang Ukuran atau Versi dari struktur ANTARMUKA . Untuk informasi selengkapnya, lihat Menggunakan Antarmuka Driver-Defined.

SendQueryToParentStack

Jika TRUE, dan jika driver Anda menentukan objek perangkat yang mewakili objek perangkat fisik (PDO) saat memanggil WdfDeviceAddQueryInterface, kerangka kerja mengirimkan permintaan untuk antarmuka ke bagian atas tumpukan driver perangkat induk. Jika anggota ini FALSE, atau jika objek perangkat tidak mewakili PDO, kerangka kerja tidak mengirim permintaan ke tumpukan perangkat induk. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

EvtDeviceProcessQueryInterfaceRequest

Penunjuk ke fungsi panggilan balik peristiwa EvtDeviceProcessQueryInterfaceRequest driver Anda, yang dipanggil ketika driver lain meminta antarmuka.

ImportInterface

Jika TRUE, antarmuka mendukung komunikasi dua arah antara driver dan driver yang meminta antarmuka.

Jika anggota ini FALSE, antarmuka mendukung komunikasi satu arah dari driver Anda ke driver yang meminta antarmuka.

Keterangan

Struktur WDF_QUERY_INTERFACE_CONFIG digunakan sebagai input ke metode WdfDeviceAddQueryInterface .

Untuk setiap antarmuka yang ditentukan driver yang diekspor driver, Anda harus mengalokasikan struktur WDF_QUERY_INTERFACE_CONFIG yang mewakili antarmuka. Driver lain dapat meminta akses ke antarmuka dengan memanggil WdfFdoQueryForInterface.

Jika Anda ingin antarmuka Anda mendukung komunikasi dua arah antara driver yang meminta dan driver Anda, atur anggota ImportInterface ke TRUE. Jika ImportInterfaceTRUE, struktur yang disediakan oleh driver yang meminta dapat berisi data yang dapat dibaca driver Anda. Dalam hal ini:

Fungsi panggilan balik EvtDeviceProcessQueryInterfaceRequest diperlukan, dan harus menginisialisasi struktur antarmuka yang disediakan driver yang meminta.
Karena fungsi panggilan balik EvtDeviceProcessQueryInterfaceRequest menyediakan antarmuka ke driver yang meminta, anggota AntarmukaWDF_QUERY_INTERFACE_CONFIG dapat berupa NULL. Jika Anda menyediakan penunjuk non-NULL , kerangka kerja memverifikasi bahwa nilai ukuran dan versi yang disediakan driver yang meminta sama dengan atau lebih besar dari nilai dalam struktur ANTARMUKA terdaftar Anda. Jika salah satu nilai ini lebih kecil, kerangka kerja akan menolak permintaan. Jika Anda tidak memberikan nilai untuk Antarmuka, fungsi panggilan balik EvtDeviceProcessQueryInterfaceRequest Anda harus memverifikasi nilai tersebut.

Jika Anda ingin antarmuka Anda hanya mendukung komunikasi satu arah dari driver Anda ke driver yang meminta, atur ImportInterface adalah FALSE. Struktur antarmuka yang disediakan driver yang meminta hanya dapat menerima data yang disediakan driver Anda. Dalam hal ini:

Fungsi panggilan balik EvtDeviceProcessQueryInterfaceRequest bersifat opsional.
Anggota Antarmuka tidak boleh NULL. Kerangka kerja memverifikasi bahwa nilai GUID, ukuran, dan versi yang disediakan driver yang meminta cocok dengan yang Anda berikan, dan kerangka kerja menolak permintaan jika nilainya tidak cocok. Jika nilainya valid, kerangka kerja menginisialisasi struktur antarmuka yang disediakan driver yang meminta dengan menggunakan nilai yang Anda berikan untuk Antarmuka.

Selain itu, anggota Antarmuka dapat berupa NULL jika nilai anggota SendQueryToParentStack adalah TRUE.

Jika anggota Antarmuka bukan NULL, kerangka kerja menyalin nilai ke ruang penyimpanan internal. Oleh karena itu, driver dapat mengalokasikan struktur INTERFACE di ruang penyimpanan lokal sementara.

Ketika driver Anda memanggil WdfDeviceAddQueryInterface, driver dapat mengaitkan antarmuka dengan objek perangkat kerangka kerja yang mewakili objek perangkat fungsi (FDO) atau objek perangkat fisik (PDO). Jika driver mengaitkan antarmuka dengan PDO, driver dapat mengatur anggota SendQueryToParentStack dari struktur WDF_QUERY_INTERFACE_CONFIG ke TRUE. Ketika kerangka kerja mencegat permintaan antarmuka, kerangka kerja memeriksa anggota SendQueryToParentStack dan, jika diatur ke TRUE, kerangka kerja mengirimkan permintaan ke bagian atas tumpukan driver induk PDO. Akibatnya, permintaan turun dua tumpukan driver: pertama, tumpukan yang berisi driver yang meminta antarmuka dan, kedua, tumpukan induk perangkat antarmuka.

Kerangka kerja menyediakan dua metode referensi/dereferensi yang dapat Anda gunakan dengan antarmuka Anda dengan menentukan alamatnya untuk anggota InterfaceReference dan InterfaceDereference dari struktur ANTARMUKA . Untuk informasi selengkapnya tentang metode ini, lihat WdfDeviceInterfaceReferenceNoOp dan WdfDeviceInterfaceDereferenceNoOp.

Driver harus menginisialisasi struktur ini dengan memanggil WDF_QUERY_INTERFACE_CONFIG_INIT.

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