TCP 抽象化

このモジュールには、ベース TCP API の上に使いやすい抽象化が含まれています。

概要

列挙型
anonymous enum enum
otTcpCircularSendBufferWrite に渡されるフラグを定義します。

Typedef
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 に渡されるフラグを定義します。

Typedef

otTcpCircularSendBuffer

struct otTcpCircularSendBuffer otTcpCircularSendBuffer

TCP エンドポイントで使用する循環送信バッファを表します。

循環送信バッファの使用は任意です。アプリケーションは、otLinkedBuffers を直接管理することで、TCP エンドポイントを使用してデータを送信できます。ただし、アプリケーションによっては、循環送信バッファを使用する方が便利である場合があります。このようなアプリケーションでは、otTcpCircularSendBufferWrite() を呼び出して循環送信バッファを TCP エンドポイントに「アタッチ」し、循環送信バッファを利用して基盤となる otLinkedBuffers に管理することで、その TCP エンドポイント上でデータを送信できます。

otTcpCircularSendBuffer は、otTcpEndpoint が提供する otLinkedBuffer ベースの API の上に実装されます。otTcpEndpoint に接続すると、otTcpCircularSendBuffer は接続の otLinkedBuffers を管理するすべての作業を実行します。つまり、otTcpCircularSendBuffer が otTcpEndpoint にアタッチされると、アプリケーションはその otTcpEndpoint で otTcpSendByReference() または otTcpSendByExtension() を呼び出してはならないということです。代わりに、アプリケーションは otTcpCircularSendBufferWrite() を使用して送信バッファにデータを追加する必要があります。

otTcpForwardProgress() コールバックは、循環送信バッファでスペースが利用可能になったときにユーザーに知らせるためのものです。otTcpCircularSendBuffer がアタッチされている otTcpEndpoint で、アプリは otTcpForwardProgress() コールバックをインストールし、コールバック関数の開始時に、アタッチされた otTcpCircularSendBuffer を呼び出さなければなりません。otLinkedBuffers の管理はすべて循環送信バッファによって処理されるため、otTcpSendDone() コールバックをインストールしないことをおすすめします。

アプリケーションは、この構造体のフィールドを直接検査しないでください。このファイル内で署名が提供される 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() を呼び出した場合や、otTcpConnectionLost() コールバックを介して接続のリセットが通知された場合など）は、アプリケーションはこの関数を呼び出すことが想定されています。

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）接続が終了する 2 つの方法で起こります。

推奨される使用パターンは、1 つの TCP エンドポイントで単一の TCP 循環送信バッファを使用し、その TCP 循環バッファだけを介しその TCP エンドポイント上でデータを送信することです。この推奨の使用パターンは、常に TCP エンドポイントと TCP 循環送信バッファを一緒に使用することで上記の問題を回避します。

循環送信バッファが容量に達すると、提供されたデータの接頭辞のみが循環送信バッファにコピーされます。

詳細
パラメータ
[in] aEndpoint
データを送信する TCP エンドポイント。
[in] aSendBuffer
データのコピー先となる TCP 循環送信バッファ。
[in] aData
TCP 循環送信バッファにコピーするデータへのポインタ。
[in] aLength
TCP 循環送信バッファにコピーする、aData でポイントされるデータの長さ。
[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 で入手できるソースコードに由来しています。 詳細について、またはドキュメントへの投稿については、リソースをご覧ください。