EVT_SPB_CONTROLLER_OTHER回调函数 (spbcx.h)

项目
08/07/2023

SPB 控制器驱动程序的 EvtSpbControllerIoOther 事件回调函数处理设备 I/O 控制请求，这些请求不由其他事件回调函数或 SPB 框架扩展 (SpbCx) 处理。

语法

EVT_SPB_CONTROLLER_OTHER EvtSpbControllerOther;

void EvtSpbControllerOther(
  [in] WDFDEVICE Controller,
  [in] SPBTARGET Target,
  [in] SPBREQUEST Request,
  [in] size_t OutputBufferLength,
  [in] size_t InputBufferLength,
  [in] ULONG IoControlCode
)
{...}

参数

[in] Controller

表示 SPB 控制器的框架设备对象的 WDFDEVICE 句柄。

[in] Target

此 I/O 请求的目标的 SPBTARGET 句柄。目标是连接到总线的外围设备或端口。 SPB 框架扩展 (SpbCx) 以前将此句柄分配给了打开与目标的连接的 EvtSpbTargetConnect 回调中的目标。

[in] Request

I/O 请求的 SPBREQUEST 句柄。 SPB 控制器驱动程序必须完成此请求。有关详细信息，请参阅“备注”。

[in] OutputBufferLength

如果请求中提供了输出缓冲区，则为输出缓冲区的长度（以字节为单位）。

[in] InputBufferLength

如果输入缓冲区随请求一起提供，则输入缓冲区的长度（以字节为单位）。

[in] IoControlCode

I/O 控制代码 (请求的 IOCTL) 。此值是 SPB 框架扩展 (SpbCx) 无法识别的 IOCTL。有关详细信息，请参阅“备注”。

返回值

无

备注

SpbCx 管理 SPB 控制器的 I/O 队列。如果 SPB 控制器驱动程序注册 EvtSpbControllerIoOther 回调函数，则当 SpbCx 不支持的设备 I/O 控制请求到达控制器的 I/O 队列时，SpbCx 将调用此函数。 Request 参数值是封装此请求的句柄。 SPB 控制器驱动程序必须通过执行请求的操作或返回错误状态来完成此请求。如果驱动程序不支持指定的 IOCTL，则驱动程序应返回STATUS_NOT_SUPPORTED错误状态。有关 SpbCx 支持的 IOCTL 列表，请参阅 SpbCx I/O 控制代码。

EvtSpbControllerIoOther 回调允许将特定于总线或特定于驱动程序的命令作为 IOCTL 调度到 SPB 控制器驱动程序。例如，客户端 (外围驱动程序) 可能会使用这些 IOCTL 来协调特定于总线的操作，例如与 SPI 总线上的目标设备进行全双工数据交换。此类 IOCTL 受 SpbCx 支持的 IOCTL 相同的流控制。

EvtSpbControllerIoOther 回调函数类似于 EvtIoDeviceControl，并且以类似的方式处理 IOCTL。有关 WDF 驱动程序如何处理 I/O 请求的一般信息，请参阅框架请求对象。

EvtSpbControllerIoOther 回调不返回状态值。相反，SPB 控制器驱动程序指示 I/O 请求的完成状态中请求的操作的状态。

如果 I/O 请求无法立即完成，则回调函数应返回，而无需等待 SPB 控制器驱动程序完成请求的处理。 SPB 控制器驱动程序稍后可以异步完成请求。

EvtSpbControllerIoOther 函数必须验证它从用户模式客户端接收的 I/O 控件请求中的参数值。对于除 EvtSpbControllerIoOther 以外的所有 EvtSpb Xxx 回调函数，SpbCx 会在调用函数之前验证用户模式参数。

若要注册 EvtSpbControllerIoOther 回调函数，请调用 SpbControllerSetIoOther 方法。

示例

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

例如，若要定义名为 MyEvtSpbControllerIoOther的 EvtSpbControllerIoOther 回调函数，请使用 EVT_SPB_CONTROLLER_OTHER 函数类型，如以下代码示例所示：

EVT_SPB_CONTROLLER_OTHER  MyEvtSpbControllerIoOther;

然后，按如下所示实现回调函数：

_Use_decl_annotations_
VOID
  MyEvtSpbControllerIoOther(
    WDFDEVICE Controller,
    SPBTARGET Target,
    SPBREQUEST Request,
    size_t OutputBufferLength,
    size_t InputBufferLength,
    ULONG IoControlCode
    )
{ ... }

EVT_SPB_CONTROLLER_OTHER函数类型在 Spbcx.h 头文件中定义。若要在运行代码分析工具时更准确地识别错误，请务必将 Use_decl_annotations 注释添加到函数定义。 Use_decl_annotations批注可确保使用应用于头文件中EVT_SPB_CONTROLLER_OTHER函数类型的注释。有关函数声明要求的详细信息，请参阅使用 KMDF 驱动程序的函数角色类型声明函数。有关 Use_decl_annotations的详细信息，请参阅批注函数行为。