Google 致力于为黑人社区推动种族平等。查看具体行动。

此页面由 Cloud Translation API 翻译。

TCP

此模块包含用于控制 TCP 通信的功能。

摘要

枚举
`anonymous enum`	枚举定义传递给 otTcpConnect() 的标志。
`anonymous enum`	枚举定义传递给 `otTcpSendByReference` 的标志。
`otTcpDisconnectedReason`	枚举
`otTcpIncomingConnectionAction{ OT_TCP_INCOMING_CONNECTION_ACTION_ACCEPT, OT_TCP_INCOMING_CONNECTION_ACTION_DEFER, OT_TCP_INCOMING_CONNECTION_ACTION_REFUSE }`	枚举定义传入的连接操作。

类型定义符
`otLinkedBuffer`	typedef `struct otLinkedBuffer` 用于 TCP 的链接缓冲区结构。
`otTcpAcceptDone)(otTcpListener aListener, otTcpEndpoint aEndpoint, const otSockAddr *aPeer)`	typedef `void(*` 此回调表示 TCP 连接现在已准备好进行双向通信。
`otTcpAcceptReady)(otTcpListener aListener, const otSockAddr aPeer, otTcpEndpoint **aAcceptInto)`	typedef `otTcpIncomingConnectionAction(*` 此回调表示与此 TCP 监听器匹配的传入连接已到达。
`otTcpDisconnected)(otTcpEndpoint *aEndpoint, otTcpDisconnectedReason aReason)`	typedef `void(*` 此回调表示连接已断开且不应再使用，或者连接已进入 TIME-WAIT 状态。
`otTcpDisconnectedReason`	typedef `enum otTcpDisconnectedReason`
`otTcpEndpoint`	typedef `struct otTcpEndpoint`
`otTcpEndpointInitializeArgs`	typedef `struct otTcpEndpointInitializeArgs` 包含 otTcpEndpointInitialize() 函数的参数。
`otTcpEstablished)(otTcpEndpoint *aEndpoint)`	typedef `void(*` 此回调告知应用 TCP 三次握手已完成，并且现在已建立连接。
`otTcpForwardProgress)(otTcpEndpoint *aEndpoint, size_t aInSendBuffer, size_t aBacklog)`	typedef `void(*` 此回调会通知应用，将数据从发送缓冲区传输到接收方的操作是否已完成。
`otTcpIncomingConnectionAction`	typedef `enum otTcpIncomingConnectionAction` 定义传入的连接操作。
`otTcpListener`	typedef `struct otTcpListener`
`otTcpListenerInitializeArgs`	typedef `struct otTcpListenerInitializeArgs` 包含 otTcpListenerInitialize() 函数的参数。
`otTcpReceiveAvailable)(otTcpEndpoint *aEndpoint, size_t aBytesAvailable, bool aEndOfStream, size_t aBytesRemaining)`	typedef `void(*` 此回调指示接收缓冲区中可用的字节数。
`otTcpSendDone)(otTcpEndpoint aEndpoint, otLinkedBuffer aData)`	typedef `void(*` 此回调会通知应用提供的 `aData` 中的数据已被连接对等方确认，并且应用可以回收 `aData` 及其包含的数据。

函数
`otTcpAbort(otTcpEndpoint *aEndpoint)`	`otError` 强制终止与此 TCP 端点关联的 TCP 连接。
`otTcpBind(otTcpEndpoint aEndpoint, const otSockAddr aSockName)`	`otError` 将 TCP 端点绑定到 IP 地址和端口。
`otTcpCommitReceive(otTcpEndpoint *aEndpoint, size_t aNumBytes, uint32_t aFlags)`	`otError` 通知 TCP 堆栈在接收缓冲区开始时已处理完 `aNumBytes` 个字节的数据，TCP 堆栈不需要继续在接收缓冲区中保留这些字节。
`otTcpConnect(otTcpEndpoint aEndpoint, const otSockAddr aSockName, uint32_t aFlags)`	`otError` 记录此连接的远程主机和端口。
`otTcpEndpointDeinitialize(otTcpEndpoint *aEndpoint)`	`otError` 取消初始化此 TCP 端点。
`otTcpEndpointGetContext(otTcpEndpoint *aEndpoint)`	`void *` 在初始化时获取与 `aEndpoint` 关联的上下文指针。
`otTcpEndpointGetInstance(otTcpEndpoint *aEndpoint)`	`otInstance *` 在初始化时获取与 `aEndpoint` 关联的 otInstance。
`otTcpEndpointInitialize(otInstance aInstance, otTcpEndpoint aEndpoint, const otTcpEndpointInitializeArgs *aArgs)`	`otError` 初始化 TCP 端点。
`otTcpGetLocalAddress(const otTcpEndpoint *aEndpoint)`	`const otSockAddr *` 获取指向 TCP 端点的本地主机和端口的指针。
`otTcpGetPeerAddress(const otTcpEndpoint *aEndpoint)`	`const otSockAddr *` 获取指向 TCP 端点对等方的主机和端口的指针。
`otTcpListen(otTcpListener aListener, const otSockAddr aSockName)`	`otError` 导致与指定 IP 地址和端口匹配的传入 TCP 连接触发此 TCP 监听器的回调。
`otTcpListenerDeinitialize(otTcpListener *aListener)`	`otError` 取消初始化此 TCP 监听器。
`otTcpListenerGetContext(otTcpListener *aListener)`	`void *` 在初始化时获取与 `aListener` 关联的上下文指针。
`otTcpListenerGetInstance(otTcpListener *aListener)`	`otInstance *` 在初始化时获取与 `aListener` 关联的 otInstance。
`otTcpListenerInitialize(otInstance aInstance, otTcpListener aListener, const otTcpListenerInitializeArgs *aArgs)`	`otError` 初始化 TCP 监听器。
`otTcpReceiveByReference(otTcpEndpoint aEndpoint, const otLinkedBuffer *aBuffer)`	`otError` 为应用提供链接的缓冲区链，该链引用当前位于 TCP 接收缓冲区中的数据。
`otTcpReceiveContiguify(otTcpEndpoint *aEndpoint)`	`otError` 将接收缓冲区重新组织为在内存中完全连续。
`otTcpSendByExtension(otTcpEndpoint *aEndpoint, size_t aNumBytes, uint32_t aFlags)`	`otError` 通过将发送缓冲区中最终的 otLinkedBuffer 的长度延长指定的大小，将数据添加到发送缓冲区。
`otTcpSendByReference(otTcpEndpoint aEndpoint, otLinkedBuffer aBuffer, uint32_t aFlags)`	`otError` 将 `aBuffer` 所指向的链接缓冲区所引用的数据添加到发送缓冲区。
`otTcpSendEndOfStream(otTcpEndpoint *aEndpoint)`	`otError` 通知连接对等方此 TCP 端点不会再发送更多数据。
`otTcpStopListening(otTcpListener *aListener)`	`otError` 使此 TCP 监听器停止监听传入连接。

结构体
otLinkedBuffer	用于 TCP 的链接缓冲区结构。
otTcpEndpoint	表示 TCP 端点。
otTcpEndpointInitializeArgs	包含 otTcpEndpointInitialize() 函数的参数。
otTcpListener	表示 TCP 监听器。
otTcpListenerInitializeArgs	包含 otTcpListenerInitialize() 函数的参数。

枚举

匿名枚举

 anonymous enum

定义传递给 otTcpConnect() 的标志。

匿名枚举

 anonymous enum

定义传递给 otTcpSendByReference 的标志。

otTcpDisconnectedReason

 otTcpDisconnectedReason

otTcpIncomingConnectionAction

 otTcpIncomingConnectionAction

定义传入的连接操作。

此方法在 otTcpAcceptReady() 回调中使用。

属性
`OT_TCP_INCOMING_CONNECTION_ACTION_ACCEPT`	接受传入连接。
`OT_TCP_INCOMING_CONNECTION_ACTION_DEFER`	推迟（静默忽略）传入连接。
`OT_TCP_INCOMING_CONNECTION_ACTION_REFUSE`	拒绝传入连接。

类型定义符

otLinkedBuffer

struct otLinkedBuffer otLinkedBuffer

用于 TCP 的链接缓冲区结构。

单个 otLinkedBuffer 结构通过 mData 和 mLength 引用内存中的字节数组。mNext 字段用于形成 otLinkedBuffer 结构链。

otTcpAcceptDone

void(* otTcpAcceptDone)(otTcpListener *aListener, otTcpEndpoint *aEndpoint, const otSockAddr *aPeer)

此回调表示 TCP 连接现在已准备好进行双向通信。

对于 TCP Fast Open，这可能是在 TCP 连接实际完成之前完成。应用会获得接受连接的 TCP 监听器和接受连接进入的 TCP 端点的上下文指针。所提供的上下文是与 TCP 监听器关联的上下文。

具体说明

参数

`[in] aListener`	与传入连接匹配的 TCP 监听器。
`[in] aEndpoint`	接受传入连接的 TCP 端点。
`[in] aPeer`	发起传入连接的主机和端口。

otTcpAcceptReady

otTcpIncomingConnectionAction(* otTcpAcceptReady)(otTcpListener *aListener, const otSockAddr *aPeer, otTcpEndpoint **aAcceptInto)

此回调表示与此 TCP 监听器匹配的传入连接已到达。

典型的响应是让应用接受传入连接。为此，它会使用指向要接受传入连接的 otTcpEndpoint 的指针填充 aAcceptInto。此 otTcpEndpoint 必须已使用 otTcpEndpointInitialize() 初始化。然后，应用会返回 OT_TCP_INCOMING_CONNECTION_ACTION_ACCEPT。

或者，应用可以拒绝接受传入连接。应用可通过两种方式执行此操作。首先，如果应用返回 OT_TCP_INCOMING_CONNECTION_ACTION_DEFER，则 OpenThread 会以静默方式忽略连接建立请求；连接对等方可能会重新传输请求，此时将再次调用回调。如果当前没有资源可用于接受连接，这会非常有用，但当连接对等方重新传输其连接建立尝试时，这些资源可能可用。其次，如果应用返回 OT_TCP_INCOMING_CONNECTION_ACTION_REFUSE，则 OpenThread 向尝试建立连接的主机发送“连接被拒绝”消息。如果应用拒绝传入连接，则无需填充 aAcceptInto。

具体说明

参数

`[in] aListener`	与传入连接匹配的 TCP 监听器。
`[in] aPeer`	发起传入连接的主机和端口。
`[out] aAcceptInto`	接受传入连接的 TCP 端点。

返回值

说明如何处理传入连接。

otTcpDisconnected

void(* otTcpDisconnected)(otTcpEndpoint *aEndpoint, otTcpDisconnectedReason aReason)

此回调表示连接已断开且不应再使用，或者连接已进入 TIME-WAIT 状态。

如果尝试建立连接的时机（通过调用 otTcpConnect() 发起）失败，或者在尝试之后的任何时间点（例如，连接超时或从连接对等端收到 RST 片段）失败，都可能会发生这种情况。此回调触发后，应用可以回收应用为此连接提供的所有资源（即它们引用的任何 otLinkedBuffers 和内存，但不是 TCP 端点本身或接收缓冲区的空间）。在连接进入 TIME-WAIT 状态时，系统会调用此回调函数两次，一次是在进入 TIME-WAIT 状态时（使用 OT_TCP_DISCONNECTED_REASON_TIME_WAIT），另一次是在 TIME-WAIT 状态到期时（使用 OT_TCP_DISCONNECTED_REASON_NORMAL）。

具体说明

参数

`[in] aEndpoint`	连接已断开的 TCP 端点。
`[in] aReason`	连接丢失的原因。

otTcpDisconnectedReason

enum otTcpDisconnectedReason otTcpDisconnectedReason

otTcpEndpoint

struct otTcpEndpoint otTcpEndpoint

otTcpEndpointInitializeArgs

struct otTcpEndpointInitializeArgs otTcpEndpointInitializeArgs

包含 otTcpEndpointInitialize() 函数的参数。

otTcpEstablished

void(* otTcpEstablished)(otTcpEndpoint *aEndpoint)

此回调告知应用 TCP 三次握手已完成，并且现在已建立连接。

具体说明

参数

[in] aEndpoint

现在已建立连接的 TCP 端点。

otTcpForwardProgress

void(* otTcpForwardProgress)(otTcpEndpoint *aEndpoint, size_t aInSendBuffer, size_t aBacklog)

此回调会通知应用，将数据从发送缓冲区传输到接收方的操作是否已完成。

此回调不是正确 TCP 操作所必需的。大多数应用只要在 TCP 堆栈用完关联的缓冲区后，即可依靠 otTcpSendDone() 回调来回收这些缓冲区。此回调的用途是支持高级应用，这些应用能够从关于连接在将数据传输到连接对等方方面如何进展的更精细信息中受益。

此回调的操作与 TCP 的发送缓冲区紧密关联。发送缓冲区可以理解为包含两个区域。第一个是发送缓冲区头部（前部）的“传输中”区域。它对应的是已发送给接收方但尚未确认的数据。其次是“积压”区域，其中包含发送缓冲区中不在“运行中”区域的所有数据。“积压”区域对应于排队等待发送但尚未发送的数据。

调用该回调函数来响应两种类型的事件。首先，发送缓冲区的“传输中”区域可能会缩小（例如，在接收方确认我们之前发送的数据时）。其次，发送缓冲区的“积压”区域可能会缩小（例如，新数据被发送出去）。这两种情况通常会同时发生，以响应来自连接对等方的 ACK 片段，因此它们会在单个回调中合并。

TCP 堆栈仅使用发送缓冲区尾部的 aInSendBuffer 字节；如果 aInSendBuffer 减少量 x，则表示 x 以前位于发送缓冲区头部的额外字节不再属于发送缓冲区的一部分，现在可以被应用回收（即覆盖）。请注意，otLinkedBuffer 结构本身只有在其引用的所有字节不再属于发送缓冲区的一部分后，才能被回收。

此回调包含 otTcpSendDone()，具体意义如下：应用可以通过将 aInSendBuffer 与每个链接缓冲区中的字节数进行比较来确定何时可以回收关联的缓冲区。不过，我们希望 otTcpSendDone() 能够直接传达可以回收哪些 otLinkedBuffers 更加简单易用。如果两个回调均已注册并由同一事件触发（例如，接收到相同的 ACK 片段），则系统会先触发 otTcpSendDone() 回调，然后再触发此回调。

此外，此回调还提供 aBacklog，用于指示发送缓冲区中有多少字节尚未传输。对于只想在确信数据很快会发送出去时将数据添加到发送缓冲区的应用，可能需要仅在 aBacklog 非常小（0 或接近 0）时才发送数据。例如，应用可以使用 aBacklog，以便通过删除或汇总数据来响应队列构建，从而避免造成数据积压。

使用正字节数组调用 otTcpSendByReference() 或 otTcpSendByExtension() 后，系统一定会调用 otTcpForwardProgress() 回调，以指明添加到发送缓冲区的字节何时发出。可以在字节添加到发送缓冲区后立即调用 otTcpForwardProgress()（如果其中一些字节立即发送出去，减少了积压），也可以在以后的某个时间（在连接发出部分或全部数据后减少积压）。“立即”是指回调会立即安排在 tasklet 中执行；为了避免与重入相关的复杂性，切勿通过 otTcpSendByReference() 或 otTcpSendByExtension() 函数直接调用 otTcpForwardProgress() 回调。

具体说明

参数

`[in] aEndpoint`	连接的 TCP 端点。
`[in] aInSendBuffer`	发送缓冲区中的字节数（“运行中”和“积压”区域的总和）。
`[in] aBacklog`	已加入待发送队列但尚未发送的字节数（“积压”区域）。

otTcpIncomingConnectionAction

enum otTcpIncomingConnectionAction otTcpIncomingConnectionAction

定义传入的连接操作。

此方法在 otTcpAcceptReady() 回调中使用。

otTcpListener

struct otTcpListener otTcpListener

otTcpListenerInitializeArgs

struct otTcpListenerInitializeArgs otTcpListenerInitializeArgs

包含 otTcpListenerInitialize() 函数的参数。

otTcpReceiveAvailable

void(* otTcpReceiveAvailable)(otTcpEndpoint *aEndpoint, size_t aBytesAvailable, bool aEndOfStream, size_t aBytesRemaining)

此回调指示接收缓冲区中可用的字节数。

每当向接收缓冲区添加字节时以及达到数据流末尾时，系统都会调用此方法。如果已达到数据流的末尾（即，如果由于连接对等端已关闭连接端写入而没有更多数据可供读取），则 aEndOfStream 为 true。最后，aBytesRemaining 表示接收缓冲区中剩余的容量可用来存储收到的其他数据。

具体说明

参数

`[in] aEndpoint`	连接的 TCP 端点。
`[in] aBytesAvailable`	连接的接收缓冲区中的字节数。
`[in] aEndOfStream`	指示是否可以接收除连接的接收缓冲区中已有的数据以外，是否可以接收其他数据。
`[in] aBytesRemaining`	接收缓冲区填满之前可以接收的额外字节数。

otTcpSendDone

void(* otTcpSendDone)(otTcpEndpoint *aEndpoint, otLinkedBuffer *aData)

此回调会通知应用提供的 aData 中的数据已被连接对等方确认，并且应用可以回收 aData 及其包含的数据。

aData 保证与通过 otTcpSendByReference() 传入 TCP 的那些完全相同，包括通过 otTcpSendByExtension() 影响的任何扩展。

具体说明

参数

`[in] aEndpoint`	连接的 TCP 端点。
`[in] aData`	指向可回收的 otLinkedBuffer 的指针。

函数

otTcpAbort

otError otTcpAbort(
  otTcpEndpoint *aEndpoint
)

强制终止与此 TCP 端点关联的 TCP 连接。

这会立即使 TCP 端点可以自由用于其他连接，并清空发送和接收缓冲区，从而将应用在 otTcpSendByReference() 和 otTcpSendByExtension() 调用中提供的任何数据的所有权移回给应用。TCP 端点的回调和接收缓冲区内存仍与 TCP 端点相关联。

具体说明

参数

[in] aEndpoint

指向 TCP 端点结构的指针，表示要中止的 TCP 端点。

返回值

`OT_ERROR_NONE`	已成功取消 TCP 端点的连接。
`OT_ERROR_FAILED`	未能取消 TCP 端点的连接。

otTcpBind

otError otTcpBind(
  otTcpEndpoint *aEndpoint,
  const otSockAddr *aSockName
)

将 TCP 端点绑定到 IP 地址和端口。

具体说明

参数

`[in] aEndpoint`	指向要绑定的 TCP 端点结构的指针。
`[in] aSockName`	要绑定此 TCP 端点的地址和端口。

返回值

`OT_ERROR_NONE`	已成功绑定 TCP 端点。
`OT_ERROR_FAILED`	未能绑定 TCP 端点。

otTcpCommitReceive

otError otTcpCommitReceive(
  otTcpEndpoint *aEndpoint,
  size_t aNumBytes,
  uint32_t aFlags
)

通知 TCP 堆栈在接收缓冲区开始时已处理完 aNumBytes 个字节的数据，TCP 堆栈不需要继续在接收缓冲区中保留这些字节。

具体说明

参数

`[in] aEndpoint`	指向 TCP 端点结构的指针，表示要在其上接收数据的 TCP 端点。
`[in] aNumBytes`	已消耗的字节数。
`[in] aFlags`	用于指定此操作的选项的标志（尚无）。

返回值

`OT_ERROR_NONE`	已成功完成接收操作。
`OT_ERROR_FAILED`	未能完成接收操作。

otTcpConnect

otError otTcpConnect(
  otTcpEndpoint *aEndpoint,
  const otSockAddr *aSockName,
  uint32_t aFlags
)

记录此连接的远程主机和端口。

必须通过 aFlags 启用或停用 TCP Fast Open。如果此政策已停用，系统会立即启动 TCP 连接建立握手。如果已启用，则此函数仅记录远程主机和端口，TCP 连接建立握手只会在首次调用 otTcpSendByReference() 时发生。

如果 TCP Fast Open 处于停用状态，调用方必须等待 otTcpEstablished 回调（指示 TCP 连接建立握手完成），然后才能开始发送数据（例如通过调用 otTcpSendByReference()）。

具体说明

参数

`[in] aEndpoint`	指向要连接的 TCP 端点结构的指针。
`[in] aSockName`	要连接的主机的 IP 地址和端口。
`[in] aFlags`	用于指定此操作的选项的标志（请参阅上面的枚举）。

返回值

`OT_ERROR_NONE`	成功完成操作。
`OT_ERROR_FAILED`	未能完成此操作。

otTcpEndpointDeinitialize

otError otTcpEndpointDeinitialize(
  otTcpEndpoint *aEndpoint
)

取消初始化此 TCP 端点。

这意味着 OpenThread 不再跟踪此 TCP 端点，并且会取消分配它在内部为此 TCP 端点分配的所有资源。应用可以根据需要重复使用支持 TCP 端点的内存。

如果它对应于实时 TCP 连接，则会意外终止连接（如 otTcpAbort()）。应用为此 TCP 端点提供的所有资源（发送缓冲区的链接缓冲区、接收缓冲区的内存、aEndpoint 结构本身等）都会立即返回给应用。

具体说明

参数

[in] aEndpoint

指向要取消初始化的 TCP 端点结构的指针。

返回值

`OT_ERROR_NONE`	已成功取消初始化 TCP 端点。
`OT_ERROR_FAILED`	未能取消初始化 TCP 端点。

otTcpEndpointGetContext

void * otTcpEndpointGetContext(
  otTcpEndpoint *aEndpoint
)

在初始化时获取与 aEndpoint 关联的上下文指针。

具体说明

参数

[in] aEndpoint

要获取其上下文的 TCP 端点。

返回值

与 aEndpoint 关联的上下文指针。

otTcpEndpointGetInstance

otInstance * otTcpEndpointGetInstance(
  otTcpEndpoint *aEndpoint
)

在初始化时获取与 aEndpoint 关联的 otInstance。

具体说明

参数

[in] aEndpoint

要获取其实例的 TCP 端点。

返回值

与 aEndpoint 关联的 otInstance 指针。

otTcpEndpointInitialize

otError otTcpEndpointInitialize(
  otInstance *aInstance,
  otTcpEndpoint *aEndpoint,
  const otTcpEndpointInitializeArgs *aArgs
)

初始化 TCP 端点。

调用此函数会使 OpenThread 跟踪 TCP 端点，并在 aEndpoint 内存储和检索 TCP 数据。应用应避免直接访问或修改 aEndpoint 中的字段。如果应用需要回收内存支持 aEndpoint，则应调用 otTcpEndpointDeinitialize()。

具体说明

参数

`[in] aInstance`	指向 OpenThread 实例的指针。
`[in] aEndpoint`	指向 TCP 端点结构的指针。
`[in] aArgs`	指向参数结构的指针。

返回值

`OT_ERROR_NONE`	已成功打开 TCP 端点。
`OT_ERROR_FAILED`	未能打开 TCP 端点。

otTcpGetLocalAddress

const otSockAddr * otTcpGetLocalAddress(
  const otTcpEndpoint *aEndpoint
)

获取指向 TCP 端点的本地主机和端口的指针。

如果此套接字未处于连接状态，并且在上次断开连接后未绑定，则主机和端口的内容可能会过时。

具体说明

参数

[in] aEndpoint

要获取其本地主机和端口的 TCP 端点。

返回值

aEndpoint 的本地主机和端口。

otTcpGetPeerAddress

const otSockAddr * otTcpGetPeerAddress(
  const otTcpEndpoint *aEndpoint
)

获取指向 TCP 端点对等方的主机和端口的指针。

如果此套接字未处于连接状态，主机和端口的内容可能会过时。

具体说明

参数

[in] aEndpoint

要获取其对等方的主机和端口的 TCP 端点。

返回值

aEndpoint 的连接对等方的主机和端口。

otTcpListen

otError otTcpListen(
  otTcpListener *aListener,
  const otSockAddr *aSockName
)

导致与指定 IP 地址和端口匹配的传入 TCP 连接触发此 TCP 监听器的回调。

具体说明

参数

`[in] aListener`	指向应开始监听的 TCP 监听器结构的指针。
`[in] aSockName`	监听传入连接的地址和端口。

返回值

`OT_ERROR_NONE`	已成功启动对 TCP 监听器的监听。
`OT_ERROR_FAILED`	未能启动对 TCP 监听器的监听。

otTcpListenerDeinitialize

otError otTcpListenerDeinitialize(
  otTcpListener *aListener
)

取消初始化此 TCP 监听器。

这意味着 OpenThread 不再跟踪此 TCP 监听器，并取消分配它在内部为此 TCP 监听器分配的所有资源。应用可以根据需要重复使用支持 TCP 监听器的内存。

如果 TCP 监听器当前正在监听，它会停止监听。

具体说明

参数

[in] aListener

指向要取消初始化的 TCP 监听器结构的指针。

返回值

`OT_ERROR_NONE`	已成功取消初始化 TCP 监听器。
`OT_ERROR_FAILED`	未能取消初始化 TCP 监听器。

otTcpListenerGetContext

void * otTcpListenerGetContext(
  otTcpListener *aListener
)

在初始化时获取与 aListener 关联的上下文指针。

具体说明

参数

[in] aListener

要获取其上下文的 TCP 监听器。

返回值

与 aListener 关联的上下文指针。

otTcpListenerGetInstance

otInstance * otTcpListenerGetInstance(
  otTcpListener *aListener
)

在初始化时获取与 aListener 关联的 otInstance。

具体说明

参数

[in] aListener

要获取其实例的 TCP 监听器。

返回值

与 aListener 关联的 otInstance 指针。

otTcpListenerInitialize

otError otTcpListenerInitialize(
  otInstance *aInstance,
  otTcpListener *aListener,
  const otTcpListenerInitializeArgs *aArgs
)

初始化 TCP 监听器。

调用此函数会使 OpenThread 跟踪 TCP 监听器，并在 aListener 中存储和检索 TCP 数据。应用应避免直接访问或修改 aListener 中的字段。如果应用需要回收内存支持 aListener，则应调用 otTcpListenerDeinitialize()。

具体说明

参数

`[in] aInstance`	指向 OpenThread 实例的指针。
`[in] aListener`	指向 TCP 监听器结构的指针。
`[in] aArgs`	指向参数结构的指针。

返回值

`OT_ERROR_NONE`	成功打开 TCP 监听器。
`OT_ERROR_FAILED`	未能打开 TCP 监听器。

otTcpReceiveByReference

otError otTcpReceiveByReference(
  otTcpEndpoint *aEndpoint,
  const otLinkedBuffer **aBuffer
)

为应用提供链接的缓冲区链，该链引用当前位于 TCP 接收缓冲区中的数据。

关联的缓冲区链将一直有效，直到下一次调用“接收就绪”回调，或者下一次调用 otTcpReceiveContiguify() 或 otTcpCommitReceive()。

具体说明

参数

`[in] aEndpoint`	指向 TCP 端点结构的指针，表示要在其上接收数据的 TCP 端点。
`[out] aBuffer`	指向链接缓冲区链的指针，该指针引用当前位于接收缓冲区中的数据。

返回值

`OT_ERROR_NONE`	成功完成操作。
`OT_ERROR_FAILED`	未能完成此操作。

otTcpReceiveContiguify

otError otTcpReceiveContiguify(
  otTcpEndpoint *aEndpoint
)

将接收缓冲区重新组织为在内存中完全连续。

这是可选的；应用只需遍历通过调用 otTcpReceiveByReference 获取的链接缓冲区链。某些应用可能希望调用此函数以使接收缓冲区保持连续，以简化其数据处理，但这样会牺牲 CPU 时间来重新组织接收缓冲区中的数据。

具体说明

参数

[in] aEndpoint

指向要重新整理其接收缓冲区的 TCP 端点的指针。

返回值

`OT_ERROR_NONE`	成功完成操作。
`OT_ERROR_FAILED`	未能完成此操作。

otTcpSendByExtension

otError otTcpSendByExtension(
  otTcpEndpoint *aEndpoint,
  size_t aNumBytes,
  uint32_t aFlags
)

通过将发送缓冲区中最终的 otLinkedBuffer 的长度延长指定的大小，将数据添加到发送缓冲区。

如果发送缓冲区为空，则操作失败。

具体说明

参数

`[in] aEndpoint`	指向 TCP 端点结构的指针，表示要在其上发送数据的 TCP 端点。
`[in] aNumBytes`	扩展最终链接缓冲区长度的字节数。
`[in] aFlags`	用于指定此操作的选项的标志（请参阅上面的枚举）。

返回值

`OT_ERROR_NONE`	已成功将数据添加到发送缓冲区。
`OT_ERROR_FAILED`	未能将数据添加到发送缓冲区。

otTcpSendByReference

otError otTcpSendByReference(
  otTcpEndpoint *aEndpoint,
  otLinkedBuffer *aBuffer,
  uint32_t aFlags
)

将 aBuffer 所指向的链接缓冲区所引用的数据添加到发送缓冲区。

成功调用此函数后，链接缓冲区及其引用的数据将归 TCP 堆栈所有；在“发送完成”回调将这些对象的所有权返回给应用程序之前，应用程序不应对其进行修改。可以调用此函数以将另一个链接的缓冲区添加到发送队列中，即使该函数的上一调用的“senddone”回调尚未触发。

请注意，aBuffer 不应链接；其 mNext 字段应为 NULL。如果在此调用之后立即添加其他数据，则应使用 OT_TCP_SEND_MORE_TO_COME 标记来提示 TCP 实现。

具体说明

参数

`[in] aEndpoint`	指向 TCP 端点结构的指针，表示要在其上发送数据的 TCP 端点。
`[in] aBuffer`	指向链接缓冲区链的指针，用于引用要添加到发送缓冲区的数据。
`[in] aFlags`	用于指定此操作的选项的标志（请参阅上面的枚举）。

返回值

`OT_ERROR_NONE`	已成功将数据添加到发送缓冲区。
`OT_ERROR_FAILED`	未能将数据添加到发送缓冲区。

otTcpSendEndOfStream

otError otTcpSendEndOfStream(
  otTcpEndpoint *aEndpoint
)

通知连接对等方此 TCP 端点不会再发送更多数据。

当应用没有更多要发送到连接对等方的数据时，应使用此方法。对于此连接，连接对等方今后的读取将会导致“流式传输结束”条件，今后对此连接端点的写入将会失败。

“流式传输结束”条件仅在连接对等方收到之前提供给 TCP 堆栈发送的任何数据后才适用。

具体说明

参数

[in] aEndpoint

指向 TCP 端点结构的指针，表示要关停的 TCP 端点。

返回值

`OT_ERROR_NONE`	已成功将“直播结束”条件加入传输队列。
`OT_ERROR_FAILED`	未能将“流式传输结束”条件加入传输队列。

otTcpStopListening

otError otTcpStopListening(
  otTcpListener *aListener
)

使此 TCP 监听器停止监听传入连接。

具体说明

参数

[in] aListener

指向应停止监听的 TCP 监听器结构的指针。

返回值

`OT_ERROR_NONE`	已成功停止对 TCP 监听器的监听。
`OT_ERROR_FAILED`	未能停止监听 TCP 监听器。

宏

OT_TCP_ENDPOINT_TCB_NUM_PTR

 OT_TCP_ENDPOINT_TCB_NUM_PTR 36

OT_TCP_ENDPOINT_TCB_SIZE_BASE

 OT_TCP_ENDPOINT_TCB_SIZE_BASE 392

选择 OT_TCP_ENDPOINT_TCB_SIZE_BASE 和 OT_TCP_ENDPOINT_TCB_NUM_POINTERS，以使 otTcpEndpoint 的 mTcb 字段与 TCPlp 中的结构 tcpcb 具有相同的大小。

这是必要的，因为 mTcb 字段虽然在声明中不透明，但在 TCP 实现中被视为结构体 tcpcb。

OT_TCP_LISTENER_TCB_NUM_PTR

 OT_TCP_LISTENER_TCB_NUM_PTR 3

OT_TCP_LISTENER_TCB_SIZE_BASE

 OT_TCP_LISTENER_TCB_SIZE_BASE 16

选择 OT_TCP_LISTENER_TCB_SIZE_BASE 和 OT_TCP_LISTENER_TCB_NUM_POINTERS，使 otTcpListener 的 mTcbListener 字段与 TCPlp 中的结构 tcpcb_listen 大小相同。

这是必要的，因为 mTcbListen 字段虽然在声明中是不透明的，但在 TCP 实现中被视为结构体 tcpcb。

OT_TCP_RECEIVE_BUFFER_SIZE_FEW_HOPS

 OT_TCP_RECEIVE_BUFFER_SIZE_FEW_HOPS 2598

对于遍历大约 3 个或更少无线跃点的 TCP 连接，建议的缓冲区大小。

在内存特别受限的平台上以及不需要高带宽的情况下，可能需要手动选择较小的缓冲区空间。

OT_TCP_RECEIVE_BUFFER_SIZE_MANY_HOPS

 OT_TCP_RECEIVE_BUFFER_SIZE_MANY_HOPS 4157

建议遍历许多无线跃点的 TCP 连接的缓冲区大小。

如果 TCP 连接遍历大量跃点（超过 6 个左右），那么我们建议您手动选择较大的缓冲区空间。

资源

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