EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST回呼函式 (wdfqueryinterface.h)

發行項
02/29/2024

[僅適用於 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

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

[in, out] ExposedInterfaceSpecificData

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

傳回值

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

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

如果回呼函式發生錯誤，它必須傳回狀態值，NT_SUCCESS (狀態) 等於 FALSE。架構會讓介面的其他驅動程式要求失敗，而且不會將要求向下傳遞至堆疊。

備註

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

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

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

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

變更介面的任何成員中的任何值。
修改 INTERFACE 結構的內容成員，以配置動態實例特定內容。

架構只會針對驅動程式透過呼叫 WdfDeviceAddQueryAddQueryInterface 註冊的 GUID 呼叫驅動程式的 EvtDDeviceProcessQueryInterfaceRequest 回呼函式。因此，這些回呼函式不會使用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的詳細資訊，請參閱標註函式行為。