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() 回呼的目的是讓使用者瞭解循環傳送緩衝區中是否有空間可用。在附加 otTcpCircularSendBufferotTcpEndpoint 上,應用程式必須安裝 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 端點傳送資料來管理緩衝。

呼叫此函式後,aSendBufferaEndpoint 會被視為「連接」。在附加時,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 取得。如要瞭解詳情或參與說明文件,請參閱資源