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

TCP 抽象化

這個模組包含基本 TCP API 頂端的易於使用抽象概念。

摘要

列舉
`anonymous enum`	列舉這個列舉項目定義了傳送至 `otTcpCircularSendBufferWrite` 的旗標。

Typedefs
`otTcpCircularSendBuffer`	typedef `struct otTcpCircularSendBuffer` 這個結構代表與 TCP 端點搭配使用的環狀傳送緩衝區。

Functions
`otTcpCircularSendBufferDeinitialize(otTcpCircularSendBuffer *aSendBuffer)`	`otError` 初始化 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)`	`otError` 在 TCP 端點上傳送資料，使用提供的 TCP 循環傳送緩衝區來管理緩衝區。

結構
otTcpCircularSendBuffer	這個結構代表與 TCP 端點搭配使用的環狀傳送緩衝區。

列舉

匿名列舉

 anonymous enum

這個列舉項目定義了傳送至 otTcpCircularSendBufferWrite 的旗標。

Typedefs

OTTcpCircularSendBuffer

struct otTcpCircularSendBuffer otTcpCircularSendBuffer

這個結構代表與 TCP 端點搭配使用的環狀傳送緩衝區。

您可以選擇使用循環傳送緩衝區。應用程式可以透過 TCP 端點，直接管理 otLinkedBuffers 來傳送資料。但是，部分應用程式認為使用環形傳送緩衝區可能更加方便；這類應用程式可以呼叫 otTcpCircularSendBufferWrite() 到「附加」環形傳送緩衝區，並透過 TCP 端點傳送出資料，並使用圓形傳送緩衝區來管理基礎 otLinkedBuffers。

otTcpCircularSendBuffer 是在 otTcpEndpoint 提供的 otLinkedBuffer 式 API 上實作。附加至 otTcpEndpoint 後，otTcpCircularSendBuffer 就會針對連線管理 otLinkedBuffers 作業。換句話說，在 otTcpEndpoint 上附加 otTcpCircularSendBuffer 後，應用程式不應在 otTcpEndpoint 上呼叫 otTcpSendByReference() 或 otTcpSendByExtension()。應用程式應使用 otTcpCircularSendBufferWrite() 將資料新增至傳送緩衝區。

otTcpForwardProgress() 回呼是用來讓使用者在環狀傳送緩衝區中取得空間時瞭解的適當方法。在附加 otTcpCircularSendBuffer 的 otTcpEndpoint 上，應用程式「必須」安裝 otTcpForwardProgress() 回呼，並在回呼函式的開頭使用附加的 otTcpCircularSendBuffer 呼叫 otTcpCircularSendBufferHandleForwardProgress()。建議使用者「不」安裝 otTcpSendDone() 回呼，因為 otLinkedBuffers 的所有管理作業都會由環狀傳送緩衝區處理。

應用程式不應直接檢查這個結構的欄位，而應該透過這個檔案中提供的簽章的 TCP Circular Send Buffer API 函式來與其互動。

Functions

otTcpCircularSendBufferDeInitial

otError otTcpCircularSendBufferDeinitialize(
  otTcpCircularSendBuffer *aSendBuffer
)

初始化 TCP 循環傳送緩衝區 (如附加的話)。

如果 TCP 循環傳送緩衝區沒有內容，則作業會失敗。

詳細資料

參數

[in] aSendBuffer

要初始化的 TCP 循環傳送緩衝區。

傳回值

`OT_ERROR_NONE`	已成功初始化 TCP 循環傳送緩衝區。
`OT_ERROR_BUSY`	循環緩衝區包含資料，且無法初始化。

otTcpCircularSendBufferForceDropAll

void otTcpCircularSendBufferForceDiscardAll(
  otTcpCircularSendBuffer *aSendBuffer
)

強制捨棄環形傳送緩衝區中的所有資料。

如果 TCP 連線無預警終止 (例如應用程式呼叫 otTcpEndpointAbort() 或透過 otTcpConnection Loss() 回呼告知重設連線)，應用程式預計會呼叫此函式。

在附加至 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` 指向的記憶體大小。

otTcpCircularSendBuffer 寫入

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) 在一般傳送緩衝區作業中，資料傳送和傳送的緩衝區資料已進行確認，或 (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 端點上傳送資料。

資源

OpenThread API 參考資料主題出自原始碼，可於 GitHub 取得。如需更多資訊，或想參閱我們的說明文件，請參閱資源。