EVT_SERCX2_CONTROL回调函数 (sercx.h)

EvtSerCx2Control 事件回调函数由串行框架扩展版本 2 (SerCx2) 调用，以处理串行 I/O 控制请求。

语法

EVT_SERCX2_CONTROL EvtSercx2Control;

NTSTATUS EvtSercx2Control(
  [in] WDFDEVICE Device,
  [in] WDFREQUEST Request,
  [in] size_t OutputBufferLength,
  [in] size_t InputBufferLength,
  [in] ULONG IoControlCode
)
{...}

参数

[in] Device

表示串行控制器的框架设备对象的 WDFDEVICE 句柄。 串行控制器驱动程序在其 EvtDriverDeviceAdd 回调函数中创建此对象。 有关详细信息，请参阅 SerCx2InitializeDevice。

[in] Request

表示串行 I/O 控制请求的框架请求对象的 WDFREQUEST 句柄。

[in] OutputBufferLength

Request 参数指定的串行 I/O 控制请求的输出缓冲区的长度（以字节为单位）。

[in] InputBufferLength

由 Request 参数指定的串行 I/O 控制请求的输入缓冲区的长度（以字节为单位）。

[in] IoControlCode

从 Request 参数指定的串行 I/O 控制请求指定 IOCTL) 指定 I/O 控制 (代码。 串行 I/O 控制请求的 IOCTL 在 Ntddser.h 头文件中定义。 有关详细信息，请参阅“备注”。

返回值

如果调用成功， EvtSerCx2Control 函数将返回STATUS_SUCCESS。 否则，它将返回相应的错误状态代码。

注解

串行控制器驱动程序必须实现此函数。 驱动程序在对 SerCx2InitializeDevice 方法的调用中注册函数，该方法完成串行控制器的框架设备对象的初始化。

EvtSerCx2Control 函数允许驱动程序处理 SerCx2 无法处理的某些串行 I/O 控制请求。 SerCx2 处理 Ntddser.h 头文件中定义的串行 IOCTL 子集的所有处理。 但是，SerCx2 依赖于驱动程序来处理串行 I/O 控制请求以执行依赖于硬件的操作。

当 SerCx2 收到只能由串行控制器驱动程序处理的串行 I/O 控制请求时，SerCx2 调用 EvtSerCx2Control 函数将 I/O 控制请求移交给驱动程序。 驱动程序负责完成此请求。 未实现对特定 I/O 控制请求的支持的驱动程序应使用STATUS_NOT_SUPPORTED错误状态代码完成此 I/O 控制请求。

为了完成 I/O 控制请求，驱动程序通常调用 WdfRequestComplete 方法，并提供 Request 参数值和状态值作为输入参数，以指示请求是否成功。 此状态值将写入请求的状态块。

EvtSerCx2Control 函数的返回值应始终与此函数写入 I/O 控制请求的状态块的状态值匹配。 SerCx2 的当前实现忽略此返回值。

SerCx2 调用 EvtSerCx2Control 函数来处理下表中显示的 IOCTL。 表右侧的列指示是否需要 EvtSerCx2Control 函数来实现对特定 IOCTL 的支持。

I/O 控制请求名称	必需还是可选
IOCTL_SERIAL_CLR_DTR	可选
IOCTL_SERIAL_CLR_RTS	必需
IOCTL_SERIAL_GET_BAUD_RATE	必需
IOCTL_SERIAL_GET_COMMSTATUS	必需
IOCTL_SERIAL_GET_DTRRTS	必需
IOCTL_SERIAL_GET_HANDFLOW	必需
IOCTL_SERIAL_GET_LINE_CONTROL	必需
IOCTL_SERIAL_GET_MODEM_CONTROL	必需
IOCTL_SERIAL_GET_MODEMSTATUS	必需
IOCTL_SERIAL_GET_PROPERTIES	必需
IOCTL_SERIAL_SET_BAUD_RATE	必需
IOCTL_SERIAL_SET_BREAK_OFF	必需
IOCTL_SERIAL_SET_BREAK_ON	必需
IOCTL_SERIAL_SET_DTR	可选
IOCTL_SERIAL_SET_FIFO_CONTROL	可选
IOCTL_SERIAL_SET_HANDFLOW	必需
IOCTL_SERIAL_SET_LINE_CONTROL	必需
IOCTL_SERIAL_SET_MODEM_CONTROL	必需
IOCTL_SERIAL_SET_RTS	必需

 

上表列出了 SerCx2 呈现给 EvtSerCx2Control 函数的所有串行 IOCTL。 对于不在此列表中的任何 IOCTL，SerCx2 要么处理 IOCTL，要么立即使 IOCTL 失败，并将请求状态设置为STATUS_NOT_SUPPORTED。 SerCx2 处理 IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION 请求，但在处理此类请求期间调用 EvtSerCx2ApplyConfig 事件回调函数。 SerCx2 处理 IOCTL_SERIAL_PURGE 请求，但在处理此类请求期间，可能会调用 EvtSerCx2PurgeFifos 事件回调函数。 SerCx 对 IOCTL_SERIAL_SET_WAIT_MASK 请求执行初步处理，但调用 EvtSerCx2SetWaitMask 事件回调函数（如果已实现），以完成此类请求的处理。 有关 SerCx2 对串行 IOCTL 的支持的详细信息，请参阅 串行 I/O 请求接口。

IOCTL_SERIAL_CLR_DTR和IOCTL_SERIAL_SET_DTR

如果串行控制器驱动程序中的 EvtSerCx2Control 函数支持 IOCTL_SERIAL_SET_DTR 请求，则此函数还应支持 IOCTL_SERIAL_CLR_DTR 请求，反之亦然。 如果驱动程序不支持这两个请求， 则IOCTL_SERIAL_GET_DTRRTS 请求的驱动程序处理程序应将此请求的输出值中的SERIAL_DTR_STATE标志位设置为零。

IOCTL_SERIAL_GET_DTRRTS

串行控制器驱动程序中的 EvtSerCx2Control 函数必须支持 IOCTL_SERIAL_GET_DTRRTS 请求，但此请求的驱动程序处理程序需要仅支持此请求的输出值中的SERIAL_RTS_STATE标志位。 作为一个选项，驱动程序还可以支持 SERIAL_DTR_STATE 标志位。 如果不支持SERIAL_DTR_STATE标志位，请将此位设置为零。

IOCTL_SERIAL_GET_COMMSTATUS

串行控制器驱动程序中的 EvtSerCx2Control 函数必须支持 IOCTL_SERIAL_GET_COMMSTATUS 请求，但此请求的驱动程序处理程序需要仅支持此请求使用的 SERIAL_STATUS 结构的以下成员：

• 错误
• HoldReasons

作为一个选项，驱动程序可以另外支持此结构的任何其他成员。 将所有不受支持的成员设置为零。

IOCTL_SERIAL_GET_PROPERTIES

串行控制器驱动程序中的 EvtSerCx2Control 函数必须支持 IOCTL_SERIAL_GET_PROPERTIES 请求。 此请求的驱动程序处理程序应将此请求使用的SERIAL_COMMPROP结构的 MaxBaud 成员设置为支持的最大波特率（以每秒位 (bps) 表示）。 例如，如果串行控制器支持的最大波特率为 115,200 bps，则驱动程序会将 MaxBaud 设置为 115200。

IOCTL_SERIAL_GET_MODEMSTATUS

串行控制器驱动程序中的 EvtSerCx2Control 函数必须支持 IOCTL_SERIAL_GET_MODEMSTATUS 请求。 此请求的驱动程序处理程序应将请求的输出值设置为从串行控制器硬件读取的原始调制解调器状态寄存器值。

IOCTL_SERIAL_GET_HANDFLOW和IOCTL_SERIAL_SET_HANDFLOW

串行控制器驱动程序中的 EvtSerCx2Control 函数必须支持 IOCTL_SERIAL_GET_HANDFLOW 和 IOCTL_SERIAL_SET_HANDFLOW 请求，但需要仅支持为这些请求定义的标志位的子集。 标志位是为这些请求使用的 SERIAL_HANDFLOW 结构的 ControlHandShake 和 FlowReplace 成员定义的。

驱动程序必须支持 ControlHandshake 成员中的以下标志位：

• SERIAL_CTS_HANDSHAKE

作为一个选项，驱动程序可以支持为 ControlHandshake 成员定义的任何其他标志位。

驱动程序必须支持 FlowReplace 成员中的以下标志位：

• SERIAL_RTS_CONTROL
• SERIAL_RTS_HANDSHAKE

作为一个选项，驱动程序可以支持为 FlowReplace 成员定义的任何其他标志位。 但是，很少需要这些其他标志位（如果有的话），Microsoft 建议不支持它们。

不支持 ControlHandShake 或 FlowReplace 成员中的特定标志位的驱动程序应在 IOCTL_SERIAL_GET_HANDFLOW 请求的输出值中将此标志位设置为零。 如果 IOCTL_SERIAL_SET_HANDFLOW 请求指定驱动程序不支持的 ControlHandshake 或 FlowReplace 标志位， 则 EvtSerCx2Control 函数应使请求失败并返回STATUS_INVALID_PARAMETER。

作为一个选项，驱动程序可以支持SERIAL_HANDFLOW结构的 XonLimit 和 XoffLimit 成员。 但是，这些成员很少（如果有的话）是需要的，Microsoft 建议不支持他们。 不支持 XonLimit 和 XoffLimit 成员的驱动程序应在 IOCTL_SERIAL_GET_HANDFLOW 请求的输出值中将这些成员设置为零。 如果 IOCTL_SERIAL_SET_HANDFLOW 请求指定非零 XonLimit 或 XoffLimit 成员，并且驱动程序不支持这些成员， 则 EvtSerCx2Control 函数应使请求失败并返回STATUS_NOT_IMPLEMENTED。

示例

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

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

EVT_SERCX2_CONTROL  MyControl;

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

_Use_decl_annotations_
NTSTATUS
  MyControl(
    WDFDEVICE  Device,
    WDFREQUEST  Request,
    size_t  OutputBufferLength,
    size_t  InputBufferLength,
    ULONG  IoControlCode
    )
  {...}

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

要求

要求	值
最低受支持的客户端	从Windows 8.1开始可用。
目标平台	桌面
标头	sercx.h
IRQL	在 IRQL <= DISPATCH_LEVEL 调用。

另请参阅

EvtDriverDeviceAdd

EvtSerCx2ApplyConfig

EvtSerCx2PurgeFifos

EvtSerCx2SetWaitMask

SERIAL_COMMPROP

SERIAL_EV_XXX

SERIAL_HANDFLOW

SERIAL_STATUS

SerCx2InitializeDevice