EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST回调函数 (wdfqueryinterface.h)

[仅适用于 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 事件回调函数。

如果驱动程序定义的接口仅支持单向通信,并设置描述 FALSE接口的 WDF_QUERY_INTERFACE_CONFIG 结构的 ImportInterface 成员,则 EvtDeviceProcessQueryInterfaceRequest 回调函数是可选的。 当另一个驱动程序调用 WdfFdoQueryForInterface时,框架会将驱动程序定义的接口值复制到请求的驱动程序的 INTERFACE 结构中,然后调用回调函数。 对于单向通信,仅当希望驱动程序检查并可能修改接口值时,才需要提供回调函数,然后框架将其返回给请求驱动程序。

如果驱动程序定义了支持双向通信的接口(并将 WDF_QUERY_INTERFACE_CONFIG 结构的 ImportInterface 成员设置为 TRUE),驱动程序必须提供 EvtDeviceProcessQueryInterfaceRequest 事件回调函数。 回调函数是必需的,因为如果 ImportInterfaceTRUE,并且另一个驱动程序调用 WdfFdoQueryForInterface,则框架不会将驱动程序定义的接口复制到请求的驱动程序接口结构中。 相反,回调函数必须更新请求驱动程序的接口结构。

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

  • 更改接口的任何成员中的任何值。
  • 通过修改 INTERFACE 结构的 上下文 成员来分配动态实例特定的上下文。
该框架仅针对驱动程序通过调用 WdfDeviceAddQueryInterdQueryInterface注册的 GUID 调用驱动程序的 EvtDeviceProcessQueryInterfaceRequest 回调函数。 因此,这些回调函数不使用STATUS_NOT_SUPPORTED返回值来报告意外的 GUID。 相反,EvtDeviceProcessQueryInterfaceRequest 回调函数应在确定特定情况下不会处理接口时返回STATUS_NOT_SUPPORTED。 例如,根据请求驱动程序提供的数据,驱动程序可能会确定较低级别的驱动程序应为接口请求提供服务。 STATUS_NOT_SUPPORTED返回值通知框架驱动程序不为接口请求提供服务,但较低级别的驱动程序可能会为它提供服务。

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

例子

若要定义 EvtDeviceProcessQueryInterfaceRequest 回调函数,必须首先提供一个函数声明,用于标识要定义的回调函数的类型。 Windows 为驱动程序提供一组回调函数类型。 使用回调函数类型声明函数有助于 驱动程序代码分析静态驱动程序验证程序(SDV)和其他验证工具查找错误,这是为 Windows 操作系统编写驱动程序的要求。

例如,若要定义名为 MyDeviceProcessQueryInterfaceRequestEvtDeviceProcessQueryInterfaceRequest 回调函数,请使用 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的信息,请参阅 批注函数行为

要求

要求 价值
目标平台 普遍
最低 KMDF 版本 1.0
标头 wdfqueryinterface.h (包括 Wdf.h)
IRQL PASSIVE_LEVEL

另请参阅

接口

WDF_QUERY_INTERFACE_CONFIG

WdfDeviceAddQueryInterface

WdfFdoQueryForInterface