# TCP Abstractions

This module includes easy-to-use abstractions on top of the base TCP API.

## Summary

| ### Enumerations ||
|---|---|
| `https://openthread.io/reference/group/api-tcp-ext#group__api-tcp-ext_1gaaf8fd5f0e57d456151c951e0f3715fc4` | enumDefines flags passed to `otTcpCircularSendBufferWrite`. |

| ### Typedefs ||
|---|---|
| `https://openthread.io/reference/group/api-tcp-ext#group__api-tcp-ext_1gab9cf6bb8274cd69c4f9a063ad2649570` | typedef `struct https://openthread.io/reference/struct/ot-tcp-circular-send-buffer` Represents a circular send buffer for use with a TCP endpoint. |
| `https://openthread.io/reference/group/api-tcp-ext#group__api-tcp-ext_1ga5ac717e2e18a711d5542b3f072e066c7` | typedef `struct https://openthread.io/reference/struct/ot-tcp-endpoint-and-circular-send-buffer` Context structure to use with mbedtls_ssl_set_bio. |

| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/api-tcp-ext#group__api-tcp-ext_1gaed0d77d0e7bc2dd90259848fbcdd951e(https://openthread.io/reference/struct/ot-tcp-circular-send-buffer *aSendBuffer)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Deinitializes a TCP circular send buffer, detaching it if attached. |
| `https://openthread.io/reference/group/api-tcp-ext#group__api-tcp-ext_1ga1e09b0ef5075e8a17680d6d18628f763(https://openthread.io/reference/struct/ot-tcp-circular-send-buffer *aSendBuffer)` | `void` Forcibly discards all data in the circular send buffer. |
| `https://openthread.io/reference/group/api-tcp-ext#group__api-tcp-ext_1gae0475620dc3a23841956d2f1869b1d01(const https://openthread.io/reference/struct/ot-tcp-circular-send-buffer *aSendBuffer)` | `size_t` Returns the amount of free space in the TCP circular send buffer. |
| `https://openthread.io/reference/group/api-tcp-ext#group__api-tcp-ext_1gae4634389a476f7f4db78bbc69bd00058(https://openthread.io/reference/struct/ot-tcp-circular-send-buffer *aSendBuffer, size_t aInSendBuffer)` | `void` Performs circular-send-buffer-specific handling in the otTcpForwardProgress callback. |
| `https://openthread.io/reference/group/api-tcp-ext#group__api-tcp-ext_1ga310570c09fd3ee8d5478cdb2aa835b37(https://openthread.io/reference/struct/ot-tcp-circular-send-buffer *aSendBuffer, void *aDataBuffer, size_t aCapacity)` | `void` Initializes a TCP circular send buffer. |
| `https://openthread.io/reference/group/api-tcp-ext#group__api-tcp-ext_1gad1a45cbf68b7d09cc5692a1ead5426f1(https://openthread.io/reference/struct/ot-tcp-endpoint *aEndpoint, https://openthread.io/reference/struct/ot-tcp-circular-send-buffer *aSendBuffer, const void *aData, size_t aLength, size_t *aWritten, uint32_t aFlags)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sends out data on a TCP endpoint, using the provided TCP circular send buffer to manage buffering. |
| `https://openthread.io/reference/group/api-tcp-ext#group__api-tcp-ext_1gaa0b979f36d268c7bd0398c82834f5098(void *aCtx, unsigned char *aBuf, size_t aLen)` | `int` Non-blocking receive callback to pass to mbedtls_ssl_set_bio. |
| `https://openthread.io/reference/group/api-tcp-ext#group__api-tcp-ext_1ga8efe8429d6e05c2c5dac8260c7810a29(void *aCtx, const unsigned char *aBuf, size_t aLen)` | `int` Non-blocking send callback to pass to mbedtls_ssl_set_bio. |

| ### Structs ||
|---|---|
| [otTcpCircularSendBuffer](https://openthread.io/reference/struct/ot-tcp-circular-send-buffer) | Represents a circular send buffer for use with a TCP endpoint. |
| [otTcpEndpointAndCircularSendBuffer](https://openthread.io/reference/struct/ot-tcp-endpoint-and-circular-send-buffer) | Context structure to use with mbedtls_ssl_set_bio. |

## Enumerations

### Anonymous Enum 23

```
 Anonymous Enum 23
```
Defines flags passed to `otTcpCircularSendBufferWrite`.

## Typedefs

### otTcpCircularSendBuffer

```
struct otTcpCircularSendBuffer otTcpCircularSendBuffer
```
Represents a circular send buffer for use with a TCP endpoint.

Using a circular send buffer is optional. Applications can use a TCP endpoint to send data by managing otLinkedBuffers directly. However, some applications may find it more convenient to have a circular send buffer; such applications can call [otTcpCircularSendBufferWrite()](https://openthread.io/reference/group/api-tcp-ext#group__api-tcp-ext_1gad1a45cbf68b7d09cc5692a1ead5426f1) to "attach" a circular send buffer to a TCP endpoint and send out data on that TCP endpoint, relying on the circular send buffer to manage the underlying otLinkedBuffers.

[otTcpCircularSendBuffer](https://openthread.io/reference/struct/ot-tcp-circular-send-buffer) is implemented on top of the otLinkedBuffer-based API provided by an [otTcpEndpoint](https://openthread.io/reference/struct/ot-tcp-endpoint). Once attached to an [otTcpEndpoint](https://openthread.io/reference/struct/ot-tcp-endpoint), an [otTcpCircularSendBuffer](https://openthread.io/reference/struct/ot-tcp-circular-send-buffer) performs all the work of managing otLinkedBuffers for the connection. This means that, once an [otTcpCircularSendBuffer](https://openthread.io/reference/struct/ot-tcp-circular-send-buffer) is attached to an [otTcpEndpoint](https://openthread.io/reference/struct/ot-tcp-endpoint), the application should not call [otTcpSendByReference()](https://openthread.io/reference/group/api-tcp#group__api-tcp_1gaa75f4bd44478f8a09a41b49544a96dfb) or [otTcpSendByExtension()](https://openthread.io/reference/group/api-tcp#group__api-tcp_1gaf4c8ad89d113b0b40778be6ca5d3cde8) on that [otTcpEndpoint](https://openthread.io/reference/struct/ot-tcp-endpoint). Instead, the application should use [otTcpCircularSendBufferWrite()](https://openthread.io/reference/group/api-tcp-ext#group__api-tcp-ext_1gad1a45cbf68b7d09cc5692a1ead5426f1) to add data to the send buffer.

The [otTcpForwardProgress()](https://openthread.io/reference/group/api-tcp#group__api-tcp_1ga69935ba978a5984e8b38b5fc8854c6fb) callback is the intended way for users to learn when space becomes available in the circular send buffer. On an [otTcpEndpoint](https://openthread.io/reference/struct/ot-tcp-endpoint) to which an [otTcpCircularSendBuffer](https://openthread.io/reference/struct/ot-tcp-circular-send-buffer) is attached, the application MUST install an [otTcpForwardProgress()](https://openthread.io/reference/group/api-tcp#group__api-tcp_1ga69935ba978a5984e8b38b5fc8854c6fb) callback and call [otTcpCircularSendBufferHandleForwardProgress()](https://openthread.io/reference/group/api-tcp-ext#group__api-tcp-ext_1gae4634389a476f7f4db78bbc69bd00058) on the attached [otTcpCircularSendBuffer](https://openthread.io/reference/struct/ot-tcp-circular-send-buffer) at the start of the callback function. It is recommended that the user NOT install an [otTcpSendDone()](https://openthread.io/reference/group/api-tcp#group__api-tcp_1gab49b3db0f5d27c85e72672468b6c425b) callback, as all management of otLinkedBuffers is handled by the circular send buffer.

The application should not inspect the fields of this structure directly; it should only interact with it via the TCP Circular Send Buffer API functions whose signature are provided in this file.

### otTcpEndpointAndCircularSendBuffer

```
struct otTcpEndpointAndCircularSendBuffer otTcpEndpointAndCircularSendBuffer
```
Context structure to use with mbedtls_ssl_set_bio.

## Functions

### otTcpCircularSendBufferDeinitialize

```
otError otTcpCircularSendBufferDeinitialize(
  otTcpCircularSendBuffer *aSendBuffer
)
```
Deinitializes a TCP circular send buffer, detaching it if attached.

If the TCP circular send buffer is not empty, then this operation will fail.

<br />

Details Parameters `[in] aSendBuffer` The TCP circular send buffer to deinitialize. Return Values `OT_ERROR_NONE` Successfully deinitialize the TCP circular send buffer. `OT_ERROR_BUSY` Circular buffer contains data and cannot be deinitialized.

### otTcpCircularSendBufferForceDiscardAll

```
void otTcpCircularSendBufferForceDiscardAll(
  otTcpCircularSendBuffer *aSendBuffer
)
```
Forcibly discards all data in the circular send buffer.

The application is expected to call this function when a TCP connection is terminated unceremoniously (e.g., if the application calls otTcpEndpointAbort() or is informed of a reset connection via the otTcpConnectionLost() callback).

Calling this function on a nonempty TCP circular send buffer attached to a TCP endpoint results in undefined behavior.

<br />

Details Parameters `[in] aSendBuffer` The TCP circular send buffer whose data to discard.

### otTcpCircularSendBufferGetFreeSpace

```
size_t otTcpCircularSendBufferGetFreeSpace(
  const otTcpCircularSendBuffer *aSendBuffer
)
```
Returns the amount of free space in the TCP circular send buffer.

This operation will always succeed.

<br />

Details Parameters `[in] aSendBuffer` A pointer to the TCP circular send buffer whose amount of free space to return. **Returns** The amount of free space in the send buffer.

### otTcpCircularSendBufferHandleForwardProgress

```
void otTcpCircularSendBufferHandleForwardProgress(
  otTcpCircularSendBuffer *aSendBuffer,
  size_t aInSendBuffer
)
```
Performs circular-send-buffer-specific handling in the otTcpForwardProgress callback.

The application is expected to install an [otTcpForwardProgress()](https://openthread.io/reference/group/api-tcp#group__api-tcp_1ga69935ba978a5984e8b38b5fc8854c6fb) callback on the [otTcpEndpoint](https://openthread.io/reference/struct/ot-tcp-endpoint), and call this function at the start of the callback function for circular-send-buffer-specific processing.

In the callback function, the application can determine the amount of free space in the circular send buffer by calling otTcpCircularSendBufferFreeSpace(), or by comparing `aInSendBuffer` with the send buffer's capacity, chosen by the user when calling [otTcpCircularSendBufferInitialize()](https://openthread.io/reference/group/api-tcp-ext#group__api-tcp-ext_1ga310570c09fd3ee8d5478cdb2aa835b37).

<br />

Details Parameters `[in] aSendBuffer` A pointer to the TCP circular send buffer for the endpoint for which [otTcpForwardProgress()](https://openthread.io/reference/group/api-tcp#group__api-tcp_1ga69935ba978a5984e8b38b5fc8854c6fb) was invoked. `[in] aInSendBuffer` Value of `aInSendBuffer` passed to the [otTcpForwardProgress()](https://openthread.io/reference/group/api-tcp#group__api-tcp_1ga69935ba978a5984e8b38b5fc8854c6fb) callback.

### otTcpCircularSendBufferInitialize

```
void otTcpCircularSendBufferInitialize(
  otTcpCircularSendBuffer *aSendBuffer,
  void *aDataBuffer,
  size_t aCapacity
)
```
Initializes a TCP circular send buffer.

<br />

Details Parameters `[in] aSendBuffer` A pointer to the TCP circular send buffer to initialize. `[in] aDataBuffer` A pointer to memory to use to store data in the TCP circular send buffer. `[in] aCapacity` The capacity, in bytes, of the TCP circular send buffer, which must equal the size of the memory pointed to by `aDataBuffer` .

### otTcpCircularSendBufferWrite

```
otError otTcpCircularSendBufferWrite(
  otTcpEndpoint *aEndpoint,
  otTcpCircularSendBuffer *aSendBuffer,
  const void *aData,
  size_t aLength,
  size_t *aWritten,
  uint32_t aFlags
)
```
Sends out data on a TCP endpoint, using the provided TCP circular send buffer to manage buffering.

Once this function is called, `aSendBuffer` and `aEndpoint` are considered "attached" to each other. While they are attached, ALL send operations for `aEndpoint` must be made using `aSendBuffer` and ALL operations on `aSendBuffer` must be associated with `aEndpoint` .

The only way to "detach" a TCP circular send buffer and a TCP endpoint is to wait for the send buffer to become completely empty. This can happen in two ways: (1) all data in the send buffer is sent and acknowledged in the normal course of TCP protocol operation, or (2) the connection is terminated.

The recommended usage pattern is to use a single TCP circular send buffer with a TCP endpoint, and to send data on that TCP endpoint only via its associated TCP circular buffer. This recommended usage pattern sidesteps the issues described above by always using a TCP endpoint and TCP circular send buffer together.

If the circular send buffer reaches capacity, only a prefix of the provided data is copied into the circular send buffer.

<br />

Details Parameters `[in] aEndpoint` The TCP endpoint on which to send out data. `[in] aSendBuffer` The TCP circular send buffer into which to copy data. `[in] aData` A pointer to data to copy into the TCP circular send buffer. `[in] aLength` The length of the data pointed to by `aData` to copy into the TCP circular send buffer. `[out] aWritten` Populated with the amount of data copied into the send buffer, which might be less than `aLength` if the send buffer reaches capacity. `[in] aFlags` Flags specifying options for this operation (see enumeration above). Return Values `OT_ERROR_NONE` Successfully copied data into the send buffer and sent it on the TCP endpoint. `OT_ERROR_FAILED` Failed to send out data on the TCP endpoint.

### otTcpMbedTlsSslRecvCallback

```
int otTcpMbedTlsSslRecvCallback(
  void *aCtx,
  unsigned char *aBuf,
  size_t aLen
)
```
Non-blocking receive callback to pass to mbedtls_ssl_set_bio.

<br />

Details Parameters `[in] aCtx` A pointer to an [otTcpEndpointAndCircularSendBuffer](https://openthread.io/reference/struct/ot-tcp-endpoint-and-circular-send-buffer). `[out] aBuf` The buffer into which to receive data. `[in] aLen` The maximum amount of data that can be received. **Returns** The number of bytes received, or an mbedtls error code.

### otTcpMbedTlsSslSendCallback

```
int otTcpMbedTlsSslSendCallback(
  void *aCtx,
  const unsigned char *aBuf,
  size_t aLen
)
```
Non-blocking send callback to pass to mbedtls_ssl_set_bio.

<br />

Details Parameters `[in] aCtx` A pointer to an [otTcpEndpointAndCircularSendBuffer](https://openthread.io/reference/struct/ot-tcp-endpoint-and-circular-send-buffer). `[in] aBuf` The data to add to the send buffer. `[in] aLen` The amount of data to add to the send buffer. **Returns** The number of bytes sent, or an mbedtls error code.

## Resources

OpenThread API Reference topics originate from the source code, available
on [GitHub](https://github.com/openthread/openthread/tree/main/include/openthread).
For more information, or to contribute to our documentation, refer to
[Resources](https://openthread.io/resources).