EVT_SERCX2_SELECT_NEXT_RECEIVE_TRANSACTION_TYPE回调函数 (sercx.h)
串行框架扩展的版本 2 (SerCx2) 调用 EvtSerCx2SelectNextReceiveTransactionType 事件回调函数,以确定用于下一个读取操作的数据传输机制。
语法
EVT_SERCX2_SELECT_NEXT_RECEIVE_TRANSACTION_TYPE EvtSercx2SelectNextReceiveTransactionType;
SERCX2_TRANSACTION_TYPE EvtSercx2SelectNextReceiveTransactionType(
[in] WDFDEVICE Device,
[in] PMDL Mdl,
[in] ULONG Offset,
[in] ULONG RemainingLength,
[out] SERCX2CUSTOMRECEIVE *CustomReceive,
[out] PULONG NextTransactionLength
)
{...}
参数
[in] Device
表示串行控制器的框架设备对象的 WDFDEVICE 句柄。 串行控制器驱动程序在其 EvtDriverDeviceAdd 回调函数中创建此对象。 有关详细信息,请参阅 SerCx2InitializeDevice。
[in] Mdl
指向 MDL 的指针,该 MDL 描述下一个接收事务的读取缓冲区跨越的内存页。 DMA 传输的散点/收集列表将使用此内存的区域,该区域由 Offset 和 Length 参数指定。
[in] Offset
下一次数据传输的起始偏移量。 此参数是 MDL 描述的缓冲区区域开头的字节偏移量。 如果 MDL 指定缓冲区空间的总 N 个字节,则 Offset 的可能值介于 0 到 N–1 之间。
[in] RemainingLength
当前 读取 (IRP_MJ_READ) 请求中要传输的数据的总字节数。 如果 MDL 指定缓冲区空间的总 N 个字节,则 Length 的可能值在 1 到 N–Offset 的范围内。
[out] CustomReceive
指向函数将 SERCX2CUSTOMRECEIVE 句柄写入自定义接收对象的位置的指针。 如果函数返回 SerCx2TransactionTypeCustom,则函数必须提供串行控制器驱动程序在上一次调用 SerCx2CustomReceiveCreate 方法中创建的对象句柄。 如果返回值不是 SerCx2TransactionTypeCustom,则 SerCx2 将忽略此输出值。
[out] NextTransactionLength
指向函数写入下一个接收事务中要传输的字节数的位置的指针。 如果返回值为 SerCx2TransactionTypeDefault,则 SerCx2 将忽略此输出值。
返回值
EvtSerCx2SelectNextReceiveTransactionType 函数返回一个SERCX2_TRANSACTION_TYPE枚举常量,以指示是使用驱动程序选择的事务类型 (编程的 I/O (PIO) 、系统 DMA 或自定义数据传输) ,还是让 SerCx2 选择用于下一个接收事务的事务类型。
注解
串行控制器驱动程序可以选择实现此函数。 如果实现,驱动程序会在对 SerCx2InitializeDevice 方法的调用中注册此函数,该方法完成串行控制器的框架设备对象的初始化。
如果串行控制器驱动程序未实现 EvtSerCx2SelectNextReceiveTransactionType 函数,则 SerCx2 始终决定 (PIO、系统 DMA 或自定义) 用于下一个接收事务的数据传输机制的类型。 SerCx2 基于串行控制器驱动程序提供的 I/O 配置信息做出决策。 支持 system-DMA-receive 事务的驱动程序提供包含此信息 的SERCX2_SYSTEM_DMA_RECEIVE_CONFIG 结构。 支持自定义接收事务的驱动程序提供包含此信息 的SERCX2_CUSTOM_RECEIVE_CONFIG 结构。
如果串行控制器驱动程序实现了 EvtSerCx2SelectNextReceiveTransactionType 函数,则 SerCx2 将调用此函数来确定 (PIO、系统 DMA 或自定义) 用于下一个接收事务的数据传输机制的类型。 如果串行控制器具有无法通过 SERCX2_XXX_RECEIVE_CONFIG 结构中的 I/O 配置信息充分描述的特殊硬件功能,则可能需要实现此函数。
示例
若要定义 EvtSerCx2CustomReceiveSelectNextTransactionType 回调函数,必须首先提供一个函数声明来标识要定义的回调函数的类型。 Windows 为驱动程序提供一组回调函数类型。 使用回调函数类型声明函数有助于 驱动程序代码分析、 静态驱动程序验证程序 (SDV) 和其他验证工具查找错误,并且这是编写适用于 Windows 操作系统的驱动程序的要求。
例如,若要定义名为 MyCustomReceiveSelectNextTransactionType
的 EvtSerCx2CustomReceiveSelectNextTransactionType 回调函数,请使用 EVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE 函数类型,如以下代码示例所示:
EVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE MyCustomReceiveTransactionStart;
然后,按如下所示实现回调函数:
_Use_decl_annotations_
SERCX2_TRANSACTION_TYPE
EvtSerCx2SelectNextReceiveTransactionType(
WDFDEVICE Device,
PMDL Mdl,
ULONG Offset,
ULONG RemainingLength,
SERCX2CUSTOMRECEIVE *CustomReceive,
PULONG NextTransactionLength
)
{...}
EVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE函数类型在 Sercx.h 头文件中定义。 若要在运行代码分析工具时更准确地识别错误,请务必将 Use_decl_annotations 注释添加到函数定义。 Use_decl_annotations批注可确保使用应用于头文件中EVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE函数类型的注释。 有关函数声明要求的详细信息,请参阅 使用 KMDF 驱动程序的函数角色类型声明函数。 有关 Use_decl_annotations的详细信息,请参阅 批注函数行为。
要求
要求 | 值 |
---|---|
最低受支持的客户端 | 从Windows 8.1开始可用。 |
目标平台 | 桌面 |
标头 | sercx.h |
IRQL | 在 IRQL <= DISPATCH_LEVEL 调用。 |
另请参阅
反馈
https://aka.ms/ContentUserFeedback。
即将发布:在整个 2024 年,我们将逐步淘汰作为内容反馈机制的“GitHub 问题”,并将其取代为新的反馈系统。 有关详细信息,请参阅:提交和查看相关反馈