EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST回调函数 (wdfqueryinterface.h)

项目
08/08/2023

[仅适用于 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

指向 INTERFACE 结构的指针，该结构描述驱动程序定义的接口，由请求访问接口的驱动程序提供。

[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) ，则驱动程序必须提供 EvtDeviceProcessQueryInterfaceRequest 事件回调函数。回调函数是必需的，因为如果 ImportInterface 为 TRUE ，而另一个驱动程序调用 WdfFdoQueryForInterface，则框架不会将驱动程序定义的接口复制到请求驱动程序的接口结构中。相反，回调函数必须更新请求驱动程序的接口结构。

回调函数可以修改接口。具体而言，它可以：

更改接口的任何成员中的任何值。
通过修改 INTERFACE 结构的 Context 成员来分配特定于实例的动态上下文。

框架仅为驱动程序通过调用 WdfDeviceAddQueryInterface 注册的 GUID 调用驱动程序的 EvtDeviceProcessQueryInterfaceRequest 回调函数。因此，这些回调函数不使用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的信息，请参阅批注函数行为。