Abstractions TCP

Ce module inclut des abstractions faciles à utiliser en plus de l'API TCP de base.

Résumé

Énumérations
anonymous enum enum
Définit les indicateurs transmis à otTcpCircularSendBufferWrite.

Typedefs
otTcpCircularSendBuffer typedef
Représente un tampon d'envoi circulaire à utiliser avec un point de terminaison TCP.
otTcpEndpointAndCircularSendBuffer typedef
Structure de contexte à utiliser avec mbedtls_ssl_set_bio.

distantes
otTcpCircularSendBufferDeinitialize(otTcpCircularSendBuffer *aSendBuffer)
Désinitialise un tampon d'envoi circulaire TCP et le dissocie s'il est associé.
otTcpCircularSendBufferForceDiscardAll(otTcpCircularSendBuffer *aSendBuffer)
void
Elle supprime de force toutes les données du tampon d'envoi circulaire.
otTcpCircularSendBufferGetFreeSpace(const otTcpCircularSendBuffer *aSendBuffer)
size_t
Renvoie la quantité d'espace disponible dans le tampon d'envoi circulaire TCP.
otTcpCircularSendBufferHandleForwardProgress(otTcpCircularSendBuffer *aSendBuffer, size_t aInSendBuffer)
void
Effectue un traitement spécifique au tampon d'envoi circulaire dans le rappel otTcpForwardProgress.
otTcpCircularSendBufferInitialize(otTcpCircularSendBuffer *aSendBuffer, void *aDataBuffer, size_t aCapacity)
void
Initialise un tampon d'envoi circulaire TCP.
otTcpCircularSendBufferWrite(otTcpEndpoint *aEndpoint, otTcpCircularSendBuffer *aSendBuffer, const void *aData, size_t aLength, size_t *aWritten, uint32_t aFlags)
Envoie des données sur un point de terminaison TCP à l'aide du tampon d'envoi circulaire TCP fourni pour gérer la mise en mémoire tampon.
otTcpMbedTlsSslRecvCallback(void *aCtx, unsigned char *aBuf, size_t aLen)
int
Rappel de réception non bloquant à transmettre à mbedtls_ssl_set_bio.
otTcpMbedTlsSslSendCallback(void *aCtx, const unsigned char *aBuf, size_t aLen)
int
Envoi non bloquant d'un rappel à transmettre à mbedtls_ssl_set_bio.

Structs
otTcpCircularSendBuffer

Représente un tampon d'envoi circulaire à utiliser avec un point de terminaison TCP.

otTcpEndpointAndCircularSendBuffer

Structure de contexte à utiliser avec mbedtls_ssl_set_bio.

Énumérations

énumération anonyme

 anonymous enum

Définit les indicateurs transmis à otTcpCircularSendBufferWrite.

Typedefs

otTcpCircularSendBuffer

struct otTcpCircularSendBuffer otTcpCircularSendBuffer

Représente un tampon d'envoi circulaire à utiliser avec un point de terminaison TCP.

L'utilisation d'un tampon d'envoi circulaire est facultative. Les applications peuvent utiliser un point de terminaison TCP pour envoyer des données en gérant directement otLinkedBuffers. Cependant, certaines applications peuvent trouver plus pratique d'avoir un tampon d'envoi circulaire ; elles peuvent appeler otTcpCircularSendBufferWrite() pour "associer" un tampon d'envoi circulaire à un point de terminaison TCP et envoyer des données sur ce point de terminaison TCP, en s'appuyant sur le tampon d'envoi circulaire pour gérer les otLinkedBuffers sous-jacents.

otTcpCircularSendBuffer est implémenté sur l'API basée sur otLinkedBuffer fournie par un otTcpEndpoint. Une fois associé à un otTcpEndpoint, un otTcpCircularSendBuffer effectue toutes les tâches de gestion des otLinkedBuffers pour la connexion. Cela signifie que, une fois qu'un otTcpCircularSendBuffer est associé à un otTcpEndpoint, l'application ne doit pas appeler otTcpSendByReference() ou otTcpSendByExtension() sur cet otTcpEndpoint. L'application doit utiliser otTcpCircularSendBufferWrite() pour ajouter des données au tampon d'envoi.

Le rappel otTcpForwardProgress() est destiné aux utilisateurs pour savoir quand de l'espace devient disponible dans le tampon d'envoi circulaire. Sur un otTcpEndpoint auquel est associé un otTcpCircularSendBuffer, l'application DOIT installer un rappel otTcpForwardProgress() et appeler otTcpCircularSendBufferHandleForwardProgress() sur l'otTcpCircularSendBuffer associé au début de la fonction de rappel. Il est recommandé à l'utilisateur de NE PAS installer de rappel otTcpSendDone(), car toute la gestion de otLinkedBuffers est gérée par le tampon d'envoi circulaire.

L'application ne doit pas inspecter directement les champs de cette structure. Elle ne doit interagir avec elle que via les fonctions de l'API TCP Circular Send Buffer dont la signature est fournie dans ce fichier.

otTcpEndpointAndCircularSendBuffer

struct otTcpEndpointAndCircularSendBuffer otTcpEndpointAndCircularSendBuffer

Structure de contexte à utiliser avec mbedtls_ssl_set_bio.

distantes

otTcpCircularSendBufferDeinitialize

otError otTcpCircularSendBufferDeinitialize(
  otTcpCircularSendBuffer *aSendBuffer
)

Désinitialise un tampon d'envoi circulaire TCP et le dissocie s'il est associé.

Si le tampon d'envoi circulaire TCP n'est pas vide, cette opération échouera.

Détails
Paramètres
[in] aSendBuffer
Tampon d'envoi circulaire TCP à déinitialiser.
Valeurs de retour
OT_ERROR_NONE
L'initialisation du tampon d'envoi circulaire TCP a bien été annulée.
OT_ERROR_BUSY
Le tampon circulaire contient des données et ne peut pas être désinitialisé.

otTcpCircularSendBufferForceDiscardAll

void otTcpCircularSendBufferForceDiscardAll(
  otTcpCircularSendBuffer *aSendBuffer
)

Elle supprime de force toutes les données du tampon d'envoi circulaire.

L'application doit appeler cette fonction lorsqu'une connexion TCP est interrompue de manière non cérémonie (par exemple, si l'application appelle otTcpEndpointAbort() ou est informée d'une réinitialisation de connexion via le rappel otTcpConnectionLost()).

L'appel de cette fonction sur un tampon d'envoi circulaire TCP non vide associé à un point de terminaison TCP entraîne un comportement indéfini.

Détails
Paramètres
[in] aSendBuffer
Tampon d'envoi circulaire TCP dont les données doivent être supprimées.

otTcpCircularSendBufferGetFreeSpace

size_t otTcpCircularSendBufferGetFreeSpace(
  const otTcpCircularSendBuffer *aSendBuffer
)

Renvoie la quantité d'espace disponible dans le tampon d'envoi circulaire TCP.

Cette opération aboutit toujours.

Détails
Paramètres
[in] aSendBuffer
Pointeur vers le tampon d'envoi circulaire TCP dont la quantité d'espace libre à renvoyer.
Renvoie
Quantité d'espace disponible dans le tampon d'envoi.

otTcpCircularSendBufferHandleForwardProgress

void otTcpCircularSendBufferHandleForwardProgress(
  otTcpCircularSendBuffer *aSendBuffer,
  size_t aInSendBuffer
)

Effectue un traitement spécifique au tampon d'envoi circulaire dans le rappel otTcpForwardProgress.

L'application doit installer un rappel otTcpForwardProgress() sur le otTcpEndpoint et appeler cette fonction au début de la fonction de rappel pour un traitement spécifique au tampon d'envoi circulaire.

Dans la fonction de rappel, l'application peut déterminer la quantité d'espace libre dans le tampon d'envoi circulaire en appelant otTcpCircularSendBufferFreeSpace() ou en comparant aInSendBuffer avec la capacité du tampon d'envoi, choisie par l'utilisateur lors de l'appel de otTcpCircularSendBufferInitialize().

Détails
Paramètres
[in] aSendBuffer
Pointeur vers le tampon d'envoi circulaire TCP pour le point de terminaison pour lequel otTcpForwardProgress() a été appelé.
[in] aInSendBuffer
Valeur de aInSendBuffer transmise au rappel otTcpForwardProgress().

otTcpCircularSendBufferInitialize

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

Initialise un tampon d'envoi circulaire TCP.

Détails
Paramètres
[in] aSendBuffer
Pointeur vers le tampon d'envoi circulaire TCP à initialiser.
[in] aDataBuffer
Pointeur vers la mémoire à utiliser pour stocker des données dans le tampon d'envoi circulaire TCP.
[in] aCapacity
Capacité, en octets, du tampon d'envoi circulaire TCP, qui doit être égale à la taille de la mémoire vers laquelle pointe aDataBuffer .

otTcpCircularSendBufferWrite

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

Envoie des données sur un point de terminaison TCP à l'aide du tampon d'envoi circulaire TCP fourni pour gérer la mise en mémoire tampon.

Une fois cette fonction appelée, aSendBuffer et aEndpoint sont considérés comme "associés" l'un à l'autre. Lorsqu'elles sont associées, TOUTES les opérations d'envoi pour aEndpoint doivent être effectuées à l'aide de aSendBuffer, et TOUTES les opérations sur aSendBuffer doivent être associées à aEndpoint .

Le seul moyen de "dissocier" un tampon d'envoi circulaire TCP et un point de terminaison TCP consiste à attendre que le tampon d'envoi devienne complètement vide. Cela peut se produire de deux manières: (1) toutes les données du tampon d'envoi sont envoyées et confirmées dans le cadre du fonctionnement normal du protocole TCP, ou (2) la connexion est interrompue.

Le modèle d'utilisation recommandé consiste à utiliser un seul tampon d'envoi circulaire TCP avec un point de terminaison TCP et à n'envoyer des données sur ce point de terminaison TCP que via le tampon circulaire TCP associé. Ce modèle d'utilisation recommandé permet d'éviter les problèmes décrits ci-dessus en utilisant toujours un point de terminaison TCP et un tampon d'envoi circulaire TCP.

Si le tampon d'envoi circulaire atteint sa capacité maximale, seul un préfixe des données fournies est copié dans le tampon d'envoi circulaire.

Détails
Paramètres
[in] aEndpoint
Point de terminaison TCP sur lequel envoyer des données.
[in] aSendBuffer
Tampon d'envoi circulaire TCP dans lequel copier les données.
[in] aData
Pointeur vers les données à copier dans le tampon d'envoi circulaire TCP.
[in] aLength
Longueur des données indiquées par aData à copier dans le tampon d'envoi circulaire TCP.
[out] aWritten
Renseigné avec la quantité de données copiées dans le tampon d'envoi, qui peut être inférieure à aLength si le tampon d'envoi atteint sa capacité maximale.
[in] aFlags
Indicateurs spécifiant les options pour cette opération (voir l'énumération ci-dessus).
Valeurs de retour
OT_ERROR_NONE
Les données ont bien été copiées dans le tampon d'envoi et envoyées au point de terminaison TCP.
OT_ERROR_FAILED
Échec de l'envoi des données sur le point de terminaison TCP.

otTcpMbedTlsSslRecvCallback

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

Rappel de réception non bloquant à transmettre à mbedtls_ssl_set_bio.

Détails
Paramètres
[in] aCtx
Pointeur vers un objet otTcpEndpointAndCircularSendBuffer.
[out] aBuf
Tampon dans lequel recevoir les données.
[in] aLen
Quantité maximale de données pouvant être reçues.
Renvoie
Nombre d'octets reçus ou code d'erreur mbedtls.

otTcpMbedTlsSslSendCallback

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

Envoi non bloquant d'un rappel à transmettre à mbedtls_ssl_set_bio.

Détails
Paramètres
[in] aCtx
Pointeur vers un objet otTcpEndpointAndCircularSendBuffer.
[in] aBuf
Données à ajouter au tampon d'envoi.
[in] aLen
Quantité de données à ajouter au tampon d'envoi.
Renvoie
Nombre d'octets envoyés ou code d'erreur mbedtls.

Ressources

Les sujets de référence de l'API OpenThread proviennent du code source, disponible sur GitHub. Pour en savoir plus ou pour contribuer à notre documentation, consultez la section Ressources.