TCP-абстракции

Этот модуль включает простые в использовании абстракции поверх базового TCP API.

Краткое содержание

Перечисления

anonymous enum перечисление
Определяет флаги, передаваемые в otTcpCircularSendBufferWrite .

Определения типов

otTcpCircularSendBuffer определение типа
Представляет циклический буфер отправки для использования с конечной точкой TCP.
otTcpEndpointAndCircularSendBuffer определение типа
Структура контекста для использования с 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 .

Определения типов

otTcpCircularSendBuffer

struct otTcpCircularSendBuffer otTcpCircularSendBuffer

Представляет циклический буфер отправки для использования с конечной точкой TCP.

Использование циклического буфера отправки не является обязательным. Приложения могут использовать конечную точку TCP для отправки данных, напрямую управляя otLinkedBuffers. Однако некоторым приложениям может оказаться более удобным иметь циклический буфер отправки; такие приложения могут вызывать otTcpCircularSendBufferWrite() , чтобы «присоединить» циклический буфер отправки к конечной точке TCP и отправлять данные на эту конечную точку TCP, полагаясь на циклический буфер отправки для управления базовыми otLinkedBuffers.

otTcpCircularSendBuffer реализован поверх API на основе otLinkedBuffer, предоставляемого otTcpEndpoint . После присоединения к otTcpEndpoint otTcpCircularSendBuffer выполняет всю работу по управлению otLinkedBuffers для соединения. Это означает, что после присоединения otTcpCircularSendBuffer к otTcpEndpoint приложение не должно вызывать otTcpSendByReference() или otTcpSendByExtension() для этого otTcpEndpoint . Вместо этого приложение должно использовать otTcpCircularSendBufferWrite() для добавления данных в буфер отправки.

Обратный вызов otTcpForwardProgress() — это предназначенный для пользователей способ узнать, когда в циклическом буфере отправки появится свободное место. В точке otTcpEndpoint , к которой подключен otTcpCircularSendBuffer , приложение ДОЛЖНО установить обратный вызов otTcpForwardProgress() и вызвать otTcpCircularSendBufferHandleForwardProgress() для присоединенного otTcpCircularSendBuffer в начале функции обратного вызова. Пользователю НЕ рекомендуется устанавливать обратный вызов otTcpSendDone() , поскольку все управление otLinkedBuffers осуществляется циклическим буфером отправки.

Приложение не должно проверять поля этой структуры напрямую; он должен взаимодействовать с ним только через функции API TCP Circular Send Buffer, подпись которых представлена ​​в этом файле.

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.

Ожидается, что приложение установит обратный вызов otTcpForwardProgress() в otTcpEndpoint и вызовет эту функцию в начале функции обратного вызова для обработки, специфичной для буфера циклической отправки.

В функции обратного вызова приложение может определить объем свободного места в циклическом буфере отправки, вызвав otTcpCircularSendBufferFreeSpace() или сравнив aInSendBuffer с емкостью буфера отправки, выбранной пользователем при вызове otTcpCircularSendBufferInitialize() .

Подробности
Параметры
[in] aSendBuffer
Указатель на циклический буфер отправки TCP для конечной точки, для которой была вызвана otTcpForwardProgress() .
[in] aInSendBuffer
Значение aInSendBuffer передается в обратный вызов otTcpForwardProgress() .

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
Указатель на otTcpEndpointAndCircularSendBuffer .
[out] aBuf
Буфер, в который принимаются данные.
[in] aLen
Максимальный объем данных, который можно получить.
Возврат
Количество полученных байтов или код ошибки mbedtls.

otTcpMbedTlsSslSendCallback

int otTcpMbedTlsSslSendCallback(
  void *aCtx,
  const unsigned char *aBuf,
  size_t aLen
)

Неблокирующий обратный вызов отправки для передачи в mbedtls_ssl_set_bio.

Подробности
Параметры
[in] aCtx
Указатель на otTcpEndpointAndCircularSendBuffer .
[in] aBuf
Данные, которые нужно добавить в буфер отправки.
[in] aLen
Объем данных, добавляемых в буфер отправки.
Возврат
Количество отправленных байтов или код ошибки mbedtls.

Ресурсы

Справочные разделы API OpenThread взяты из исходного кода, доступного на GitHub . Для получения дополнительной информации или внесения вклада в нашу документацию обратитесь к Ресурсам .