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

指向描述驱动程序定义的接口的接口结构的指针。

InterfaceType

指向标识接口的 GUID 的指针。

注释

在引入现有接口的新版本时，请创建新的 GUID，而不是修改大小或版本字段 INTERFACE 结构。有关详细信息，请参阅使用 Driver-Defined 接口。

SendQueryToParentStack

如果 TRUE，并且驱动程序在调用 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 结构中的值。如果其中任一值较小，框架将拒绝请求。如果未为接口提供值，EvtDeviceProcessQueryInterfaceRequest 回调函数必须验证这些值。

如果希望接口仅支持从驱动程序到请求驱动程序的单向通信，ImportInterface 设置为 FALSE。请求驱动程序提供的接口结构只能接收驱动程序提供的数据。在这种情况下：

EvtDeviceProcessQueryInterfaceRequest 回调函数是可选的。
接口成员不能 NULL。框架验证请求驱动程序提供的 GUID、大小和版本值是否与所提供的 GUID、大小和版本值匹配，如果值不匹配，框架将拒绝请求。如果值有效，框架将使用为接口提供的值初始化请求驱动程序提供的接口结构。

此外，如果 SendQueryToParentStack 成员的值 TRUE，接口成员可以 NULL。

如果接口成员为非NULL，则框架会将该值复制到内部存储空间。因此，驱动程序可以在本地临时存储空间中分配 INTERFACE 结构。

当驱动程序调用 WdfDeviceAddQueryInterface时，它可以将接口与表示功能设备对象（FDO）或物理设备对象（PDO）的框架设备对象相关联。如果驱动程序将接口与 PDO 相关联，则可以将 WDF_QUERY_INTERFACE_CONFIG 结构的 SendQueryToParentStack 成员设置为 TRUE。当框架截获接口的请求时，它会检查 SendQueryToParentStack 成员，如果设置为 TRUE，框架会将请求发送到 PDO 父级驱动程序堆栈的顶部。因此，请求会向下传输两个驱动程序堆栈：第一个是包含正在请求接口的驱动程序的堆栈，第二个是接口设备的父级的堆栈。

该框架提供了两种引用/取消引用方法，可以通过指定接口 InterfaceReference 地址和 InterfaceDereferenceINTERFACE 结构的成员来将其地址用于接口。有关这些方法的详细信息，请参阅 WdfDeviceInterfaceReferenceNoOp 和 WdfDeviceInterfaceDereferenceNoOp。

驱动程序应通过调用 WDF_QUERY_INTERFACE_CONFIG_INIT来初始化此结构。

有关驱动程序定义接口的详细信息，请参阅使用 Driver-Defined 接口。