本頁面由 Cloud Translation API 翻譯而成。

nl::Inet::TCPEndPoint

#include <src/inet/TCPEndPoint.h>

這個類別的物件代表 TCP 傳輸端點。

摘要

Nest Inet Layer 會封裝與 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「保持運作」選項。
`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` 取得端點的 ID。
`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 連線不再開啟。

繫結

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「保持運作」選項。

TCPEndPoint::DisableKeepAlive。

在相關聯的 TCP 連線上停用 TCP 保持運作探測。

詳細說明

傳回值

`INET_NO_ERROR`	成功：已擷取位址和通訊埠。
`INET_ERROR_INCORRECT_STATE`	尚未建立 TCP 連線。
`INET_ERROR_CONNECTION_ABORTED`	TCP 連線不再開啟。
`INET_ERROR_NOT_IMPLEMENTED`	系統實作程序未完成
`other`	其他系統或平台錯誤

注意：只有在端點處於其中一種連線狀態時，才能呼叫這個方法。如果端點未啟用 Keepalives，這個方法就不會有任何作用。

DisableReceive

void DisableReceive(
  void
)

停用接收。

停用所有事件處理常式。如果資料傳送到停用接收的端點，在接收視窗用盡之前，我們會確認這些資料。

EnableKeepAlive

INET_ERROR EnableKeepAlive(
  uint16_t interval,
  uint16_t timeoutCount
)

啟用 TCP 的「keep-alive」選項。

TCPEndPoint::EnableKeepAlive。

每隔 interval 秒自動傳輸 TCP「保持運作」探測區段。收到負面回應後，或是在傳送 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 保持運作探測。

注意：只有在端點處於其中一種連線狀態時，才能呼叫這個方法。您可以多次呼叫此方法來調整保持運作間隔或逾時計數。

詳細說明

參數

`interval`	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
)

取得端點的 ID。

詳細說明
傳回	傳回使用記錄的不透明專屬 ID。

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 使用者逾時通訊端選項。

注意：只有在端點處於其中一種連線狀態時，才能呼叫這個方法。您可以多次呼叫此方法來調整保持運作間隔或逾時計數。

關機

INET_ERROR Shutdown(
  void
)

啟動 TCP 半關閉，也就是完成傳送。

詳細說明

傳回值

`INET_NO_ERROR`	成功：已擷取位址和通訊埠。
`INET_ERROR_INCORRECT_STATE`	尚未建立 TCP 連線。
`other`	其他系統或平台錯誤