TCP 抽象

此模块包含基于基础 TCP API 的易用抽象。

摘要

枚举

anonymous enum 枚举
定义传递给 otTcpCircularSendBufferWrite 的标志。

类型定义符

otTcpCircularSendBuffer typedef
表示用于 TCP 端点的环形发送缓冲区。
otTcpEndpointAndCircularSendBuffer typedef
要与 mbedtls_ssl_set_bio 搭配使用的上下文结构。

函数

otTcpCircularSendBufferDeinitialize(otTcpCircularSendBuffer *aSendBuffer)
取消初始化 TCP 环形发送缓冲区,使其在连接后分离。
otTcpCircularSendBufferForceDiscardAll(otTcpCircularSendBuffer *aSendBuffer)
void
强制舍弃循环发送缓冲区中的所有数据。
otTcpCircularSendBufferGetFreeSpace(const otTcpCircularSendBuffer *aSendBuffer)
size_t
返回 TCP 循环发送缓冲区中的可用空间量。
otTcpCircularSendBufferHandleForwardProgress(otTcpCircularSendBuffer *aSendBuffer, size_t aInSendBuffer)
void
在 otTcpForwardProgress 回调中执行特定于环形发送缓冲区的处理。
otTcpCircularSendBufferInitialize(otTcpCircularSendBuffer *aSendBuffer, void *aDataBuffer, size_t aCapacity)
void
初始化 TCP 环形发送缓冲区。
otTcpCircularSendBufferWrite(otTcpEndpoint *aEndpoint, otTcpCircularSendBuffer *aSendBuffer, const void *aData, size_t aLength, size_t *aWritten, uint32_t aFlags)
在 TCP 端点上发送数据,并使用提供的 TCP 循环发送缓冲区来管理缓冲。
otTcpMbedTlsSslRecvCallback(void *aCtx, unsigned char *aBuf, size_t aLen)
int
传递给 mbedtls_ssl_set_bio 的非阻塞接收回调。
otTcpMbedTlsSslSendCallback(void *aCtx, const unsigned char *aBuf, size_t aLen)
int
传递给 mbedtls_ssl_set_bio 的非阻塞发送回调。

结构体

otTcpCircularSendBuffer

表示用于 TCP 端点的环形发送缓冲区。

otTcpEndpointAndCircularSendBuffer

要与 mbedtls_ssl_set_bio 搭配使用的上下文结构。

枚举

匿名枚举

 anonymous enum

定义传递给 otTcpCircularSendBufferWrite 的标志。

类型定义符

otTcpCircularSendBuffer

struct otTcpCircularSendBuffer otTcpCircularSendBuffer

表示用于 TCP 端点的环形发送缓冲区。

使用循环发送缓冲区是可选的。应用可以通过直接管理 otLinkedBuffers 来使用 TCP 端点发送数据。不过,有些应用可能会发现使用循环发送缓冲区更方便;此类应用可以调用 otTcpCircularSendBufferWrite() 以将循环发送缓冲区“附加”到 TCP 端点,并在该 TCP 端点上发送数据,从而依靠循环发送缓冲区来管理底层 otLinkedBuffers。

otTcpCircularSendBuffer 是在 otTcpEndpoint 提供的基于 otLinkedBuffer 的 API 之上实现的。附加到 otTcpEndpoint 后,otTcpCircularSendBuffer 会执行管理连接的 otLinkedBuffers 的所有工作。这意味着,将 otTcpCircularSendBuffer 附加到 otTcpEndpoint 后,应用不应对该 otTcpEndpoint 调用 otTcpSendByReference()otTcpSendByExtension()。相反,应用应使用 otTcpCircularSendBufferWrite() 将数据添加到发送缓冲区。

otTcpForwardProgress() 回调旨在让用户了解环形发送缓冲区中何时有可用空间。在附加了 otTcpCircularSendBufferotTcpEndpoint 上,应用必须在回调函数开始时安装 otTcpForwardProgress() 回调,并在附加的 otTcpCircularSendBuffer建议用户不要安装 otTcpSendDone() 回调,因为所有 otLinkedBuffers 管理工作都是由循环发送缓冲区处理的。

应用不应直接检查此结构的字段,而应仅通过 TCP Circular Send Buffer API 函数(在此文件中提供了其签名)与其交互。

otTcpEndpointAndCircularSendBuffer

struct otTcpEndpointAndCircularSendBuffer otTcpEndpointAndCircularSendBuffer

要与 mbedtls_ssl_set_bio 搭配使用的上下文结构。

函数

otTcpCircularSendBufferDeinitialize

otError otTcpCircularSendBufferDeinitialize(
  otTcpCircularSendBuffer *aSendBuffer
)

取消初始化 TCP 环形发送缓冲区,使其在连接后分离。

如果 TCP 循环发送缓冲区不为空,则此操作将失败。

具体说明
参数
[in] aSendBuffer
要取消初始化的 TCP 环形发送缓冲区。
返回值
OT_ERROR_NONE
成功取消初始化 TCP 循环发送缓冲区。
OT_ERROR_BUSY
循环缓冲区包含数据,无法取消初始化。

otTcpCircularSendBufferForceDiscardAll

void otTcpCircularSendBufferForceDiscardAll(
  otTcpCircularSendBuffer *aSendBuffer
)

强制舍弃循环发送缓冲区中的所有数据。

应用应在 TCP 连接意外终止时调用此函数(例如,如果应用调用 otTcpEndpointAbort() 或通过 otTcpConnectionLost() 回调获知重置连接)。

在连接到 TCP 端点的非空 TCP 循环发送缓冲区上调用此函数会导致未定义的行为。

具体说明
参数
[in] aSendBuffer
要舍弃其数据的 TCP 循环发送缓冲区。

otTcpCircularSendBufferGetFreeSpace

size_t otTcpCircularSendBufferGetFreeSpace(
  const otTcpCircularSendBuffer *aSendBuffer
)

返回 TCP 循环发送缓冲区中的可用空间量。

此操作一定会成功。

具体说明
参数
[in] aSendBuffer
指向 TCP 循环发送缓冲区(要返回其可用空间量)的指针。
返回值
发送缓冲区中的可用空间。

otTcpCircularSendBufferHandleForwardProgress

void otTcpCircularSendBufferHandleForwardProgress(
  otTcpCircularSendBuffer *aSendBuffer,
  size_t aInSendBuffer
)

在 otTcpForwardProgress 回调中执行特定于环形发送缓冲区的处理。

应用应在 otTcpEndpoint 上安装 otTcpForwardProgress() 回调,而且在回调函数的开头调用此函数,以便进行特定于循环发送缓冲区的处理。

在回调函数中,应用可以通过以下方式确定循环发送缓冲区中的可用空间量:调用 otTcpCircularSendBufferFreeSpace(),或将 aInSendBuffer 与用户调用 otTcpCircularSendBufferInitialize() 时选择的发送缓冲区容量进行比较。

具体说明
参数
[in] aSendBuffer
指向调用 otTcpForwardProgress() 的端点的 TCP 循环发送缓冲区的指针。
[in] aInSendBuffer
传递给 otTcpForwardProgress() 回调的 aInSendBuffer 值。

otTcpCircularSendBufferInitialize

void otTcpCircularSendBufferInitialize(
  otTcpCircularSendBuffer *aSendBuffer,
  void *aDataBuffer,
  size_t aCapacity
)

初始化 TCP 环形发送缓冲区。

具体说明
参数
[in] aSendBuffer
指向要初始化的 TCP 环形发送缓冲区的指针。
[in] aDataBuffer
指向内存的指针,用于将数据存储在 TCP 循环发送缓冲区中。
[in] aCapacity
TCP 循环发送缓冲区的容量(以字节为单位),必须等于 aDataBuffer 所指向的内存的大小。

otTcpCircularSendBufferWrite

otError otTcpCircularSendBufferWrite(
  otTcpEndpoint *aEndpoint,
  otTcpCircularSendBuffer *aSendBuffer,
  const void *aData,
  size_t aLength,
  size_t *aWritten,
  uint32_t aFlags
)

在 TCP 端点上发送数据,并使用提供的 TCP 循环发送缓冲区来管理缓冲。

调用此函数后,aSendBufferaEndpoint 将被视为彼此“关联”。附加后,对 aEndpoint 的所有发送操作都必须使用 aSendBuffer 进行,对 aSendBuffer 的所有操作都必须与 aEndpoint 相关联。

“分离”TCP 循环发送缓冲区和 TCP 端点的唯一方法是等待发送缓冲区变得完全空。具体可能有两种:(1) 在 TCP 协议操作的正常过程中发送和确认发送缓冲区中的所有数据,或 (2) 连接终止。

建议的使用模式是将单个 TCP 循环发送缓冲区与 TCP 端点一起使用,并且仅通过其关联的 TCP 循环缓冲区在该 TCP 端点上发送数据。这种建议的使用模式始终同时使用 TCP 端点和 TCP 循环发送缓冲区,可以避免上述问题。

如果循环发送缓冲区达到容量上限,则仅将所提供数据的前缀复制到循环发送缓冲区。

具体说明
参数
[in] aEndpoint
要在其中发送数据的 TCP 端点。
[in] aSendBuffer
用于复制数据的 TCP 循环发送缓冲区。
[in] aData
指向要复制到 TCP 循环发送缓冲区的数据的指针。
[in] aLength
aData 所指向要复制到 TCP 循环发送缓冲区的数据的长度。
[out] aWritten
使用复制到发送缓冲区的数据量进行填充,如果发送缓冲区达到容量上限,该数据量可能会小于 aLength
[in] aFlags
用于指定此操作的选项的标志(请参阅上面的枚举)。
返回值
OT_ERROR_NONE
已成功将数据复制到发送缓冲区,并将其发送到 TCP 端点。
OT_ERROR_FAILED
未能向 TCP 端点发送数据。

otTcpMbedTlsSslRecvCallback

int otTcpMbedTlsSslRecvCallback(
  void *aCtx,
  unsigned char *aBuf,
  size_t aLen
)

传递给 mbedtls_ssl_set_bio 的非阻塞接收回调。

具体说明
参数
[in] aCtx
[out] aBuf
要在其中接收数据的缓冲区。
[in] aLen
可以接收的最大数据量。
返回值
已接收的字节数或 mbedtls 错误代码。

otTcpMbedTlsSslSendCallback

int otTcpMbedTlsSslSendCallback(
  void *aCtx,
  const unsigned char *aBuf,
  size_t aLen
)

传递给 mbedtls_ssl_set_bio 的非阻塞发送回调。

具体说明
参数
[in] aCtx
[in] aBuf
要添加到发送缓冲区的数据。
[in] aLen
要添加到发送缓冲区的数据量。
返回值
已发送的字节数或 mbedtls 错误代码。

资源

OpenThread API 参考文档源自 GitHub 上提供的源代码。如需了解详情,或者为我们的文档做贡献,请参阅资源