WDF_QUERY_INTERFACE_CONFIG 结构 (wdfqueryinterface.h)

项目
03/05/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

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

InterfaceType

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

注意

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

SendQueryToParentStack

如果 为 TRUE，并且驱动程序在调用 WdfDeviceAddQueryInterface 时指定表示 PDO) (物理设备对象的设备对象，框架会将接口的请求发送到父设备的驱动程序堆栈顶部。如果此成员为 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、大小和版本值是否与你提供的 GUID、大小和版本值匹配，如果值不匹配，框架将拒绝请求。如果值有效，框架将使用你为接口提供的值初始化请求驱动程序提供的接口结构。

此外，如果 SendQueryToParentStack 成员的值为 TRUE，则 Interface 成员可以为 NULL。

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

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

框架提供了两个 reference/dereference 方法，可以通过指定接口结构的 InterfaceReference 和 InterfaceDereference 成员的地址来与接口一起使用。有关这些方法的详细信息，请参阅 WdfDeviceInterfaceReferenceNoOp 和 WdfDeviceInterfaceDereferenceNoOp。

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

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