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() 回调旨在让用户了解环形发送缓冲区中何时有可用空间。在附加了 otTcpCircularSendBuffer 的 otTcpEndpoint 上，应用必须在回调函数开始时安装 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 循环发送缓冲区来管理缓冲。

调用此函数后，aSendBuffer 和 aEndpoint 将被视为彼此“关联”。附加后，对 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 上提供的源代码。如需了解详情，或者为我们的文档做贡献，请参阅资源。