nl::Weave::System::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

La classe de tampon de paquets est la structure de base utilisée pour manipuler les paquets de données sérialisées par octet, généralement dans le contexte d'un réseau de communication de données, tel que le Bluetooth ou le protocole Internet.

Résumé

Dans les environnements basés sur LwIP, cette classe repose sur la structure pbuf définie dans cette bibliothèque. En l'absence de LwIP, Weave propose soit une implémentation basée sur malloc, soit une implémentation basée sur un pool qui se rapproche le plus des défis de mémoire des appareils profondément intégrés.

Comme de nombreuses structures similaires utilisées dans les piles réseau en couches, la classe PacketBuffer fournit un mécanisme permettant de réserver de l'espace pour les en-têtes de protocole au niveau de chaque couche d'une pile de communication configurable. Pour en savoir plus, consultez PacketBuffer::New() ainsi que la documentation LwIP.

Les objets PacketBuffer sont comptabilisés en référence, et le mode d'utilisation principal dans Weave est "fire-and-forget". Lorsque le paquet (et son objet PacketBuffer sous-jacent) est envoyé via différentes couches de protocole, la réussite d'un appel ascendant ou descendant entre les couches implique un transfert de propriété, et l'appelé est chargé de libérer le tampon. En cas d'échec d'un appel intercouche, la responsabilité de libérer le tampon incombe à l'appelant.

Les nouveaux objets de la classe PacketBuffer sont initialisés au début d'une allocation de mémoire obtenue à partir de l'environnement sous-jacent (par exemple, à partir de pools cibles LwIP pbuf), à partir du tas de mémoire de la bibliothèque C standard, d'un pool de mémoire tampon interne. Dans le cas simple, la taille du tampon de données est de WEAVE_SYSTEM_PACKETBUFFER_SIZE. Un composer est fourni pour permettre l'utilisation de tampons de données d'autres tailles.

Les objets PacketBuffer peuvent être enchaînés pour accueillir des charges utiles plus importantes. En revanche, le chaînage n'est pas transparent, et les utilisateurs de la classe doivent décider explicitement de le prendre en charge. Voici quelques exemples de classes écrites avec prise en charge des chaînages: 

@ref nl::Weave::WeaveTLVReader
@ref nl::Weave::WeaveTLVWriter

Héritage

Hérite de : pbuf

Fonctions publiques
AddRef(void)
void
Incrémenter le nombre de références du tampon actuel
AddToEnd(PacketBuffer *aPacket)
void
Ajoutez le tampon de paquets donné à la fin de la chaîne de tampon, en ajustant la longueur totale de chaque tampon de la chaîne en conséquence.
AlignPayload(uint16_t aAlignBytes)
bool
Aligne la charge utile du tampon sur la limite d'octets spécifiée.
AllocSize(void) const
size_t
Renvoie la taille de l'allocation, en incluant les espaces de données réservés et la charge utile, sans inclure l'espace alloué à la structure PacketBuffer.
AvailableDataLength(void) const
uint16_t
Obtenir le nombre d'octets de données pouvant être ajoutés au tampon actuel en fonction de la position de départ et de la longueur des données actuelles
CompactHead(void)
void
Déplace les données des tampons suivants de la chaîne vers le tampon actuel jusqu'à ce qu'il soit saturé.
Consume(uint16_t aConsumeLength)
Consomme les données dans une chaîne de tampons.
ConsumeHead(uint16_t aConsumeLength)
void
Ajustez le tampon actuel pour indiquer la quantité de données consommées.
DataLength(void) const
uint16_t
Obtenir la longueur, en octets, des données dans le tampon de paquets.
DetachTail(void)
Dissociez le tampon actuel de sa chaîne et renvoyez un pointeur vers les tampons restants.
EnsureReservedSize(uint16_t aReservedSize)
bool
Assurez-vous que le tampon dispose au moins de la quantité d'espace réservé spécifiée.
MaxDataLength(void) const
uint16_t
Obtenez la quantité maximale, en octets, de données pouvant tenir dans la mémoire tampon en fonction de la position de départ et de la taille de la mémoire tampon actuelles.
Next(void) const
Permet d'obtenir le pointeur vers le tampon suivant dans la chaîne.
ReservedSize(void) const
uint16_t
Obtenir le nombre d'octets dans le tampon actuel entre le début du tampon et la position de début des données actuelle
SetDataLength(uint16_t aNewLen, PacketBuffer *aChainHead)
void
Définissez la longueur, en octets, des données dans la mémoire tampon, et ajustez la longueur totale en conséquence.
SetStart(uint8_t *aNewStart)
void
Définissez les données de début dans la mémoire tampon, en ajustant la longueur et la longueur totale en conséquence.
Start(void) const
uint8_t *
Renvoie le pointeur vers le début des données dans la mémoire tampon.
TotalLength(void) const
uint16_t
Obtenir la longueur totale des données des paquets dans la chaîne de mémoire tampon

Fonctions statiques publiques
Free(PacketBuffer *aPacket)
void
Libérez tous les tampons de paquets d'une chaîne.
FreeHead(PacketBuffer *aPacket)
Libérez le premier tampon d'une chaîne en renvoyant un pointeur vers les tampons restants.
New(void)
Alloue un seul objet PacketBuffer de la taille maximale par défaut (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) avec la taille réservée par défaut (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) dans la charge utile.
New(uint16_t aReservedSize)
Alloue un seul élément PacketBuffer de taille totale maximale avec une taille de réserve d'en-tête spécifique.
NewWithAvailableSize(size_t aAvailableSize)
Alloue un PacketBuffer avec une taille réservée par défaut (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) dans la charge utile des en-têtes et au moins aAllocSize octets d'espace pour les données supplémentaires après le pointeur initial du curseur.
NewWithAvailableSize(uint16_t aReservedSize, size_t aAvailableSize)
Alloue un objet PacketBuffer avec au moins aReservedSize octets réservés dans la charge utile pour les en-têtes et au moins aAllocSize octets d'espace pour les données supplémentaires après le pointeur initial du curseur.
RightSize(PacketBuffer *aPacket)
Copiez le tampon donné dans un tampon de taille correcte, le cas échéant.

Fonctions publiques

AddRef

void AddRef(
  void
)

Incrémenter le nombre de références du tampon actuel

AddToEnd

void AddToEnd(
  PacketBuffer *aPacket
)

Ajoutez le tampon de paquets donné à la fin de la chaîne de tampon, en ajustant la longueur totale de chaque tampon de la chaîne en conséquence.

Détails
Paramètres
[in] aPacket
: tampon de paquets à ajouter à la fin de la chaîne actuelle.

AlignPayload

bool AlignPayload(
  uint16_t aAlignBytes
)

Aligne la charge utile du tampon sur la limite d'octets spécifiée.

Déplacement de la charge utile dans le tampon vers l'avant, si nécessaire.

Détails
Paramètres
[in] aAlignBytes
: spécifie le nombre d'octets du pointeur de début de la charge utile.
Renvoie
true si l'alignement est réussi, false s'il n'y a pas assez d'espace dans le tampon.

AllocSize

size_t AllocSize(
  void
) const

Renvoie la taille de l'allocation, en incluant les espaces de données réservés et la charge utile, sans inclure l'espace alloué à la structure PacketBuffer.

Détails
Renvoie
la taille de l'allocation

AvailableDataLength

uint16_t AvailableDataLength(
  void
) const

Obtenir le nombre d'octets de données pouvant être ajoutés au tampon actuel en fonction de la position de départ et de la longueur des données actuelles

Détails
Renvoie
la longueur, en octets, des données pouvant tenir dans le tampon actuel, compte tenu de la position de départ et de la longueur actuelles des données.

CompactHead

void CompactHead(
  void
)

Déplace les données des tampons suivants de la chaîne vers le tampon actuel jusqu'à ce qu'il soit saturé.

Seul le tampon actuel est compacté: les données qu'il contient sont déplacées au début du tampon, éliminant ainsi tout espace réservé. L'espace disponible restant est rempli par les données déplacées à partir des tampons suivants de la chaîne, jusqu'à ce que le tampon actuel soit saturé. Si un tampon ultérieur de la chaîne est déplacé dans le tampon actuel dans son intégralité, il est supprimé de la chaîne et libéré. La méthode n'accepte aucun paramètre, ne renvoie aucun résultat et ne peut pas échouer.

Utiliser

PacketBuffer * Consume(
  uint16_t aConsumeLength
)

Consomme les données dans une chaîne de tampons.

Consomme les données d'une chaîne de tampons en commençant par le tampon actuel et en parcourant les tampons restants de la chaîne. Chaque tampon complètement consommé est libéré et la fonction renvoie le premier tampon (le cas échéant) contenant les données restantes. Le tampon actuel doit être l'élément principal de la chaîne de tampon.

Détails
Paramètres
[in] aConsumeLength
: nombre d'octets à consommer à partir de la chaîne actuelle.
Renvoie
le premier tampon de la chaîne actuelle qui contient les données restantes. S'il ne reste aucune donnée, une valeur NULL est renvoyée.

ConsumeHead

void ConsumeHead(
  uint16_t aConsumeLength
)

Ajustez le tampon actuel pour indiquer la quantité de données consommées.

Faites avancer la position de départ des données dans le tampon actuel selon la quantité spécifiée, en octets, jusqu'à la longueur des données dans le tampon. Réduisez la longueur et la longueur totale en fonction de la quantité consommée.

Détails
Paramètres
[in] aConsumeLen
: nombre d'octets à consommer à partir du tampon actuel.

DataLength

uint16_t DataLength(
  void
) const

Obtenir la longueur, en octets, des données dans le tampon de paquets.

Détails
Renvoie
longueur, en octets (longueur de la charge utile actuelle).

DetachTail

PacketBuffer * DetachTail(
  void
)

Dissociez le tampon actuel de sa chaîne et renvoyez un pointeur vers les tampons restants.

Le tampon actuel doit être l'élément principal de la chaîne.

Détails
Renvoie
la fin de la chaîne de tampon actuelle ou NULL si le tampon actuel est le seul tampon de la chaîne.

EnsureReservedSize

bool EnsureReservedSize(
  uint16_t aReservedSize
)

Assurez-vous que le tampon dispose au moins de la quantité d'espace réservé spécifiée.

Assurez-vous que le tampon dispose au moins de la quantité d'espace réservée spécifiée, en déplaçant les données dans le tampon vers l'avant pour libérer de l'espace si nécessaire.

Détails
Paramètres
[in] aReservedSize
: nombre d'octets souhaités pour les en-têtes.
Renvoie
true si la taille réservée demandée est disponible, false si l'espace dans le tampon est insuffisant.

MaxDataLength

uint16_t MaxDataLength(
  void
) const

Obtenez la quantité maximale, en octets, de données pouvant tenir dans la mémoire tampon en fonction de la position de départ et de la taille de la mémoire tampon actuelles.

Détails
Renvoie
nombre d'octets pouvant tenir dans le tampon, compte tenu de la position de départ actuelle.

Suivant

PacketBuffer * Next(
  void
) const

Permet d'obtenir le pointeur vers le tampon suivant dans la chaîne.

Détails
Renvoie
un pointeur vers le tampon suivant dans la chaîne. NULL est renvoyé lorsqu'il n'y a pas de tampons dans la chaîne.

ReservedSize

uint16_t ReservedSize(
  void
) const

Obtenir le nombre d'octets dans le tampon actuel entre le début du tampon et la position de début des données actuelle

Détails
Renvoie
la quantité d'espace, en octets, entre le début du tampon et la position de début des données actuelle ;

SetDataLength

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

Définissez la longueur, en octets, des données dans la mémoire tampon, et ajustez la longueur totale en conséquence.

La fonction définit la longueur, en octets, des données dans le tampon, en ajustant la longueur totale de manière appropriée. Lorsque le tampon n'est pas la tête de la chaîne de tampon (cas courant: l'appelant ajoute des données au dernier tampon de la chaîne PacketBuffer avant d'appeler les couches supérieures), aChainHead doit être transmis pour ajuster correctement les longueurs totales de chaque tampon avant le tampon actuel.

Détails
Paramètres
[in] aNewLen
: nouvelle longueur, en octets, de ce tampon.
[in,out] aChainHead
: tête de la chaîne de tampons à laquelle appartient le tampon actuel. Peut être NULL si le tampon actuel est le chef de la chaîne de tampon.

SetStart

void SetStart(
  uint8_t *aNewStart
)

Définissez les données de début dans la mémoire tampon, en ajustant la longueur et la longueur totale en conséquence.

Détails
Paramètres
[in] aNewStart
: pointeur vers l'endroit où la nouvelle charge utile doit commencer. newStart est ajusté en interne pour correspondre aux limites du premier tampon de la chaîne PacketBuffer.

Commencer

uint8_t * Start(
  void
) const

Renvoie le pointeur vers le début des données dans la mémoire tampon.

Détails
Renvoie
pointeur vers le début des données.

TotalLength

uint16_t TotalLength(
  void
) const

Obtenir la longueur totale des données des paquets dans la chaîne de mémoire tampon

Détails
Renvoie
longueur totale, en octets.

Fonctions statiques publiques

Sans frais

void Free(
  PacketBuffer *aPacket
)

Libérez tous les tampons de paquets d'une chaîne.

Diminuez le nombre de références à tous les tampons de la chaîne actuelle. Si le nombre de références atteint 0, les tampons respectifs sont libérés ou renvoyés vers des pools d'allocation, le cas échéant. En règle générale, les utilisateurs doivent traiter cette méthode comme un équivalent de la fonction free() et ne pas utiliser l'argument après l'appel.

Détails
Paramètres
[in] aPacket
- Tampon de paquets à libérer.

FreeHead

PacketBuffer * FreeHead(
  PacketBuffer *aPacket
)

Libérez le premier tampon d'une chaîne en renvoyant un pointeur vers les tampons restants.

* @note When the buffer chain is referenced by multiple callers,FreeHead() détache l'élément "head", sans forcer la désallocation du tampon principal.

Détails
Paramètres
[in] aPacket
- Chaîne de tampons.
Renvoie
chaîne de tampon de paquets composée de la fin du tampon d'entrée (peut être NULL).

Nouvelle version

PacketBuffer * New(
  void
)

Alloue un seul objet PacketBuffer de la taille maximale par défaut (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) avec la taille réservée par défaut (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) dans la charge utile.

La taille réservée (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) est suffisamment grande pour contenir les en-têtes de la couche transport ainsi que les en-têtes requis par WeaveMessageLayer et WeaveExchangeLayer.

Nouvelle version

PacketBuffer * New(
  uint16_t aReservedSize
)

Alloue un seul élément PacketBuffer de taille totale maximale avec une taille de réserve d'en-tête spécifique.

Le paramètre transmis correspond à la taille réservée avant la charge utile pour gérer les en-têtes de paquets provenant de différentes couches de pile, et non à la taille globale du tampon à allouer. Taille du tampon (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) spécifiée dans l'appel.

  • PacketBuffer::New(0) : lorsqu'il est appelé de cette manière, le tampon est renvoyé sans en-tête réservé. L'appelant peut donc utiliser l'intégralité de la charge utile. Ce modèle est particulièrement utile dans les couches inférieures des piles réseau, lorsque l'utilisateur sait que la charge utile sera copiée dans le message final avec les réserves d'en-tête appropriées ou lors de la création de PacketBuffer ajoutés à une chaîne de PacketBuffer via PacketBuffer::AddToEnd(). Paramètres
    [in] aReservedSize
    d'espace d'en-tête à réserver.
    Renvoie
    En cas de réussite, un pointeur vers PacketBuffer, en cas d'échec NULL.

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

Alloue un PacketBuffer avec une taille réservée par défaut (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) dans la charge utile des en-têtes et au moins aAllocSize octets d'espace pour les données supplémentaires après le pointeur initial du curseur.

Cette utilisation est particulièrement appropriée lors de l'allocation d'un PacketBuffer à un message au niveau de la couche d'application.

Détails
Paramètres
[in] aAvailableSize
Nombre d'octets à allouer après le curseur.
Renvoie
En cas de réussite, pointeur vers PacketBuffer dans le bloc alloué. En cas d'échec : NULL. *

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

Alloue un objet PacketBuffer avec au moins aReservedSize octets réservés dans la charge utile pour les en-têtes et au moins aAllocSize octets d'espace pour les données supplémentaires après le pointeur initial du curseur.

Détails
Paramètres
[in] aReservedSize
Nombre d'octets à réserver derrière le curseur.
[in] aAvailableSize
Nombre d'octets à allouer après le curseur.
Renvoie
En cas de réussite, pointeur vers PacketBuffer dans le bloc alloué. En cas d'échec : NULL.

RightSize

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

Copiez le tampon donné dans un tampon de taille correcte, le cas échéant.

Il s'agit d'une fonction no-op pour les sockets.

Détails
Paramètres
[in] aPacket
- Mise en mémoire tampon ou chaîne de tampons.
Renvoie
nouveau tampon de paquets ou le tampon d'origine