Abstracciones de TCP

En este módulo, se incluyen abstracciones fáciles de usar además de la API de TCP básica.

Resumen

Enumeraciones
anonymous enum	enum Define las marcas que se pasan a otTcpCircularSendBufferWrite.

Typedefs
otTcpCircularSendBuffer	typedef struct otTcpCircularSendBuffer Representa un búfer de envío circular para usar con un extremo de TCP.
otTcpEndpointAndCircularSendBuffer	typedef struct otTcpEndpointAndCircularSendBuffer Estructura de contexto para usar con mbedtls_ssl_set_bio.

remotas
otTcpCircularSendBufferDeinitialize(otTcpCircularSendBuffer *aSendBuffer)	otError Anula la inicialización de un búfer de envío circular TCP y lo desconecta si está conectado.
otTcpCircularSendBufferForceDiscardAll(otTcpCircularSendBuffer *aSendBuffer)	void Descarta a la fuerza todos los datos del búfer de envío circular.
otTcpCircularSendBufferGetFreeSpace(const otTcpCircularSendBuffer *aSendBuffer)	size_t Muestra la cantidad de espacio libre en el búfer de envío circular de TCP.
otTcpCircularSendBufferHandleForwardProgress(otTcpCircularSendBuffer *aSendBuffer, size_t aInSendBuffer)	void Realiza el control específico de búfer de envío circular en la devolución de llamada otTcpForwardProgress.
otTcpCircularSendBufferInitialize(otTcpCircularSendBuffer *aSendBuffer, void *aDataBuffer, size_t aCapacity)	void Inicializa un búfer de envío circular TCP.
otTcpCircularSendBufferWrite(otTcpEndpoint *aEndpoint, otTcpCircularSendBuffer *aSendBuffer, const void *aData, size_t aLength, size_t *aWritten, uint32_t aFlags)	otError Envía datos en un extremo de TCP mediante el búfer de envío circular de TCP proporcionado para administrar el almacenamiento en búfer.
otTcpMbedTlsSslRecvCallback(void *aCtx, unsigned char *aBuf, size_t aLen)	int Sin bloqueo, reciben una devolución de llamada para pasar a mbedtls_ssl_set_bio.
otTcpMbedTlsSslSendCallback(void *aCtx, const unsigned char *aBuf, size_t aLen)	int Envía una devolución de llamada sin bloqueo para pasar a mbedtls_ssl_set_bio.

Structs
otTcpCircularSendBuffer	Representa un búfer de envío circular para usar con un extremo de TCP.
otTcpEndpointAndCircularSendBuffer	Estructura de contexto para usar con mbedtls_ssl_set_bio.

Enumeraciones

enumeración anónima

 anonymous enum

Define las marcas que se pasan a otTcpCircularSendBufferWrite.

Typedefs

otTcpCircularSendBuffer

struct otTcpCircularSendBuffer otTcpCircularSendBuffer

Representa un búfer de envío circular para usar con un extremo de TCP.

El uso de un búfer de envío circular es opcional. Las aplicaciones pueden usar un extremo TCP para enviar datos mediante la administración directa de otLinkedBuffers. Sin embargo, a algunas aplicaciones puede resultar más conveniente tener un búfer de envío circular. Esas aplicaciones pueden llamar a otTcpCircularSendBufferWrite() para "adjuntar" un búfer de envío circular a un extremo de TCP y enviar datos en ese extremo de TCP en función del búfer de envío circular para administrar el otLinkedBuffers subyacentes.

otTcpCircularSendBuffer se implementa sobre la API basada en otLinkedBuffer proporcionada por un otTcpEndpoint. Una vez que se conecta a un otTcpEndpoint, un otTcpCircularSendBuffer realiza todo el trabajo de administración de otLinkedBuffers para la conexión. Esto significa que, una vez que se adjunta un otTcpCircularSendBuffer a un otTcpEndpoint, la aplicación no debe llamar a otTcpSendByReference() ni a otTcpSendByExtension() en ese otTcpEndpoint. En su lugar, la aplicación debe usar otTcpCircularSendBufferWrite() para agregar datos al búfer de envío.

La devolución de llamada otTcpForwardProgress() es la manera prevista para que los usuarios sepan cuándo hay espacio disponible en el búfer de envío circular. En un otTcpEndpoint al que se adjunta un otTcpCircularSendBuffer, la aplicación DEBE instalar una devolución de llamada otTcpForwardProgress() y llamar a otTcpCircularSendBufferHandleForwardProgress() en el otTcpCircularSendBuffer adjunto al inicio de la función de devolución de llamada. Se recomienda que el usuario NO instale una devolución de llamada otTcpSendDone(), ya que toda la administración de otLinkedBuffers se controla a través del búfer de envío circular.

La aplicación no debe inspeccionar los campos de esta estructura directamente; solo debe interactuar con ella a través de las funciones de la API de TCP Circular Send Buffer cuya firma se proporciona en este archivo.

otTcpEndpointAndCircularSendBuffer

struct otTcpEndpointAndCircularSendBuffer otTcpEndpointAndCircularSendBuffer

Estructura de contexto para usar con mbedtls_ssl_set_bio.

remotas

otTcpCircularSendBufferDeinitialize

otError otTcpCircularSendBufferDeinitialize(
  otTcpCircularSendBuffer *aSendBuffer
)

Anula la inicialización de un búfer de envío circular TCP y lo desconecta si está conectado.

Si el búfer de envío circular TCP no está vacío, fallará esta operación.

Detalles
Parámetros	[in] aSendBuffer El búfer de envío circular de TCP que se desinicializar.
Valores que se muestran	OT_ERROR_NONE Se anuló correctamente la inicialización del búfer de envío circular de TCP. OT_ERROR_BUSY El búfer circular contiene datos y no se puede desinicializar.

otTcpCircularSendBufferForceDiscardAll

void otTcpCircularSendBufferForceDiscardAll(
  otTcpCircularSendBuffer *aSendBuffer
)

Descarta a la fuerza todos los datos del búfer de envío circular.

Se espera que la aplicación llame a esta función cuando se finaliza una conexión TCP de manera inceremoniosa (p.ej., si la aplicación llama a otTcpEndpointAbort() o se le informa de una conexión de restablecimiento a través de la devolución de llamada otTcpConnectionLost()).

Llamar a esta función en un búfer de envío circular TCP no vacío conectado a un extremo de TCP da como resultado un comportamiento indefinido.

Detalles
Parámetros	[in] aSendBuffer El búfer de envío circular de TCP cuyos datos se descartarán.

otTcpCircularSendBufferGetFreeSpace

size_t otTcpCircularSendBufferGetFreeSpace(
  const otTcpCircularSendBuffer *aSendBuffer
)

Muestra la cantidad de espacio libre en el búfer de envío circular de TCP.

Esta operación siempre se realizará de forma correcta.

Detalles
Parámetros	[in] aSendBuffer Un puntero al búfer de envío circular de TCP cuya cantidad de espacio libre se debe mostrar.
Qué muestra	Es la cantidad de espacio libre en el búfer de envío.

otTcpCircularSendBufferHandleForwardProgress

void otTcpCircularSendBufferHandleForwardProgress(
  otTcpCircularSendBuffer *aSendBuffer,
  size_t aInSendBuffer
)

Realiza el control específico de búfer de envío circular en la devolución de llamada otTcpForwardProgress.

Se espera que la aplicación instale una devolución de llamada otTcpForwardProgress() en el otTcpEndpoint y que llame a esta función al comienzo de la función de devolución de llamada para procesamiento específico del búfer de envío circular.

En la función de devolución de llamada, la aplicación puede determinar la cantidad de espacio libre en el búfer de envío circular llamando a otTcpCircularSendBufferFreeSpace() o comparando aInSendBuffer con la capacidad del búfer de envío que eligió el usuario cuando llama a otTcpCircularSendBufferInitialize().

Detalles
Parámetros	[in] aSendBuffer Un puntero al búfer de envío circular de TCP para el extremo para el que se invocó otTcpForwardProgress(). [in] aInSendBuffer El valor de aInSendBuffer se pasa a la devolución de llamada otTcpForwardProgress().

otTcpCircularSendBufferInitialize

void otTcpCircularSendBufferInitialize(
  otTcpCircularSendBuffer *aSendBuffer,
  void *aDataBuffer,
  size_t aCapacity
)

Inicializa un búfer de envío circular TCP.

Detalles
Parámetros	[in] aSendBuffer Un puntero al búfer de envío circular de TCP para inicializar. [in] aDataBuffer Un puntero a la memoria para almacenar datos en el búfer de envío circular TCP. [in] aCapacity La capacidad, en bytes, del búfer de envío circular de TCP, que debe ser igual al tamaño de la memoria a la que apunta aDataBuffer .

otTcpCircularSendBufferWrite

otError otTcpCircularSendBufferWrite(
  otTcpEndpoint *aEndpoint,
  otTcpCircularSendBuffer *aSendBuffer,
  const void *aData,
  size_t aLength,
  size_t *aWritten,
  uint32_t aFlags
)

Envía datos en un extremo de TCP mediante el búfer de envío circular de TCP proporcionado para administrar el almacenamiento en búfer.

Una vez que se llama a esta función, aSendBuffer y aEndpoint se consideran "vinculados" entre sí. Mientras estén adjuntos, TODAS las operaciones de envío de aEndpoint deben realizarse con aSendBuffer, y TODAS las operaciones de aSendBuffer deben asociarse con aEndpoint .

La única forma de “desconectar” un búfer de envío circular de TCP y un extremo de TCP es esperar a que el búfer de envío se vacíe por completo. Esto puede ocurrir de dos maneras: (1) todos los datos en el búfer de envío se envían y se confirman en el curso normal del funcionamiento del protocolo TCP, o (2) la conexión se finaliza.

El patrón de uso recomendado es utilizar un único búfer de envío circular de TCP con un extremo de TCP y enviar datos en ese extremo de TCP solo a través de su búfer circular de TCP asociado. Este patrón de uso recomendado evita los problemas descritos anteriormente, ya que siempre se usa un extremo de TCP y un búfer de envío circular TCP juntos.

Si el búfer de envío circular alcanza su capacidad, solo se copia en él un prefijo de los datos proporcionados.

Detalles
Parámetros	[in] aEndpoint El extremo TCP en el que se envían los datos. [in] aSendBuffer El búfer de envío circular de TCP en el que se copian los datos. [in] aData Un puntero a los datos que se copiarán en el búfer de envío circular de TCP. [in] aLength La longitud de los datos a los que hace referencia aData para copiar en el búfer de envío circular de TCP. [out] aWritten Se propaga con la cantidad de datos copiados en el búfer de envío, que podría ser inferior a aLength si el búfer de envío alcanza su capacidad. [in] aFlags Marcas que especifican opciones para esta operación (consulta la enumeración anterior).
Valores que se muestran	OT_ERROR_NONE Los datos se copiaron correctamente en el búfer de envío y se enviaron al extremo TCP. OT_ERROR_FAILED No se pudieron enviar los datos en el extremo TCP.

otTcpMbedTlsSslRecvCallback

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

Sin bloqueo, reciben una devolución de llamada para pasar a mbedtls_ssl_set_bio.

Detalles
Parámetros	[in] aCtx Un puntero para un otTcpEndpointAndCircularSendBuffer. [out] aBuf El búfer en el que se reciben los datos. [in] aLen La cantidad máxima de datos que se pueden recibir.
Qué muestra	La cantidad de bytes recibidos o un código de error mbedtls.

otTcpMbedTlsSslSendCallback

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

Envía una devolución de llamada sin bloqueo para pasar a mbedtls_ssl_set_bio.

Detalles
Parámetros	[in] aCtx Un puntero para un otTcpEndpointAndCircularSendBuffer. [in] aBuf Los datos que se agregarán al búfer de envío. [in] aLen Es la cantidad de datos que se agregarán al búfer de envío.
Qué muestra	La cantidad de bytes enviados o un código de error mbedtls.

Recursos

Los temas de referencia de la API de OpenThread se originan a partir del código fuente, disponible en GitHub. Para obtener más información o contribuir a nuestra documentación, consulta Recursos.