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

此页面由 Cloud Translation API 翻译。

nl::Inet::TCPEndPoint

#include <src/inet/TCPEndPoint.h>

此类的对象表示 TCP 传输端点。

摘要

Nest Inet 层封装了与 TCP 传输端点（Linux 和 BSD 派生系统上的 SOCK_STREAM 套接字）或 LwIP TCP 协议控制块交互的方法，因为系统会进行相应配置。

继承

公共类型
`@10{ kState_Ready = kBasisState_Closed, kState_Bound = 1, kState_Listening = 2, kState_Connecting = 3, kState_Connected = 4, kState_SendShutdown = 5, kState_ReceiveShutdown = 6, kState_Closing = 7, kState_Closed = 8 }`	枚举底层端点的基本动态状态。
`OnAcceptErrorFunct)(TCPEndPoint *endPoint, INET_ERROR err)`	typedef `void(*` 连接接受错误事件处理函数的类型。
`OnConnectCompleteFunct)(TCPEndPoint *endPoint, INET_ERROR err)`	typedef `void(*` 连接建立事件处理函数的类型。
`OnConnectionClosedFunct)(TCPEndPoint *endPoint, INET_ERROR err)`	typedef `void(*` 连接建立事件处理函数的类型。
`OnConnectionReceivedFunct)(TCPEndPoint listeningEndPoint, TCPEndPoint conEndPoint, const IPAddress &peerAddr, uint16_t peerPort)`	typedef `void(*` 收到的连接事件处理函数的类型。
`OnDataReceivedFunct)(TCPEndPoint endPoint, Weave::System::PacketBuffer data)`	typedef `void(*` 数据接收事件处理函数的类型。
`OnDataSentFunct)(TCPEndPoint *endPoint, uint16_t len)`	typedef `void(*` 数据传输事件处理函数的类型。
`OnPeerCloseFunct)(TCPEndPoint *endPoint)`	typedef `void(*` 半关闭接收事件处理函数的类型。
`OnTCPSendIdleChangedFunct)(TCPEndPoint *endPoint, bool isIdle)`	typedef `void(*` TCP SendIdle 类型更改了信号处理函数。

公共属性
`OnAcceptError`	`OnAcceptErrorFunct` 端点的连接接受事件处理函数委托。
`OnConnectComplete`	`OnConnectCompleteFunct` 端点的连接建立事件处理函数委托。
`OnConnectionClosed`	`OnConnectionClosedFunct` 端点的关闭事件处理函数委托。
`OnConnectionReceived`	`OnConnectionReceivedFunct` 端点的连接接收事件处理函数委托。
`OnDataReceived`	`OnDataReceivedFunct` 端点的消息文本接收事件处理函数委托。
`OnDataSent`	`OnDataSentFunct` 端点的消息文本传输事件处理函数委托。
`OnPeerClose`	`OnPeerCloseFunct` 端点的半关闭接收事件处理函数委托。
`OnTCPSendIdleChanged`	`OnTCPSendIdleChangedFunct` 端点的事件处理函数委托会在 TCP 连接的发送通道的空闲时间发生变化时发出信号。
`ReceiveEnabled`	`bool` 指示应用是否正在接收数据的控制开关。
`State`	`enum nl::Inet::TCPEndPoint::@10` 底层端点的基本动态状态。

公共函数
`Abort(void)`	`void` 取消端点关闭，换言之，发送 RST 数据包。
`AckReceive(uint16_t len)`	`INET_ERROR` 确认收到消息文字。
`Bind(IPAddressType addrType, IPAddress addr, uint16_t port, bool reuseAddr)`	`INET_ERROR` 将端点绑定到接口 IP 地址。
`Close(void)`	`INET_ERROR` 启动 TCP 完全关闭，换言之，发送和接收均结束。
`Connect(IPAddress addr, uint16_t port, InterfaceId intf)`	`INET_ERROR` 启动 TCP 连接。
`DisableKeepAlive(void)`	`INET_ERROR` 停用 TCP“keep-alive”选项。
`DisableReceive(void)`	`void` 停用信号接收。
`EnableKeepAlive(uint16_t interval, uint16_t timeoutCount)`	`INET_ERROR` 启用 TCP“keep-alive”选项。
`EnableNoDelay(void)`	`INET_ERROR` EnableNoDelay。
`EnableReceive(void)`	`void` 启用信号接收。
`Free(void)`	`void` 启动（或继续）TCP 完全关闭，忽略错误。
`GetLocalInfo(IPAddress retAddr, uint16_t retPort)`	`INET_ERROR` 提取本地端点的 IP 地址和 TCP 端口。
`GetPeerInfo(IPAddress retAddr, uint16_t retPort) const`	`INET_ERROR` 提取远程端点的 IP 地址和 TCP 端口。
`IsConnected(void) const`	`bool` 提取是否建立 TCP 连接。
`Listen(uint16_t backlog)`	`INET_ERROR` 准备端点以接收 TCP 消息。
`LogId(void)`	`uint16_t` 获取端点的标识符。
`MarkActive(void)`	`void` 记录活动，也就是重置闲置计时器。
`PendingReceiveLength(void)`	`uint32_t` 提取未确认的接收数据的长度。
`PendingSendLength(void)`	`uint32_t` 提取等待首次传输的数据的长度。
`PutBackReceivedData(Weave::System::PacketBuffer *data)`	`INET_ERROR` 将消息文本推送回接收队列的开头。
`Send(Weave::System::PacketBuffer *data, bool push)`	`INET_ERROR` 通过 TCP 连接发送消息文本。
`SetConnectTimeout(const uint32_t connTimeoutMsecs)`	`void` 设置超时，以便连接成功或返回错误。
`SetUserTimeout(uint32_t userTimeoutMillis)`	`INET_ERROR` 设置 TCP_USER_TIMEOUT 套接字选项。
`Shutdown(void)`	`INET_ERROR` 启动 TCP 半关闭，也就是完成发送。

公共类型

@10

@10

底层端点的基本动态状态。

对象初始化为“就绪”状态，然后继续到后续状态，相应后续状态则是 TCP 传输状态机的简化状态。

注意：出于历史二进制文件兼容性原因，kBasisState_Closed 状态枚举会映射到 kState_Ready。现有 kState_Closed 旨在单独标识之前处于 kState_Ready 和 kState_Closed 状态的“尚未打开”和“之前打开现已关闭”之间的区别。

属性
`kState_Bound`	端点绑定，但不监听。
`kState_Closed`	端点已关闭，可以发布。
`kState_Closing`	端点双向关闭。
`kState_Connected`	端点已连接，可以进行 tx/rx 传输。
`kState_Connecting`	端点正在尝试连接。
`kState_Listening`	端点接收连接。
`kState_Ready`	端点已初始化，但尚未绑定。
`kState_ReceiveShutdown`	端点响应了半关闭。
`kState_SendShutdown`	端点发起了半关闭。

OnAcceptErrorFunct

void(* OnAcceptErrorFunct)(TCPEndPoint *endPoint, INET_ERROR err)

连接接受错误事件处理函数的类型。

向 OnAcceptError 委托成员提供此类型的函数，以处理 endPoint 上的连接接受错误事件。err 参数提供有关错误类型的具体详细信息。

具体说明

参数

`[in] endPoint`	与事件关联的 TCP 端点。
`[in] err`	错误的原因。

OnConnectCompleteFunct

void(* OnConnectCompleteFunct)(TCPEndPoint *endPoint, INET_ERROR err)

连接建立事件处理函数的类型。

向 OnConnectComplete 委托成员提供此类型的函数，以处理 endPoint 上的连接建立事件。err 参数用于区分成功连接与失败连接。

具体说明

参数

`[in] endPoint`	与事件关联的 TCP 端点。
`[in] err`	如果成功，则为 `INET_NO_ERROR`，否则为其他代码。

OnConnectionClosedFunct

void(* OnConnectionClosedFunct)(TCPEndPoint *endPoint, INET_ERROR err)

连接建立事件处理函数的类型。

向 OnConnectionClosed 委托成员提供此类型的函数，以处理 endPoint 上的连接终止事件。err 参数用于区分成功终止与失败。

具体说明

参数

`[in] endPoint`	与事件关联的 TCP 端点。
`[in] err`	如果成功，则为 `INET_NO_ERROR`，否则为其他代码。

OnConnectionReceivedFunct

void(* OnConnectionReceivedFunct)(TCPEndPoint *listeningEndPoint, TCPEndPoint *conEndPoint, const IPAddress &peerAddr, uint16_t peerPort)

收到的连接事件处理函数的类型。

向 OnConnectionReceived 委托成员提供此类型的函数，以处理 listeningEndPoint 上的连接接收事件。新收到的端点 conEndPoint 位于 IP 地址 peerAddr 和 TCP 端口 peerPort。

具体说明

参数

`[in] listeningEndPoint`	监听 TCP 端点。
`[in] conEndPoint`	新收到的 TCP 端点。
`[in] peerAddr`	远程对等方的 IP 地址。
`[in] peerPort`	远程对等方的 TCP 端口。

OnDataReceivedFunct

void(* OnDataReceivedFunct)(TCPEndPoint *endPoint, Weave::System::PacketBuffer *data)

数据接收事件处理函数的类型。

向 OnDataReceived 委托成员提供此类型的函数，以处理 endPoint 上的数据接收事件，其中 data 是收到的消息文本。

具体说明

参数

`[in] endPoint`	与事件关联的 TCP 端点。
`[in] data`	收到的数据。

数据接收事件处理脚本必须确认使用 AckReceive 方法处理的数据。除非改用 PutBackReceivedData，否则还必须对数据缓冲区调用 Free 方法。

OnDataSentFunct

void(* OnDataSentFunct)(TCPEndPoint *endPoint, uint16_t len)

数据传输事件处理函数的类型。

向 OnDataSent 委托成员提供此类型的函数，以处理 endPoint 上的数据传输事件，其中 len 是添加到 TCP 传输窗口的消息文本的长度，可以由底层网络堆栈发送。

具体说明

参数

`[in] endPoint`	与事件关联的 TCP 端点。
`[in] len`	添加到传输窗口的字节数。

OnPeerCloseFunct

void(* OnPeerCloseFunct)(TCPEndPoint *endPoint)

半关闭接收事件处理函数的类型。

向 OnPeerClose 委托成员提供此类型的函数，以处理 endPoint 上的连接终止事件。

具体说明

参数

[in] endPoint

与事件关联的 TCP 端点。

OnTCPSendIdleChangedFunct

void(* OnTCPSendIdleChangedFunct)(TCPEndPoint *endPoint, bool isIdle)

TCP SendIdle 类型更改了信号处理函数。

向 OnTCPSendIdleChanged 委托成员提供此类型的函数，以处理 TCPEndPoint 发送通道在空闲和不空闲之间更改状态的事件。

具体说明

参数

`[in] endPoint`	与事件关联的 TCP 端点。
`[in] isIdle`	如果 TCP 端点的发送通道为空闲，则为 true，否则为 false。

公共属性

OnAcceptError

OnAcceptErrorFunct OnAcceptError

端点的连接接受事件处理函数委托。

OnConnectComplete

OnConnectCompleteFunct OnConnectComplete

端点的连接建立事件处理函数委托。

OnConnectionClosed

OnConnectionClosedFunct OnConnectionClosed

端点的关闭事件处理函数委托。

OnConnectionReceived

OnConnectionReceivedFunct OnConnectionReceived

端点的连接接收事件处理函数委托。

OnDataReceived

OnDataReceivedFunct OnDataReceived

端点的消息文本接收事件处理函数委托。

OnDataSent

OnDataSentFunct OnDataSent

端点的消息文本传输事件处理函数委托。

OnPeerClose

OnPeerCloseFunct OnPeerClose

端点的半关闭接收事件处理函数委托。

OnTCPSendIdleChanged

OnTCPSendIdleChangedFunct OnTCPSendIdleChanged

端点的事件处理函数委托会在 TCP 连接的发送通道的空闲时间发生变化时发出信号。

上层利用此功能根据发送的数据是否已可靠地传送到对等端来采取适当的操作。

ReceiveEnabled

bool ReceiveEnabled

指示应用是否正在接收数据的控制开关。

状态

enum nl::Inet::TCPEndPoint::@10 State

底层端点的基本动态状态。

对象初始化为“就绪”状态，然后继续到后续状态，相应后续状态则是 TCP 传输状态机的简化状态。

公共函数

取消

void Abort(
  void
)

取消端点关闭，换言之，发送 RST 数据包。

AckReceive

INET_ERROR AckReceive(
  uint16_t len
)

确认收到消息文字。

使用此方法确认已收到全部或部分数据。如果 len 大于未确认的待处理数据总数，则未定义操作语义。

具体说明

参数

[in] len

要确认的字节数。

返回值

`INET_NO_ERROR`	成功：接收已确认。
`INET_ERROR_INCORRECT_STATE`	未建立 TCP 连接。
`INET_ERROR_CONNECTION_ABORTED`	TCP 连接已断开。

Bind

INET_ERROR Bind(
  IPAddressType addrType,
  IPAddress addr,
  uint16_t port,
  bool reuseAddr
)

将端点绑定到接口 IP 地址。

将端点绑定到指定的网络接口 IP 地址。

具体说明

参数

`[in] addrType`	IP 地址的协议版本
`[in] addr`	IP 地址（必须是接口地址）
`[in] port`	TCP 端口
`[in] reuseAddr`	用于与其他端点共享绑定的选项

返回值

`INET_NO_ERROR`	成功：端点绑定到地址
`INET_ERROR_INCORRECT_STATE`	端点之前已经绑定过
`INET_NO_MEMORY`	端点内存不足
`INET_ERROR_WRONG_PROTOCOL_TYPE`	“`addrType`”与“`IPVer`”不匹配。
`INET_ERROR_WRONG_ADDRESS_TYPE`	`addrType` 为 `kIPAddressType_Any`，或者 `addr` 的类型不等于 `addrType`。
`other`	其他系统或平台错误

在 LwIP 上，不得在已获取 LwIP 堆栈锁的情况下调用此方法。

关闭

INET_ERROR Close(
  void
)

启动 TCP 完全关闭，换言之，发送和接收均结束。

具体说明

返回值

`INET_NO_ERROR`	成功：已提取地址和端口。
`INET_ERROR_INCORRECT_STATE`	未建立 TCP 连接。
`other`	其他系统或平台错误

连接

INET_ERROR Connect(
  IPAddress addr,
  uint16_t port,
  InterfaceId intf
)

启动 TCP 连接。

 If possible, then this method initiates a TCP connection to the
 destination \c addr (with \c intf used as the scope
 identifier for IPv6 link-local destinations) and \c port.

具体说明

参数

`[in] addr`	目标 IP 地址
`[in] port`	目标 TCP 端口
`[in] intf`	可选的网络接口指示符

返回值

`INET_NO_ERROR`	如果成功：`msg` 已加入传输队列。
`INET_ERROR_NOT_IMPLEMENTED`	系统实施尚未完成。
`INET_ERROR_WRONG_ADDRESS_TYPE`	目标地址和绑定的接口地址没有匹配的协议版本或地址类型，或者目标地址是 IPv6 链路本地地址，并且未指定 `intf`。
`other`	其他系统或平台错误

DisableKeepAlive

INET_ERROR DisableKeepAlive(
  void
)

停用 TCP“keep-alive”选项。

TCPEndPoint::DisableKeepAlive。

对关联的 TCP 连接停用 TCP keepalive 探测。

具体说明

返回值

`INET_NO_ERROR`	成功：已提取地址和端口。
`INET_ERROR_INCORRECT_STATE`	未建立 TCP 连接。
`INET_ERROR_CONNECTION_ABORTED`	TCP 连接已断开。
`INET_ERROR_NOT_IMPLEMENTED`	系统实施尚未完成。
`other`	其他系统或平台错误

注意：仅当端点处于其中一种连接状态时，才能调用此方法。如果端点上尚未启用 keepalive，则此方法不会执行任何操作。

DisableReceive

void DisableReceive(
  void
)

停用信号接收。

停用所有事件处理脚本。发送到停用接收功能的端点的数据将得到确认，直到接收时段过去为止。

EnableKeepAlive

INET_ERROR EnableKeepAlive(
  uint16_t interval,
  uint16_t timeoutCount
)

启用 TCP“keep-alive”选项。

TCPEndPoint::EnableKeepAlive。

开始每 interval 秒自动传输一次 TCP“keep-alive”探测片段。收到负面响应或发送 timeoutCount 探测片段但未收到积极响应后，连接将自动取消。

具体说明

参数

`[in] interval`	探测请求之间的时间间隔（以秒为单位）。
`[in] timeoutCount`	超时前要发送的探测次数。

返回值

`INET_NO_ERROR`	成功：已提取地址和端口。
`INET_ERROR_INCORRECT_STATE`	未建立 TCP 连接。
`INET_ERROR_CONNECTION_ABORTED`	TCP 连接已断开。
`INET_ERROR_NOT_IMPLEMENTED`	系统实施尚未完成。
`other`	其他系统或平台错误

有关规范详情，请参阅 RFC 1122 第 4.2.3.6 节。

对关联的 TCP 连接启用 TCP keepalive 探测。

注意：仅当端点处于其中一种连接状态时，才能调用此方法。可以多次调用此方法来调整 keepalive 间隔或超时计数。

具体说明

参数

`interval`	keepalive 探测之间的时间间隔（以秒为单位）。此值还可控制从发送上一个数据包到传输第一个 keepalive 探测之间的时间。
`timeoutCount`	在连接被视为失败之前，未确认的探测次数上限。

EnableNoDelay

INET_ERROR EnableNoDelay(
  void
)

EnableNoDelay。

TCPEndPoint::EnableNoDelay。

通过设置 TCP_NODELAY 套接字选项，关闭 TCP 中的 Nagle 缓冲算法。

EnableReceive

void EnableReceive(
  void
)

启用信号接收。

启用所有事件处理脚本。发送到停用接收功能的端点的数据将得到确认，直到接收时段过去为止。

免费

void Free(
  void
)

启动（或继续）TCP 完全关闭，忽略错误。

该对象会被返回免费池，其余的所有用户引用随后都将失效。

GetLocalInfo

INET_ERROR GetLocalInfo(
  IPAddress *retAddr,
  uint16_t *retPort
)

提取本地端点的 IP 地址和 TCP 端口。

请勿为任一参数使用 NULL 指针值。

具体说明

参数

`[out] retAddr`	本地端点的 IP 地址。
`[out] retPort`	本地端点的 TCP 端口。

返回值

`INET_NO_ERROR`	成功：已提取地址和端口。
`INET_ERROR_INCORRECT_STATE`	未建立 TCP 连接。
`INET_ERROR_CONNECTION_ABORTED`	TCP 连接已断开。

GetPeerInfo

INET_ERROR GetPeerInfo(
  IPAddress *retAddr,
  uint16_t *retPort
) const

提取远程端点的 IP 地址和 TCP 端口。

请勿为任一参数使用 NULL 指针值。

具体说明

参数

`[out] retAddr`	远程端点的 IP 地址。
`[out] retPort`	远程端点的 TCP 端口。

返回值

`INET_NO_ERROR`	成功：已提取地址和端口。
`INET_ERROR_INCORRECT_STATE`	未建立 TCP 连接。
`INET_ERROR_CONNECTION_ABORTED`	TCP 连接已断开。

IsConnected

bool IsConnected(
  void
) const

提取是否建立 TCP 连接。

聆听

INET_ERROR Listen(
  uint16_t backlog
)

准备端点以接收 TCP 消息。

如果 State 已处于 kState_Listening 状态，则不执行任何操作；否则，State 将设置为 kState_Listening，并且端点会根据平台的语义准备好接收 TCP 消息。

具体说明

参数

[in] backlog

连接接受队列的最大深度

返回值

`INET_NO_ERROR`	成功：端点可以接收消息了。
`INET_ERROR_INCORRECT_STATE`	端点已经在监听。

在某些平台上，不会使用 backlog 参数（队列深度是固定的；一次只能接受一个连接）。

在 LwIP 系统上，不得在已获取 LwIP 堆栈锁的情况下调用此方法。

LogId

uint16_t LogId(
  void
)

获取端点的标识符。

具体说明
返回值	返回使用日志的不透明唯一标识符。

MarkActive

void MarkActive(
  void
)

记录活动，也就是重置闲置计时器。

将闲置计时器重置为零。

PendingReceiveLength

uint32_t PendingReceiveLength(
  void
)

提取未确认的接收数据的长度。

具体说明
返回值	接收队列中尚未通过 `AckReceive(uint16_t len)` 确认的字节数。

PendingSendLength

uint32_t PendingSendLength(
  void
)

提取等待首次传输的数据的长度。

具体说明
返回值	传输队列中未传输的字节数。

PutBackReceivedData

INET_ERROR PutBackReceivedData(
  Weave::System::PacketBuffer *data
)

将消息文本推送回接收队列的开头。

此方法只能由数据接收事件处理脚本调用，以便将未确认的数据部分放回接收队列中。如果调用方不在数据接收事件处理脚本的范围之内，data 不是提供给处理程序的 Weave::System::PacketBuffer，或者 data 不包含在先前调用 AckReceive(uint16_t len) 方法确认的字节之后剩余的未确认部分，则操作语义未定义。

具体说明

参数

[out] data

要推送的消息文本。

返回值

`INET_NO_ERROR`	成功：接收已确认。
`INET_ERROR_INCORRECT_STATE`	未建立 TCP 连接。

发送

INET_ERROR Send(
  Weave::System::PacketBuffer *data,
  bool push
)

通过 TCP 连接发送消息文本。

无论传输成功还是失败，都会对 data 参数调用 Weave::System::PacketBuffer::Free 方法。

具体说明

参数

`[out] data`	要发送的消息文字。
`[out] push`	如果为 `true`，则立即发送，否则排入队列。

返回值

`INET_NO_ERROR`	成功：已提取地址和端口。
`INET_ERROR_INCORRECT_STATE`	未建立 TCP 连接。

SetConnectTimeout

void SetConnectTimeout(
  const uint32_t connTimeoutMsecs
)

设置超时，以便连接成功或返回错误。

具体说明

参数

[in] connTimeoutMsecs

SetUserTimeout

INET_ERROR SetUserTimeout(
  uint32_t userTimeoutMillis
)

设置 TCP_USER_TIMEOUT 套接字选项。

TCPEndPoint::SetUserTimeout。

当该值大于 0 时，它指定了在 TCP 强制关闭相应连接之前传输数据可以保持未确认状态的最长时间（以毫秒为单位）。如果该选项的值被指定为 0，则 TCP 将使用系统默认值。如需了解详情，请参阅 RFC 5482。

具体说明

参数

[in] userTimeoutMillis

TCP 用户超时值（以毫秒为单位）。

返回值

`INET_NO_ERROR`	成功：已提取地址和端口。
`INET_ERROR_NOT_IMPLEMENTED`	系统实施尚未完成。
`other`	其他系统或平台错误

设置 TCP 用户超时套接字选项。

注意：仅当端点处于其中一种连接状态时，才能调用此方法。可以多次调用此方法来调整 keepalive 间隔或超时计数。

关停

INET_ERROR Shutdown(
  void
)

启动 TCP 半关闭，也就是完成发送。

具体说明

返回值

`INET_NO_ERROR`	成功：已提取地址和端口。
`INET_ERROR_INCORRECT_STATE`	未建立 TCP 连接。
`other`	其他系统或平台错误