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 端點搭配使用的循環傳送緩衝區。

使用環形傳送緩衝區是選用項目。應用程式可透過 TCP 端點直接管理 otLinkedBuffers 來傳送資料。不過，某些應用程式可能會讓您更容易使用環狀傳送緩衝區；這類應用程式可以呼叫 otTcpCircularSendBufferWrite() 將環形傳送緩衝區「附加」到 TCP 端點，然後在該 TCP 端點上傳送資料，仰賴循環傳送緩衝區來管理基礎 otLinkedBuffers。

otTcpCircularSendBuffer 建構在 otTcpEndpoint 提供的 otLinkedBuffer 型 API 上。附加至 otTcpEndpoint 後，otTcpCircularSendBuffer 負責管理連線的 otLinkedBuffers。也就是說，otTcpCircularSendBuffer 附加至 otTcpEndpoint 後，應用程式就不應對該 otTcpEndpoint 呼叫 otTcpSendByReference() 或 otTcpSendByExtension()。應用程式應改用 otTcpCircularSendBufferWrite() 將資料新增至傳送緩衝區。

otTcpForwardProgress() 回呼是使用者，在圓形傳送緩衝區中何時可用空間。在已連結 otTcpCircularSendBuffer 的 otTcpEndpoint 上，於回呼函式開始時，在附加的 otTcpCircularSendBuffer建議使用者「不要」安裝 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()，或經由 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 指向的記憶體大小。

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 取得。如要瞭解詳情或對說明文件做出貢獻，請參閱資源。