共用方式為

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST回呼函式 （wdfqueryinterface.h）

  • 發行項

[僅適用於 KMDF]

驅動程式的 EvtDeviceProcessQueryInterfaceRequest 事件回呼函式會檢查另一個驅動程式對驅動程式定義介面的存取要求，然後架構會將介面傳遞至要求驅動程式。

語法

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST EvtWdfDeviceProcessQueryInterfaceRequest;

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

參數

[in] Device

架構裝置物件的句柄。

[in] InterfaceType

識別驅動程式定義介面之 GUID 的指標。

[in, out] ExposedInterface

INTERFACE 結構的指標，描述驅動程式定義的介面，並由要求存取介面的驅動程式提供。

[in, out] ExposedInterfaceSpecificData

其他、選擇性、驅動程式定義的介面特定資訊的指標。 架構型驅動程式藉由在 呼叫 WdfFdoQueryForInterface時，提供非NULLInterfaceSpecificData 參數值來指定此值。

傳回值

如果 EvtDeviceProcessQueryInterfaceRequest 回呼函式收到它支援的 GUID，而且如果函式沒有發生任何錯誤，它必須傳回STATUS_SUCCESS或其他狀態值，NT_SUCCESS狀態） 等於 TRUE。 架構會繼續將要求傳遞至堆疊，以查看其他驅動程式是否也支援 介面。

EvtDeviceProcessQueryInterfaceRequest 回呼函式必須傳回STATUS_NOT_SUPPORTED，如果判斷該函式在特定情況下，它不會為介面提供服務。 架構會繼續將要求傳遞至堆疊，以查看另一個驅動程式是否支援 介面。 如需這種情況的詳細資訊，請參閱下列一節。

如果回呼函式發生錯誤，它必須傳回狀態值，NT_SUCCESS（狀態） 等於 FALSE。 架構會失敗另一個驅動程式對 介面的要求，而且不會將要求傳遞至堆疊。

言論

架構型驅動程式會呼叫 WdfDeviceAddQueryInterface來註冊 EvtDeviceProcessQueryInterfaceRequest 事件回呼函式。

如果驅動程式定義介面僅支援單向通訊，並設定 ImportInterface 成員，該 WDF_QUERY_INTERFACE_CONFIG 結構的成員描述要 FALSE的介面，則 EvtDeviceProcessQueryInterfaceRequest 回呼函式是選擇性的。 當另一個驅動程式呼叫 WdfFdoQueryForInterface時，架構會將驅動程式定義的介面值複製到要求的驅動程式 INTERFACE 結構，然後呼叫回呼函式。 若要進行單向通訊，只有在您想要驅動程式檢查並可能修改介面值之前，才需要提供回呼函式，架構才會將它們傳回要求驅動程式。

如果驅動程式定義支援雙向通訊的介面，則驅動程序必須提供 EvtDeviceProcessQueryInterfaceRequest 事件回呼函式（並將 WDF_QUERY_INTERFACE_CONFIG 結構的 ImportInterface 成員設定為 TRUE）。 需要回呼函式，因為如果 ImportInterfaceTRUE，而另一個驅動程式呼叫 WdfFdoQueryForInterface，架構就不會將驅動程式定義的介面複製到要求的驅動程式介面結構中。 相反地，回呼函式必須更新要求的驅動程式介面結構。

回呼函式可以修改 介面。 特別是，它可以：

  • 變更介面任何成員中的任何值。
  • 修改 INTERFACE 結構 成員，以配置動態實例特定內容。
架構只會針對驅動程式註冊的 GUID 呼叫驅動程式的 EvtDDeviceProcessQueryInterfaceRequest 回呼函式，方法是呼叫 WdfDeviceAddQueryInterface。 因此，這些回呼函式不會使用STATUS_NOT_SUPPORTED傳回值來報告非預期的 GUID。 相反地，EvtDeviceProcessQueryInterfaceRequest 回呼函式應該會在判斷特定情況時傳回STATUS_NOT_SUPPORTED，而不會處理介面。 例如，根據要求驅動程式提供的數據，您的驅動程式可能會判斷較低層級的驅動程式應該為介面要求提供服務。 STATUS_NOT_SUPPORTED傳回值會通知架構您的驅動程式未服務介面要求，但較低層級的驅動程式可能會為它提供服務。

如需驅動程式定義介面的詳細資訊，請參閱使用 Driver-Defined 介面。

例子

若要定義 EvtDeviceProcessQueryInterfaceRequest 回呼函式，您必須先提供函式宣告，以識別您要定義的回呼函式類型。 Windows 提供一組驅動程式的回呼函式類型。 使用回呼函式類型宣告函式有助於 驅動程式的程式代碼分析、靜態驅動程式驗證器 （SDV）和其他驗證工具尋找錯誤，而且是撰寫 Windows 操作系統驅動程式的需求。

例如，若要定義名為 MyDeviceProcessQueryInterfaceRequest 回呼函式 EvtDeviceProcessQueryInterfaceRequest ，請使用 EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST 類型，如下列程式代碼範例所示：

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST  MyDeviceProcessQueryInterfaceRequest;

然後，實作回呼函式，如下所示：

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

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST 函式類型定義於 WdfQueryInterface.h 頭檔中。 若要在執行程式代碼分析工具時更準確地識別錯誤，請務必將 Use_decl_annotations 批註新增至函式定義。 Use_decl_annotations 批注可確保會使用套用至頭檔中 EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST 函式類型的批注。 如需函式宣告需求的詳細資訊，請參閱 使用 KMDF 驅動程式的函式角色類型來宣告函式。 如需 Use_decl_annotations的相關信息，請參閱 批注函式行為。

要求

要求 價值
目標平臺 普遍
最低 KMDF 版本 1.0
標頭 wdfqueryinterface.h （包括 Wdf.h）
IRQL PASSIVE_LEVEL

另請參閱

INTERFACE

WDF_QUERY_INTERFACE_CONFIG

WdfDeviceAddQueryInterface

WdfFdoQueryForInterface