WDF_QUERY_INTERFACE_CONFIG結構（wdfqueryinterface.h）

發行項
03/22/2025

[僅適用於 KMDF]

WDF_QUERY_INTERFACE_CONFIG 結構描述驅動程式定義的介面。

語法

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;

成員

Size

這個結構的大小，以位元組為單位。

Interface

描述驅動程式定義介面之 INTERFACE 結構的指標。

InterfaceType

識別介面之 GUID 的指標。

備註

在引進新版的現有介面時，請建立新的 GUID，而不是修改 Size 或 Version 欄位 INTERFACE 結構。如需詳細資訊，請參閱使用 Driver-Defined 介面。

SendQueryToParentStack

如果 TRUE，而且如果驅動程式指定裝置物件，代表實體裝置物件（PDO），則呼叫 WdfDeviceAddQueryInterface時，架構會將介面的要求傳送至父裝置驅動程式堆疊的頂端。如果這個成員 FALSE，或者如果裝置物件不代表 PDO，架構就不會將要求傳送至父裝置的堆疊。如需詳細資訊，請參閱下列一節。

EvtDeviceProcessQueryInterfaceRequest

驅動程式 EvtDeviceProcessQueryInterfaceRequest 事件回呼函式的指標，當另一個驅動程式要求介面時，就會呼叫此函式。

ImportInterface

如果 TRUE，介面支援驅動程式與要求介面的驅動程式之間的雙向通訊。

如果這個成員 FALSE，介面支援從驅動程式到要求介面的驅動程式的單向通訊。

備註

WDF_QUERY_INTERFACE_CONFIG 結構會作為 WdfDeviceAddQueryInterface 方法的輸入。

針對驅動程式導出的每個驅動程式定義介面，您必須配置代表介面的WDF_QUERY_INTERFACE_CONFIG結構。其他驅動程式可以呼叫 WdfFdoQueryForInterface來要求存取介面。

如果您要介面支援要求驅動程式與驅動程式之間的雙向通訊，請將 ImportInterface 成員設定為 TRUE。如果 ImportInterfaceTRUE，則要求驅動程式所提供的結構可以包含驅動程式可以讀取的數據。在此案例中：

需要 EvtDeviceProcessQueryInterfaceRequest 回呼函式，而且必須初始化要求驅動程式提供的介面結構。
由於 EvtDeviceProcessQueryInterfaceRequest 回呼函式會提供要求驅動程式的介面，因此 WDF_QUERY_INTERFACE_CONFIG 的介面成員可以 NULL。如果您提供非NULL 指標，架構會驗證要求驅動程式所提供的大小和版本值是否等於或大於已註冊 INTERFACE 結構中的值。如果其中一個值較小，架構就會拒絕要求。如果您未提供 Interface的值，則 EvtDeviceProcessQueryInterfaceRequest callback 函式必須驗證這些值。

如果您要讓介面只支援從驅動程式到要求驅動程式的單向通訊，請設定 importInterfaceFALSE。要求驅動程式提供的介面結構只能接收驅動程式所提供的數據。在此情況下：

EvtDeviceProcessQueryInterfaceRequest 回呼函式是選擇性的。
介面成員不能 NULL。架構會驗證要求驅動程式所提供的 GUID、大小和版本值符合您提供的 GUID、大小和版本值，如果值不相符，架構就會拒絕要求。如果值有效，架構會使用您提供給 Interface 的值，初始化要求驅動程式所提供的介面結構。

此外，如果 sendQueryToParentStack 成員的值 TRUE，Interface 成員可以 NULL。

如果介面成員非NULL，架構會將此值複製到內部儲存空間。因此，驅動程式可以在本機暫存空間中配置 INTERFACE 結構。

當您的驅動程式呼叫 WdfDeviceAddQueryInterface時，它可以將介面與代表功能裝置物件（FDO）或實體裝置物件（PDO）的架構裝置物件產生關聯。如果驅動程式將介面與 PDO 產生關聯，它可以將 SendQueryToParentStackWDF_QUERY_INTERFACE_CONFIG 結構的成員設定為 TRUE。當架構攔截介面的要求時，它會檢查 SendQueryToParentStack 成員，如果它設定為 TRUE，架構會將要求傳送至 PDO 父系驅動程式堆疊的頂端。因此，要求會向下移動兩個驅動程式堆疊：第一，包含要求介面之驅動程式的堆疊，第二個是介面裝置父系的堆疊。

架構提供兩個參考/取值方法，您可以藉由指定介面 InterfaceReference 和 InterfaceDereferenceINTERFACE 結構的成員位址，來搭配介面使用。如需這些方法的詳細資訊，請參閱 WdfDeviceInterfaceReferenceNoOp 和 WdfDeviceInterfaceDereferenceNoOp。

驅動程式應該呼叫 WDF_QUERY_INTERFACE_CONFIG_INIT來初始化這個結構。

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