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 }	列舉 定義連入連線動作。

Typedefs
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 3 向握手已完成，並已建立連線。
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	拒絕連入連線。

Typedefs

otLinkedBuffer

struct otLinkedBuffer otLinkedBuffer

已連結的緩衝區結構，可與 TCP 搭配使用。

單一 otLinkedBuffer 結構會透過 mData 和 mLength 參照記憶體中的位元組陣列。mNext 欄位可用來形成 otLinkedBuffer 結構的鏈結。

otTcpAcceptDone

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

這個回呼表示 TCP 連線已準備好進行雙向通訊。

如果是 TCP 快速開啟，這可能在 TCP 連線握手實際完成之前。應用程式會提供結構定義指標，包括接受連線的 TCP 事件監聽器，以及其接受的 TCP 端點。提供的結構定義與 TCP 事件監聽器相關聯。

詳細說明
參數	[in] aListener 與傳入連線相符的 TCP 事件監聽器。 [in] aEndpoint 接受傳入連線的 TCP 端點。 [in] aPeer 傳入連線的主機和通訊埠。

otTcpAcceptReady

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

這個回呼表示與這個 TCP 事件監聽器相符的連入連線已抵達。

一般的回應是讓應用程式接受傳入的連線。方法是填入 aAcceptInto，並指向接受傳入連線的 otTcpEndpoint。這個 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 3 向握手已完成，並已建立連線。

詳細說明
參數	[in] aEndpoint 建立連線的 TCP 端點。

otTcpForwardProgress

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

如果從傳送緩衝區將資料從傳送緩衝區轉移到接收端，此回呼會通知應用程式。

這個回呼不需要用於正確的 TCP 作業。大多數應用程式只要運用 otTcpSendDone() 回呼，即可在 TCP 堆疊使用完畢之後，收回已連結的緩衝區。這個回呼的用途是支援進階應用程式，以便從更精細的資訊中瞭解連線如何順利將資料轉移至連線對等點。

這個回呼的作業與 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 快速開啟功能。如果停用此選項，系統會立即啟動 TCP 連線建立握手程序。如果啟用，則此函式只會記錄遠端主機和通訊埠，而且只會在第一次呼叫 otTcpSendByReference() 時執行 TCP 連線建立握手作業。

如果「TCP 快速開啟」已停用，呼叫端必須等待 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 堆疊所擁有；在「傳送已完成」回呼將這些物件的擁有權傳回應用程式之前，應用程式不應修改這些物件。您可以呼叫此函式在傳送佇列中新增另一個連結的緩衝區，即使先前叫用此函式的「傳送已完成」回呼尚未觸發亦然。

請注意，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 實作中會視為 struct 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 中的 struct tcpcb_listen 相同。

這是必要的，因為雖然其宣告中的 mTcbListen 欄位為不透明，但在 TCP 實作中會視為 struct 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 取得。如要瞭解詳情或對說明文件做出貢獻，請參閱資源。