EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST fungsi panggilan balik (wdfqueryinterface.h)

Artikel
08/08/2023

[Hanya berlaku untuk KMDF]

Fungsi panggilan balik peristiwa EvtDeviceProcessQueryInterfaceRequest driver memeriksa permintaan driver lain untuk akses ke antarmuka yang ditentukan driver, sebelum kerangka kerja meneruskan antarmuka ke driver yang meminta.

Sintaks

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST EvtWdfDeviceProcessQueryInterfaceRequest;

NTSTATUS EvtWdfDeviceProcessQueryInterfaceRequest(
  [in]      WDFDEVICE Device,
  [in]      LPGUID InterfaceType,
  [in, out] PINTERFACE ExposedInterface,
  [in, out] PVOID ExposedInterfaceSpecificData
)
{...}

Parameter

[in] Device

Handel ke objek perangkat kerangka kerja.

[in] InterfaceType

Penunjuk ke GUID yang mengidentifikasi antarmuka yang ditentukan driver.

[in, out] ExposedInterface

Penunjuk ke struktur ANTARMUKA yang menjelaskan antarmuka yang ditentukan driver dan disediakan oleh driver yang meminta akses ke antarmuka.

[in, out] ExposedInterfaceSpecificData

Penunjuk ke informasi tambahan, opsional, ditentukan driver, khusus antarmuka. Driver berbasis kerangka kerja menentukan nilai ini dengan menyediakan nilai parameter InterfaceSpecificDatanon-NULL saat memanggil WdfFdoQueryForInterface.

Mengembalikan nilai

Jika fungsi panggilan balik EvtDeviceProcessQueryInterfaceRequest menerima GUID yang didukungnya, dan jika fungsi tidak mengalami kesalahan, fungsi harus mengembalikan STATUS_SUCCESS atau nilai status lain yang NT_SUCCESS(statusnya) sama dengan TRUE. Kerangka kerja terus menerus meneruskan permintaan ke bawah tumpukan untuk melihat apakah driver tambahan juga mendukung antarmuka.

Fungsi panggilan balik EvtDeviceProcessQueryInterfaceRequest harus mengembalikan STATUS_NOT_SUPPORTED jika menentukan bahwa, untuk kasus tertentu, itu tidak akan melayani antarmuka. Kerangka kerja terus meneruskan permintaan ke bawah tumpukan untuk melihat apakah driver lain mendukung antarmuka. Untuk informasi selengkapnya tentang situasi ini, lihat bagian Keterangan berikut ini.

Jika fungsi panggilan balik mengalami kesalahan, fungsi tersebut harus mengembalikan nilai status yang NT_SUCCESS(statusnya) sama dengan FALSE. Kerangka kerja gagal permintaan driver lain untuk antarmuka dan tidak meneruskan permintaan ke bawah tumpukan.

Keterangan

Driver berbasis kerangka kerja mendaftarkan fungsi panggilan balik peristiwa EvtDeviceProcessQueryInterfaceRequest dengan memanggil WdfDeviceAddQueryInterface.

Jika antarmuka yang ditentukan driver hanya mendukung komunikasi satu arah dan mengatur anggota ImportInterface dari struktur WDF_QUERY_INTERFACE_CONFIG yang menjelaskan antarmuka ke FALSE, fungsi panggilan balik EvtDeviceProcessQueryInterfaceRequest bersifat opsional. Ketika driver lain memanggil WdfFdoQueryForInterface, kerangka kerja menyalin nilai antarmuka yang ditentukan driver ke dalam struktur INTERFACE driver yang meminta dan kemudian memanggil fungsi panggilan balik. Untuk komunikasi satu arah, Anda perlu menyediakan fungsi panggilan balik hanya jika Anda ingin driver memeriksa, dan mungkin memodifikasi, nilai antarmuka sebelum kerangka kerja mengembalikannya ke driver yang meminta.

Driver Anda harus menyediakan fungsi panggilan balik peristiwa EvtDeviceProcessQueryInterfaceRequest jika driver menentukan antarmuka yang mendukung komunikasi dua arah (dan mengatur anggota ImportInterface dari struktur WDF_QUERY_INTERFACE_CONFIG ke TRUE). Fungsi panggilan balik diperlukan karena, jika ImportInterfaceTRUE dan driver lain memanggil WdfFdoQueryForInterface, kerangka kerja tidak menyalin antarmuka yang ditentukan driver ke dalam struktur antarmuka driver yang meminta. Sebagai gantinya, fungsi panggilan balik harus memperbarui struktur antarmuka driver yang meminta.

Fungsi panggilan balik dapat mengubah antarmuka. Secara khusus, ia dapat:

Ubah nilai apa pun di setiap anggota antarmuka.
Alokasikan konteks khusus instans dinamis dengan memodifikasi anggota Konteks struktur INTERFACE .

Kerangka kerja memanggil fungsi panggilan balik EvtDeviceProcessQueryInterfaceRequest driver Anda hanya untuk GUID yang telah didaftarkan driver dengan memanggil WdfDeviceAddQueryInterface. Oleh karena itu, fungsi panggilan balik ini tidak menggunakan nilai pengembalian STATUS_NOT_SUPPORTED untuk melaporkan GUID yang tidak terduga. Sebaliknya, fungsi panggilan balik EvtDeviceProcessQueryInterfaceRequest harus mengembalikan STATUS_NOT_SUPPORTED ketika menentukan bahwa, untuk kasus tertentu, ia tidak akan menangani antarmuka. Misalnya, berdasarkan data yang disediakan driver yang meminta, driver Anda mungkin menentukan bahwa driver tingkat bawah harus melayani permintaan antarmuka. Nilai pengembalian STATUS_NOT_SUPPORTED menginformasikan kerangka kerja bahwa driver Anda tidak melayani permintaan antarmuka, tetapi driver tingkat bawah mungkin melayaninya.

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

Contoh

Untuk menentukan fungsi panggilan balik EvtDeviceProcessQueryInterfaceRequest , Anda harus terlebih dahulu memberikan deklarasi fungsi yang mengidentifikasi jenis fungsi panggilan balik yang Anda tentukan. Windows menyediakan sekumpulan tipe fungsi panggilan balik untuk driver. Mendeklarasikan fungsi menggunakan jenis fungsi panggilan balik membantu Analisis Kode untuk Driver, Pemverifikasi Driver Statis (SDV), dan alat verifikasi lainnya menemukan kesalahan, dan itu adalah persyaratan untuk menulis driver untuk sistem operasi Windows.

Misalnya, untuk menentukan fungsi panggilan balik EvtDeviceProcessQueryInterfaceRequest yang diberi nama MyDeviceProcessQueryInterfaceRequest, gunakan jenis EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST seperti yang ditunjukkan dalam contoh kode ini:

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST  MyDeviceProcessQueryInterfaceRequest;

Kemudian, terapkan fungsi panggilan balik Anda sebagai berikut:

_Use_decl_annotations_
NTSTATUS
 MyDeviceProcessQueryInterfaceRequest (
    WDFDEVICE  Device,
    LPGUID  InterfaceType,
    PINTERFACE  ExposedInterface,
    PVOID  ExposedInterfaceSpecificData
    )
  {...}

Jenis fungsi EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST didefinisikan dalam file header WdfQueryInterface.h. Untuk mengidentifikasi kesalahan secara lebih akurat saat Anda menjalankan alat analisis kode, pastikan untuk menambahkan anotasi Use_decl_annotations ke definisi fungsi Anda. Anotasi Use_decl_annotations memastikan bahwa anotasi yang diterapkan ke jenis fungsi EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST dalam file header digunakan. Untuk informasi selengkapnya tentang persyaratan untuk deklarasi fungsi, lihat Mendeklarasikan Fungsi dengan Menggunakan Jenis Peran Fungsi untuk Driver KMDF. Untuk informasi tentang Use_decl_annotations, lihat Perilaku Fungsi Anotasi.