[CP_AUTOSAR]_通信服务_CanTp模块（四）

  在前面 《[CP_AUTOSAR]_通信服务_CanTp模块（一）》 和 《[CP_AUTOSAR]_通信服务_CanTp模块（二）》  《[CP_AUTOSAR]_通信服务_CanTp模块（三）》文章中介绍了CanTp 模块的主要功能、与其它模块的交互关系，以及功能规范。本文再接着介绍下CanTp 模块定义的API接口函数。

4、API 规范

4.1、函数定义

4.1.1、CanTp_Init

函数	CanTp_Init
语法	void CanTp_Init(const CanTp_ConfigType* CfgPtr)
服务 ID	0x01
Sync/Async	同步：同步通信指的是发送方在发送请求后会等待接收方的响应，期间发送方通常会被阻塞，无法执行其他任务。
Reentrancy	不可重入（重入：可以由多个任务并发调用，而不影响直接结果）
参数（in）	CfgPtr，指向 CanTp 模块构建后的配置参数
参数（inout）	None
参数（out）	None
返回值	None
描述	初始化 CanTp 模块参数使用
获取	CanTp.h

  上电后，CanTp 模块应该进入 CANTP_OFF 状态，该状态下 CanTp 模块仍未完成配置，也不能支持相关的通信任务。函数 CanTp_Init 初始化 CanTp 模块的所有全局参数，设置其状态为空闲状态（state = CANTP_ON，但接收和发送都不在进行中）。函数 CanTp_Init 是没有返回值，要求在参数配置过程中（如使用配置工具）能够监测配置数据错误。而且，如果硬件模块错误发生，应该可以通过硬件错误管理器模块汇报出当前错误。

功能需求	描述
SWS_CanTp_00199	在进一步使用 CanTp 模块之前，应该调用 CanTp_Init 函数来初始化；
SWS_CanTp_00161	用于显示 BSW 模块是否被初始化的状态变量，应该使用 BSW 的 API函数来初始化为0；

4.1.2、CanTp_ GetVersionInfo

函数	CanTp_GetVersionInfo
语法	void CanTp_GetVersionInfo (Std_VersionInfoType* versioninfo)
服务 ID	0x07
Sync/Async	同步：同步通信指的是发送方在发送请求后会等待接收方的响应，期间发送方通常会被阻塞，无法执行其他任务。
Reentrancy	可重入（重入：可以由多个任务并发调用，而不影响直接结果）
参数（in）	None
参数（inout）	None
参数（out）	versioninfo，存储了该模块的版本信息；
返回值	None
描述	返回 CanTp 模块的版本信息；
获取	CanTp.h

功能需求	描述
SWS_CanTp_00319	如果开发中监测错误的功能开启了，参数是空指针，那么该函数应该能汇报错误 CanTp.CANTP_E_PARAM_POINTER；

4.1.3、CanTp_Shutdown

函数	CanTp_Shutdown
语法	void CanTp_GetVersionInfo (Std_VersionInfoType* versioninfo)
服务 ID	0x02
Sync/Async	同步：同步通信指的是发送方在发送请求后会等待接收方的响应，期间发送方通常会被阻塞，无法执行其他任务。
Reentrancy	不可重入（重入：可以由多个任务并发调用，而不影响直接结果）
参数（in）	None
参数（inout）	None
参数（out）	None
返回值	None
描述	关闭 CanTp 模块；
获取	CanTp.h

功能需求	描述
SWS_CanTp_00202	CanTp_Shutdown 函数被调用时，应该关闭所有挂起的传输协议连接，释放所有的资源，并且设置 CanTp 模块为 CANTP_OFF 状态；
SWS_CanTp_00200	CanTp_Shutdown 函数不会引发关于挂起帧传输或者发送；

4.1.4、CanTp_Transmit

函数	CanTp_Transmit
语法	Std_ReturnType CanTp_Transmit (PduIdType TxPduId, const PduInfoType* PduInfoPtr)
服务 ID	0x49
Sync/Async	同步：同步通信指的是发送方在发送请求后会等待接收方的响应，期间发送方通常会被阻塞，无法执行其他任务。
Reentrancy	不同的 PduId 可重入，相同的 PduId 不可重入；（重入：可以由多个任务并发调用，而不影响直接结果）
参数（in）	TxPduId，被发送的 PDU 的ID
参数（inout）	PduInfoPtr，指向数组的指针，包括了 PDU 数据长度和元数据的指针；
参数（out）	None
返回值	Std_ReturnType；E_OK：发送的请求被接收；E_NOT_OK：发送的请求未被接收；
描述	请求发送 PDU ；
获取	CanTp.h

功能需求	描述
SWS_CanTp_00231	如果要发送的数据没有填充满 N-PDU ，函数 CanTp_Transmit() 应该发送 SF N-PDU（单帧）；
SWS_CanTp_00232	如果要发送的数据超出了一帧 N-PDU 数量，函数 CanTp_Transmit() 应该发送多帧；
SWS_CanTp_00354	N-PDU 的最大发送长度来源于EcuC的配置参数 PduLength，该参数等于 ISO 15765-2 中的 TX_DL；
SWS_CanTp_00204	当消息传送完成时，CanTp 模块应该调用 PduR_CanTpTxConfirmation 函数来通知上层；
SWS_CanTp_00205	如果错误发生（比如，溢出、N_As 超时、N_Bs 超时等等），CanTp 模块应该停止发送消息，并调用函数 PduR_CanTpTxConfirmation （返回值为 E_NOT_OK）；
SWS_CanTp_00206	在当前 CanTp 传输层中会话中，CanTp_Transmit 正在被某个 N-PDU ID 调用，那么 函数 CanTp_Transmit 需要拒绝该请求；
SWS_CanTp_00298	CanTp 模块缓存空间有限，因此要发送的 N-PDU 数据载荷不是在内部被拷贝的。CanTp 层通过函数 PduR_CanTpCopyTxData 服务从上层直接获取数据。因此，为了保证数据一致性，上层（比如DCM，PduR 或者是 AUTOSAR COM）必须锁住内存区域，直到确认通知产生。
SWS_CanTp_00299	当上层调用函数 CanTp_Transmit 来发送一个没有元数据的 N-PDU，结构体 PduInfoPtr 只表示了数据长度信息；对于带有元数据的 N-PDU，除了数据的长度信息和指向元数据的指针，CanTp 模块需要调用 PduR_CanTpCopyTxData 函数去获取真实的发送数据；
SWS_CanTp_00321	如果开发中监测错误的功能开启了，PduInfoPtr 是空指针，函数 CanTp_Transmit 应该汇报错误 CanTp.CANTP_E_PARAM_POINTER；
SWS_CanTp_00356	如果开发中监测错误的功能开启了，函数 CanTp_Transmit 应该检查参数 TxPduId 的有效性。如果值无效，函数 CanTp_Transmit 应该汇报错误 CanTp.CANTP_E_INVALID_TX_ID.；

4.1.5、CanTp_CancelTransmit

函数	CanTp_CancelTransmit
语法	Std_ReturnType CanTp_CancelTransmit (PduIdType TxPduId)
服务 ID	0x4a
Sync/Async	同步：同步通信指的是发送方在发送请求后会等待接收方的响应，期间发送方通常会被阻塞，无法执行其他任务。
Reentrancy	不同的 PduId 可重入，相同的 PduId 不可重入；（重入：可以由多个任务并发调用，而不影响直接结果）
参数（in）	TxPduId，被取消发送的 PDU 的ID
参数（inout）	None
参数（out）	None
返回值	Std_ReturnType；E_OK：目标模块成功执行取消发送请求；E_NOT_OK：目标模块拒绝执行取消发送请求；
描述	在下层通讯模块中，请求取消一个正在发送中的 PDU ；
获取	CanTp.h

   该服务用于取消已经调用函数 CanTp_Transmit 发送 N-PDU 的请求。

功能需求	描述
SWS_CanTp_00254	如果开发中监测错误的功能开启了 ，函数 CanTp_CancelTransmit 应该检查参数 TxPduId 的有效性。如果值无效，函数 CanTp_CancelTransmit 应该汇报错误 CanTp.CANTP_E_INVALID_TX_ID.；如果参数值表示取消发送 N-PDU 的请求，而该 N-PDU 并没有正在发送中，CanTp 模块应该汇报运行时错误 CanTp.CANTP_E_OPER_NOT_SUPPORTED 给 Default Error Tracer 模块，并且函数返回值为 E_NOT_OK ；
SWS_CanTp_00256	CanTp 模块应该停止发送当前 N-PDU，如果函数返回值为 E_OK；
SWS_CanTp_00255	如果函数 CanTp_CancelTransmit 成功执行，那么 CanTp 模块应该调用 PduR_CanTpTxConfirmation 函数，其返回值为 E_NOT_OK；

4.1.6、CanTp_CancelReceive

函数	CanTp_CancelReceive
语法	Std_ReturnType CanTp_CancelReceive(PduIdType RxPduId)
服务 ID	0x4c
Sync/Async	同步：同步通信指的是发送方在发送请求后会等待接收方的响应，期间发送方通常会被阻塞，无法执行其他任务。
Reentrancy	不可重入（重入：可以由多个任务并发调用，而不影响直接结果）；
参数（in）	RxPduId，被取消接收的 PDU 的ID
参数（inout）	None
参数（out）	None
返回值	Std_ReturnType；E_OK：目标模块成功执行取消发送请求；E_NOT_OK：目标模块拒绝执行取消发送请求；
描述	在下层通讯模块中，请求取消一个正在接收中的 PDU ；
获取	CanTp.h

   该服务用于取消已经调用 N-PDU 的接收，其开始于首帧的接收和函数 PduR_StartOfReception 的连续调用。当函数返回值，应再也没有一个给定的 N-PDU ID在接收中。

功能需求	描述
SWS_CanTp_00260	如果开发中监测错误的功能开启了 ，函数 CanTp_CancelReceive 应该检查参数 RxPduId 的有效性。如果值无效，函数 CanTp_CancelReceive 应该汇报错误 CanTp.CANTP_E_INVALID_RX_ID.；如果参数值表示取消接收 N-PDU 的请求，而该 N-PDU 并没有正在接收中，CanTp 模块应该汇报运行时错误 CanTp.CANTP_E_OPER_NOT_SUPPORTED 给 Default Error Tracer 模块，并且函数返回值为 E_NOT_OK ；
SWS_CanTp_00261	CanTp 模块应该停止接收当前 N-PDU，如果函数返回值为 E_OK；
SWS_CanTp_00262	如果单帧接收或者CanTp 模块正在接收最后一个连续帧 CF N-PDU（比如，该服务在 N_Cr 超时之后被调用来开始最后一个连续帧），CanTp 模块应该拒绝这个取消发送的请求，这种情况下，CanTp 返回值为 E_NOT_OK ；
SWS_CanTp_00263	如果函数 CanTp_CancelReceive 成功执行，那么 CanTp 模块应该调用 PduR_CanTpRxIndication 函数，其返回值为 E_NOT_OK；

4.1.7、CanTp_ChangeParameter

函数	CanTp_ChangeParameter
语法	Std_ReturnType CanTp_ChangeParameter (PduIdType id, TPParameterType parameter, uint16 value)
服务 ID	0x4b
Sync/Async	同步：同步通信指的是发送方在发送请求后会等待接收方的响应，期间发送方通常会被阻塞，无法执行其他任务。
Reentrancy	不可重入（重入：可以由多个任务并发调用，而不影响直接结果）；
参数（in）	id，参数改变的 PDU ID； parameter，被改变的参数； value，参数的新值；
参数（inout）	None
参数（out）	None
返回值	Std_ReturnType；E_OK：参数被成功改变；E_NOT_OK：参数被拒绝改变；
描述	请求改变一个指定的传输层参数（比如，BS，block size） ；
获取	CanTp.h

   该服务 CanTp_ChangeParameter 用于改变接收参数 BS 和 STmin 的值，其与每个接收的 N-PDU 有关。

功能需求	描述
SWS_CanTp_00303	改变一个参数只可能 N-PDU 不在接收过程中，即在接收首帧 FF 直到最后一帧连续帧被接收，改变一个参数是不可能的；
SWS_CanTp_00304	如果改变一个正在接收的N-PDU 的参数值， CanTp_ChangeParameter 函数应立即返回 E_NOT_OK，并且不会改变任何值；
SWS_CanTp_00338	当调用函数 CanTp_ChangeParameter 改变一个带有元数据的 N-PDU的参数值，那么该改变应该被应用到所有的通过连接上，以便于可以被接下来所有的N-PDU接收所使用；
SWS_CanTp_00305	如果开发中监测错误的功能开启了 ，函数 CanTp_ChangeParameter 应该检查参数（parameter 和 value）的有效性。如果值 parameter 无效，函数应该汇报错误 CanTp.CANTP_E_PARAM_ID；如果值 value 无效，函数应该汇报错误 CanTp.CANTP_E_PARAM_CONFIG；
SWS_CanTp_00357	如果开发中监测错误的功能开启了 ，函数 CanTp_ChangeParameter 应该检查参数（ id ）的有效性。如果值 id 无效，函数应该汇报错误 CanTp.CANTP_E_INVALID_RX_ID；

4.1.8、CanTp_ReadParameter

函数	CanTp_ReadParameter
语法	Std_ReturnType CanTp_ReadParameter (PduIdType id, TPParameterType parameter, uint16 * value)
服务 ID	0x0b
Sync/Async	同步：同步通信指的是发送方在发送请求后会等待接收方的响应，期间发送方通常会被阻塞，无法执行其他任务。
Reentrancy	不可重入（重入：可以由多个任务并发调用，而不影响直接结果）；
参数（in）	id，读取参数的 PDU ID； parameter，指定读取的参数；
参数（inout）	None
参数（out）	value，指向参数的指针
返回值	Std_ReturnType；E_OK：请求被接受了；E_NOT_OK：请求被拒绝；
描述	该服务用于读取 N-PDU 接收参数（BS，STmin）的当前值；
获取	CanTp.h

功能需求	描述
SWS_CanTp_00324	如果开发中监测错误的功能开启了 ，函数 CanTp_ReadParameter 应该检查参数（parameter）的有效性。如果值 parameter 无效，函数应该汇报错误 CanTp.CANTP_E_PARAM_ID；
SWS_CanTp_00358	如果开发中监测错误的功能开启了 ，函数 CanTp_ReadParameter 应该检查参数（id）的有效性。如果值 id 无效，函数应该汇报错误 CanTp.CANTP_E_INVALID_RX_ID；

4.1.9、Main Function

函数	CanTp_MainFunction
语法	void CanTp_MainFunction (void)
服务 ID	0x06
描述	调度 CanTp 的主函数；
获取	CanTp.h

功能需求	描述
SWS_CanTp_00164	调度 CanTp 模块的主函数（调度的入口）； 该主函数被 Schedule Manager（调度管理器）或者 Free Running Timer 模块根据其调用周期来调用，CanTp_MainFunction 与处理 CAN TP 时序参数 N_As, N_Bs, N_Cs, N_Ar, N_Br, N_Cr 和 STMmin 有关；

4.2、回调函数

4.2.1、CanTp_RxIndication

函数	CanTp_RxIndication
语法	void CanTp_RxIndication(PduIdType RxPduId, const PduInfoType* PduInfoPtr)
服务 ID	0x42
Sync/Async	同步：同步通信指的是发送方在发送请求后会等待接收方的响应，期间发送方通常会被阻塞，无法执行其他任务。
Reentrancy	相同的 PduId 不可重入，不同的可以重入（重入：可以由多个任务并发调用，而不影响直接结果）；
参数（in）	1、RxPduId，接收 PDU 的 ID； 2、PduInfoPtr，包含接收 PDU 的长度（SduLength）和指向存有 PDU 元数据的指针（SduDataPtr）
参数（inout）	None
参数（out）	None
返回值	None
描述	表明从下层的通信接口模块中接收到一个 PDU
获取	CanTp.h

   CanIf 模块在成功接收一个 Rx CAN L-PDU后，应该回调该函数。接下来数据会在 CanTp 模块中通过 PDU 结构体 PduInfoType（该结构体中包含了 PDU 长度、指向元数据的指针） 被拷贝，由于Rx CAN L-PDU 数据并不是全局变量，因此该数据需要被分配到相应的 CAN Transport Layer 中。

功能需求	描述
SWS_CanTp_00235	CanTp_RxIndication 函数可以在中断中被回调；
SWS_CanTp_00322	如果开发中监测错误的功能开启了，当 PduInfoPtr 为空指针时，那么 CanTp_RxIndication 函数能够汇报 CanTp.CANTP_E_PARAM_POINTER；
SWS_CanTp_00359	如果开发中监测错误的功能开启了，那么 CanTp_RxIndication 函数能够检查函数参数 RxPduId 的有效性，如果无效，则应该汇报 CanTp.CANTP_E_INVALID_RX_ID；

4.2.2、CanTp_TxConfirmation

函数	CanTp_TxConfirmation
语法	void CanTp_TxConfirmation(PduIdType RxPduId, Std_ReturnType result)
服务 ID	0x40
Sync/Async	同步：同步通信指的是发送方在发送请求后会等待接收方的响应，期间发送方通常会被阻塞，无法执行其他任务。
Reentrancy	相同的 PduId 不可重入，不同的可以重入（重入：可以由多个任务并发调用，而不影响直接结果）；
参数（in）	1、TxPduId，被发送 PDU 的 ID； 2、result，值为 E_OK：表示 PDU 被发送；值为 E_NOT_OK：发送 PDU 失败；
参数（inout）	None
参数（out）	None
返回值	None
描述	下层的通信接口模块确认了被发送的 PDU 的成功或者失败；
获取	CanTp.h

   在 CanTp 模块通过 CAN 网络发送了报文（单帧/首帧/连续帧/流控帧），CanIf 模块应该调用 CanTp_TxConfirmation 函数。

功能需求	描述
SWS_CanTp_00236	CanTp_TxConfirmation 函数可以在中断中被回调；
SWS_CanTp_00360	如果开发中监测错误的功能开启了，那么 CanTp_RxIndication 函数能够检查参数 TxPduId 的有效性。如果值无效，函数能够汇报 CanTp.CANTP_E_INVALID_TX_ID；

   更多内容可参考 CP_AUTOSAR_总目录，点击跳转