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 des octets, 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 des pools qui se rapprochent des problèmes de mémoire des appareils profondément intégrés.

La classe PacketBuffer, comme de nombreuses structures similaires utilisées dans les piles réseau en couches, 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() et la documentation LwIP.

Les objets PacketBuffer sont comptés par référence, et le mode d'utilisation prédominant dans Weave est "fire-and-forget". Étant donné que le paquet (et son objet PacketBuffer sous-jacent) est envoyé via différentes couches de protocole, un appel montant ou descendant réussi 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 intercalaire, la libération du 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 depuis les pools cibles LwIP PBuf, depuis le tas de mémoire standard de la bibliothèque C ou depuis un pool de tampon interne. Dans le cas simple, la taille du tampon de données est WEAVE_SYSTEM_PACKETBUFFER_SIZE. Un outil de composition permettant d'utiliser des tampons de données d'autres tailles est fourni.

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

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

Héritage

Hérite de : pbuf

Fonctions publiques
AddRef(void)
void
Incrémentez le nombre de références du tampon actuel.
AddToEnd(PacketBuffer *aPacket)
void
Ajoutez le tampon de paquet 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, y compris les espaces de données réservés et de charge utile, mais sans l'espace alloué pour la structure PacketBuffer.
AvailableDataLength(void) const
uint16_t
Obtenez le nombre d'octets de données pouvant être ajoutés au tampon actuel en fonction de la position de départ actuelle et de la longueur des données.
CompactHead(void)
void
Déplacez les données des tampons suivants de la chaîne dans le tampon actuel jusqu'à ce qu'elles soient pleines.
Consume(uint16_t aConsumeLength)
Consommer les données d'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
Récupère 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 contient au moins 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 le tampon en fonction de la position de départ actuelle et de la taille de la mémoire tampon.
Next(void) const
Permet d'obtenir le pointeur vers le tampon suivant de la chaîne.
ReservedSize(void) const
uint16_t
Obtient 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 *
Permet d'obtenir le pointeur au début des données du tampon.
TotalLength(void) const
uint16_t
Obtenez la longueur totale des données des paquets dans la chaîne de 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 PacketBuffer de 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 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 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.
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 des données supplémentaires après le pointeur initial du curseur.
RightSize(PacketBuffer *aPacket)
Copiez le tampon donné dans un tampon de taille appropriée, le cas échéant.

Fonctions publiques

AddRef

void AddRef(
  void
)

Incrémentez le nombre de références du tampon actuel.

AddToEnd

void AddToEnd(
  PacketBuffer *aPacket
)

Ajoutez le tampon de paquet 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.

Si nécessaire, déplacez la charge utile dans le tampon.

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

AllocSize

size_t AllocSize(
  void
) const

Renvoie la taille de l'allocation, y compris les espaces de données réservés et de charge utile, mais sans l'espace alloué pour la structure PacketBuffer.

Détails
Renvoie
taille de l'allocation

AvailableDataLength

uint16_t AvailableDataLength(
  void
) const

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

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

CompactHead

void CompactHead(
  void
)

Déplacez les données des tampons suivants de la chaîne dans le tampon actuel jusqu'à ce qu'elles soient pleines.

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 avec des données déplacées des tampons suivants de la chaîne, jusqu'à ce que le tampon actuel soit plein. 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 ne prend aucun paramètre, ne renvoie aucun résultat et ne peut pas échouer.

Utiliser

PacketBuffer * Consume(
  uint16_t aConsumeLength
)

Consommer les données d'une chaîne de tampons

Consommer 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 entièrement utilisé est libéré et la fonction renvoie le premier tampon (le cas échéant) contenant les données restantes. Le tampon actuel doit être le début de la chaîne de tampons.

Détails
Paramètres
[in] aConsumeLength
: nombre d'octets à consommer depuis la chaîne actuelle.
Renvoie
le premier tampon de la chaîne actuelle qui contient les données restantes. Si aucune donnée ne subsiste, 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.

Avance la position de départ des données dans le tampon actuel de la quantité spécifiée, en octets, jusqu'à la longueur des données du tampon. Réduisez la durée et la durée 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

Récupère la longueur, en octets, des données dans le tampon de paquets.

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

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 le début 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 contient au moins la quantité d'espace réservé spécifiée.

Assurez-vous que le tampon dispose d'au moins la quantité d'espace réservé spécifiée, en déplaçant les données qu'il contient afin de 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 et false si l'espace dans la mémoire tampon est insuffisant.

MaxDataLength

uint16_t MaxDataLength(
  void
) const

Obtenez la quantité maximale (en octets) de données pouvant tenir dans le tampon en fonction de la position de départ actuelle et de la taille de la mémoire tampon.

Détails
Renvoie
Nombre d'octets adaptés à la mémoire tampon en fonction de la position de départ actuelle.

Suivant

PacketBuffer * Next(
  void
) const

Permet d'obtenir le pointeur vers le tampon suivant de 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 tampon dans la chaîne.

ReservedSize

uint16_t ReservedSize(
  void
) const

Obtenez 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 du tampon, en ajustant la longueur totale en conséquence. Lorsque le tampon n'est pas le début 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 la longueur totale de chaque tampon avant le tampon actuel.

Détails
Paramètres
[in] aNewLen
: nouvelle longueur, en octets, de ce tampon.
[in,out] aChainHead
: début de la chaîne de tampon à laquelle appartient le tampon actuel. Peut être NULL si le tampon actuel est à la tête 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
- Un pointeur vers le point de départ de la nouvelle charge utile. newStart sera ajusté en interne pour se conformer aux limites du premier tampon de la chaîne PacketBuffer.

Démarrer

uint8_t * Start(
  void
) const

Permet d'obtenir le pointeur au début des données du tampon.

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

TotalLength

uint16_t TotalLength(
  void
) const

Obtenez la longueur totale des données des paquets dans la chaîne de tampon.

Détails
Renvoie
la longueur totale, en octets.

Fonctions statiques publiques

Gratuit

void Free(
  PacketBuffer *aPacket
)

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

Diminuer le nombre de références pour afficher 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 dans les pools d'allocation, selon le cas. En règle générale, les utilisateurs doivent traiter cette méthode comme l'équivalent de la fonction free() et ne pas utiliser l'argument après l'appel.

Détails
Paramètres
[in] aPacket
- le 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 la tête, mais ne désaffecte pas de force le tampon principal.

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

Nouveau

PacketBuffer * New(
  void
)

Alloue un seul PacketBuffer de 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.

Nouveau

PacketBuffer * New(
  uint16_t aReservedSize
)

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

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

  • PacketBuffer::New(0) : lorsqu'il est appelé de cette manière, le tampon est renvoyé sans aucun en-tête réservé. Par conséquent, l'intégralité de la charge utile peut être utilisée par l'appelant. Ce modèle est particulièrement utile au niveau des couches inférieures des piles réseau, si l'utilisateur sait que la charge utile sera copiée dans le message final avec des réserves d'en-tête appropriées ou lors de la création de PacketBuffer qui sont 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 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.

Cette utilisation est particulièrement appropriée lors de l'allocation d'un PacketBuffer à un message 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 des 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 appropriée, le cas échéant.

Cette fonction est une opération no-op pour les sockets.

Détails
Paramètres
[in] aPacket
: tampon ou chaîne de tampon.
Renvoie
Nouveau tampon de paquets ou tampon d'origine