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 回调函数必须返回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 结构的 上下文 成员来分配动态实例特定的上下文。
有关驱动程序定义接口的详细信息,请参阅 使用 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的信息,请参阅 批注函数行为。
要求
要求 | 价值 |
---|---|
目标平台 | 普遍 |
最低 KMDF 版本 | 1.0 |
标头 | wdfqueryinterface.h (包括 Wdf.h) |
IRQL | PASSIVE_LEVEL |