TCP 抽象層
這個模組在基本 TCP API 之上,提供簡單易用的抽象化機制。
摘要
列舉 |
|
---|---|
anonymous enum
|
列舉 定義傳遞至 otTcpCircularSendBufferWrite 的旗標。 |
Typedefs |
|
---|---|
otTcpCircularSendBuffer
|
typedefstruct otTcpCircularSendBuffer
代表與 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 環狀傳送緩衝區不是空白,這項作業就會失敗。
詳細說明 | |||||
---|---|---|---|---|---|
參數 |
|
||||
傳回值 |
|
otTcpCircularSendBufferForceDiscardAll
void otTcpCircularSendBufferForceDiscardAll( otTcpCircularSendBuffer *aSendBuffer )
強制捨棄環形傳送緩衝區中的所有資料。
當 TCP 連線不正常終止時 (例如,應用程式呼叫 otTcpEndpointAbort(),或透過 otTcpConnectionConnected() 回呼收到已重設的連線),即應呼叫此函式。
在連接至 TCP 端點的非空白 TCP 循環傳送緩衝區上呼叫此函式會產生未定義的行為。
詳細說明 | |||
---|---|---|---|
參數 |
|
otTcpCircularSendBufferGetFreeSpace
size_t otTcpCircularSendBufferGetFreeSpace( const otTcpCircularSendBuffer *aSendBuffer )
傳回 TCP 環形傳送緩衝區中的可用空間量。
這項作業一定會成功。
詳細說明 | |||
---|---|---|---|
參數 |
|
||
傳回 |
傳送緩衝區中的可用空間。
|
otTcpCircularSendBufferHandleForwardProgress
void otTcpCircularSendBufferHandleForwardProgress( otTcpCircularSendBuffer *aSendBuffer, size_t aInSendBuffer )
在 otTcpForwardProgress 回呼中執行循環傳送緩衝區特定處理作業。
應用程式應在 otTcpEndpoint 上安裝 otTcpForwardProgress() 回呼,並在回呼函式的開頭呼叫此函式,以便進行循環傳送緩衝區特定處理作業。
在回呼函式中,應用程式可以呼叫 otTcpCircularSendBufferFreeSpace(),或比較 aInSendBuffer
與傳送緩衝區的容量 (在呼叫 otTcpCircularSendBufferInitialize() 時選擇的傳送緩衝區空間),決定圓形傳送緩衝區中的可用空間。
詳細說明 | |||||
---|---|---|---|---|---|
參數 |
|
otTcpCircularSendBufferInitialize
void otTcpCircularSendBufferInitialize( otTcpCircularSendBuffer *aSendBuffer, void *aDataBuffer, size_t aCapacity )
初始化 TCP 循環傳送緩衝區。
詳細說明 | |||||||
---|---|---|---|---|---|---|---|
參數 |
|
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 環狀傳送緩衝區。
如果循環傳送緩衝區達到容量上限,所提供資料的前置字串只會複製到循環傳送緩衝區。
詳細說明 | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
參數 |
|
||||||||||||
傳回值 |
|
otTcpMbedTlsSslRecvCallback
int otTcpMbedTlsSslRecvCallback( void *aCtx, unsigned char *aBuf, size_t aLen )
非封鎖功能的接收回呼會傳遞至 mbedtls_ssl_set_bio。
詳細說明 | |||||||
---|---|---|---|---|---|---|---|
參數 |
|
||||||
傳回 |
收到的位元組數,或 mbedtls 錯誤代碼。
|
otTcpMbedTlsSslSendCallback
int otTcpMbedTlsSslSendCallback( void *aCtx, const unsigned char *aBuf, size_t aLen )
非阻塞式傳送回呼以傳遞至 mbedtls_ssl_set_bio。
詳細說明 | |||||||
---|---|---|---|---|---|---|---|
參數 |
|
||||||
傳回 |
傳送的位元組數,或 mbedtls 錯誤代碼。
|
資源
源自原始碼的 OpenThread API 參考資料主題,可在 GitHub 取得。如要瞭解詳情或參與說明文件,請參閱資源。