WDF_QUERY_INTERFACE_CONFIG 結構 (wdfqueryinterface.h)

發行項
02/27/2024

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

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

InterfaceType

識別介面之 GUID 的指標。

注意

引進新版本的現有介面時，請建立新的 GUID，而不是修改 INTERFACE 結構的 Size 或 Version 字段。如需詳細資訊，請參閱使用 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。如果 ImportInterface 為 TRUE，則要求驅動程式所提供的結構可以包含驅動程式可讀取的數據。在此案例中：

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

如果您想要讓介面只支援從驅動程式到要求驅動程式的單向通訊，請將 ImportInterface 設定為 FALSE。要求驅動程式提供的介面結構只能接收驅動程式所提供的數據。在此案例中：

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

此外，如果 SendQueryToParentStack 成員的值為 TRUE，介面成員可以是 NULL。

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

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

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

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

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