TCP 抽象層

這個模組在基本 TCP API 之上，提供簡單易用的抽象化機制。

摘要

列舉
anonymous enum 列舉
定義傳遞至 otTcpCircularSendBufferWrite 的旗標。

Typedefs
otTcpCircularSendBuffer typedef
代表與 TCP 端點搭配使用的循環傳送緩衝區。
otTcpEndpointAndCircularSendBuffer typedef
與 mbedtls_ssl_set_bio 搭配使用的結構定義結構。

函式
otTcpCircularSendBufferDeinitialize(otTcpCircularSendBuffer *aSendBuffer)
取消初始化 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)
使用所提供的 TCP 環狀傳送緩衝區，透過 TCP 端點傳送資料來管理緩衝。
otTcpMbedTlsSslRecvCallback(void *aCtx, unsigned char *aBuf, size_t aLen)
int
非封鎖功能的接收回呼會傳遞至 mbedtls_ssl_set_bio。
otTcpMbedTlsSslSendCallback(void *aCtx, const unsigned char *aBuf, size_t aLen)
int
非阻塞式傳送回呼以傳遞至 mbedtls_ssl_set_bio。

結構
otTcpCircularSendBuffer

代表與 TCP 端點搭配使用的循環傳送緩衝區。
otTcpEndpointAndCircularSendBuffer

與 mbedtls_ssl_set_bio 搭配使用的結構定義結構。

列舉

匿名列舉

 anonymous enum

定義傳遞至 otTcpCircularSendBufferWrite 的旗標。

Typedefs

otTcpCircularSendBuffer

struct otTcpCircularSendBuffer otTcpCircularSendBuffer

代表與 TCP 端點搭配使用的循環傳送緩衝區。

您可以選擇使用循環傳送緩衝區。應用程式可以直接管理 otLinkedBuffers，藉此使用 TCP 端點傳送資料。不過，有些應用程式可能比較方便使用循環傳送緩衝區；這類應用程式可以呼叫 otTcpCircularSendBufferWrite() 以將環狀傳送緩衝區「附加」到 TCP 端點，並透過該 TCP 端點傳送資料，並透過循環傳送緩衝區管理基礎 otLinkedBuffers。

otTcpCircularSendBuffer 是在 otTcpEndpoint 提供的 otLinkedBuffer 式 API 之上。附加至 otTcpEndpoint 後，otTcpCircularSendBuffer 會執行為連線管理 otLinkedBuffers 的所有工作。也就是說，將 otTcpCircularSendBuffer 附加至 otTcpEndpoint 後，應用程式就不得在該 otTcpEndpoint 上呼叫 otTcpSendByReference() 或 otTcpSendByExtension()。而應用程式應改用 otTcpCircularSendBufferWrite() 將資料新增至傳送緩衝區。

otTcpForwardProgress() 回呼的目的是讓使用者瞭解循環傳送緩衝區中是否有空間可用。在附加 otTcpCircularSendBuffer 的 otTcpEndpoint 上，應用程式必須安裝 otTcpForwardProgress() 回呼，並在附加的 otTcpCircularSendBuffer 時呼叫 otTcpCircularSendBufferHandleForwardProgress()。建議使用者「不要」安裝 otTcpSendDone() 回呼，因為 otLinkedBuffers 的所有管理作業都是由環形傳送緩衝區處理。

應用程式不應直接檢查這個結構的欄位；只能透過 TCP Circular Send Buffer API 函式 (該檔案內含簽章) 與這個結構互動。

otTcpEndpointAndCircularSendBuffer

struct otTcpEndpointAndCircularSendBuffer otTcpEndpointAndCircularSendBuffer

與 mbedtls_ssl_set_bio 搭配使用的結構定義結構。

函式

otTcpCircularSendBufferDeinitialize

otError otTcpCircularSendBufferDeinitialize(
  otTcpCircularSendBuffer *aSendBuffer
)

取消初始化 TCP 循環傳送緩衝區，如果附加的話，卸離該緩衝區。

如果 TCP 環狀傳送緩衝區不是空白，這項作業就會失敗。

詳細說明
參數
[in] aSendBuffer
要取消初始化的 TCP 循環傳送緩衝區。
傳回值
OT_ERROR_NONE
成功取消初始化 TCP 環狀傳送緩衝區。
OT_ERROR_BUSY
圓形緩衝區包含資料，無法取消初始化。

otTcpCircularSendBufferForceDiscardAll

void otTcpCircularSendBufferForceDiscardAll(
  otTcpCircularSendBuffer *aSendBuffer
)

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

當 TCP 連線不正常終止時 (例如，應用程式呼叫 otTcpEndpointAbort()，或透過 otTcpConnectionConnected() 回呼收到已重設的連線)，即應呼叫此函式。

在連接至 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 指向的記憶體大小。

otTcpCircularSendBufferWrite

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) 在一般的 TCP 通訊協定作業過程中，傳送及確認傳送緩衝區中的所有資料，或 (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 端點傳送資料。

otTcpMbedTlsSslRecvCallback

int otTcpMbedTlsSslRecvCallback(
  void *aCtx,
  unsigned char *aBuf,
  size_t aLen
)

非封鎖功能的接收回呼會傳遞至 mbedtls_ssl_set_bio。

詳細說明
參數
[in] aCtx
[out] aBuf
接收資料的緩衝區。
[in] aLen
接收的資料量上限。
傳回
收到的位元組數，或 mbedtls 錯誤代碼。

otTcpMbedTlsSslSendCallback

int otTcpMbedTlsSslSendCallback(
  void *aCtx,
  const unsigned char *aBuf,
  size_t aLen
)

非阻塞式傳送回呼以傳遞至 mbedtls_ssl_set_bio。

詳細說明
參數
[in] aCtx
[in] aBuf
要新增至傳送緩衝區的資料。
[in] aLen
要新增至傳送緩衝區的資料量。
傳回
傳送的位元組數，或 mbedtls 錯誤代碼。

資源

源自原始碼的 OpenThread API 參考資料主題，可在 GitHub 取得。如要瞭解詳情或參與說明文件，請參閱資源。