nl::Weave::TLV::TLVUpdater

#include <src/lib/core/WeaveTLV.h>

Fournit une interface de lecture/rédaction unifiée permettant de modifier, d'ajouter ou de supprimer des éléments avec l'encodage TLV.

Résumé

TLVUpdater combine les objets TLVReader et TLVWriter. Il fournit des méthodes d'interface permettant de modifier/supprimer des données dans un encodage, ainsi que d'ajouter de nouveaux éléments à l'encodage TLV. L'objet TLVUpdater agit essentiellement comme deux curseurs, un pour lire l'encodage existant et l'autre pour l'écriture (que ce soit pour copier des données existantes ou écrire de nouvelles données).

Sur le plan sémantique, l'objet TLVUpdater fonctionne comme l'union de TLVReader et de TLVWriter. Les méthodes TLVUpdater ont des significations plus ou moins semblables à celles de leurs homologues portant un nom similaire dans TLVReader/TLVWriter. Lorsqu'il y a des différences au niveau de la sémantique, elles sont clairement documentées dans la section des commentaires de la fonction dans le fichier WeaveTLVUpdater.cpp.

Une remarque particulièrement importante concernant les méthodes PutBytes() et PutString() de TLVUpdater est qu'elles peuvent laisser l'encodage dans un état corrompu, avec seulement l'en-tête de l'élément écrit en cas de dépassement. Les applications peuvent appeler la méthode GetAlwaysFreeLength() pour s'assurer que l'espace disponible est approximatif pour écrire l'encodage. Notez que la méthode GetAlwaysFreeLength() ne vous indique que le nombre d'octets disponibles et que l'application n'a aucun moyen de connaître la longueur des données encodées qui sont écrites. En cas de dépassement, PutBytes() et PutString() renvoient WEAVE_ERROR_BUFFER_TOO_Small à l'appelant.

Notez également que la méthode Next() est surchargée afin d'ignorer l'élément actuel et de faire passer le lecteur interne à l'élément suivant. Le fait d'ignorer les éléments déjà encodés nécessite de modifier les variables d'état d'espace libre du rédacteur interne pour tenir compte du nouvel espace libéré (disponible en les ignorant). L'application doit donc appeler Next() sur le programme de mise à jour après une méthode Get() dont elle ne souhaite pas réécrire la valeur (ce qui équivaut à ignorer l'élément actuel).

Fonctions publiques

CopyElement(TLVReader & reader)
CopyElement(uint64_t tag, TLVReader & reader)
DupBytes(uint8_t *& buf, uint32_t & dataLen)
DupString(char *& buf)
EndContainer(TLVType outerContainerType)
EnterContainer(TLVType & outerContainerType)
Prépare un objet TLVUpdater pour lire les éléments d'un conteneur.
ExitContainer(TLVType outerContainerType)
Lecture complète d'un élément de conteneur TLV et encode une fin de l'élément TLV dans le TLV de sortie.
Finalize(void)
Get(bool & v)
Get(int8_t & v)
Get(int16_t & v)
Get(int32_t & v)
Get(int64_t & v)
Get(uint8_t & v)
Get(uint16_t & v)
Get(uint32_t & v)
Get(uint64_t & v)
Get(float & v)
Get(double & v)
GetBytes(uint8_t *buf, uint32_t bufSize)
GetContainerType(void) const
GetDataPtr(const uint8_t *& data)
GetImplicitProfileId(void)
uint32_t
GetLength(void) const
uint32_t
GetLengthRead(void) const
uint32_t
GetLengthWritten(void)
uint32_t
GetReader(TLVReader & containerReader)
void
GetRemainingFreeLength(void)
uint32_t
GetRemainingLength(void) const
uint32_t
GetString(char *buf, uint32_t bufSize)
GetTag(void) const
uint64_t
GetType(void) const
Init(uint8_t *buf, uint32_t dataLen, uint32_t maxLen)
Initialisez un objet TLVUpdater pour modifier un seul tampon d'entrée.
Init(TLVReader & aReader, uint32_t freeLen)
Initialisez un objet TLVUpdater à l'aide d'un TLVReader.
Move(void)
Copie l'élément actuel à partir de l'entrée TLV dans la sortie TLV.
MoveUntilEnd(void)
void
Déplacez tout, depuis le point de lecture actuel de TLVUpdater jusqu'à la fin du tampon TLV d'entrée et la sortie.
Next(void)
Ignorez l'élément actuel et faites avancer l'objet TLVUpdater jusqu'à l'élément suivant dans le TLV d'entrée.
Put(uint64_t tag, int8_t v)
Put(uint64_t tag, int16_t v)
Put(uint64_t tag, int32_t v)
Put(uint64_t tag, int64_t v)
Put(uint64_t tag, uint8_t v)
Put(uint64_t tag, uint16_t v)
Put(uint64_t tag, uint32_t v)
Put(uint64_t tag, uint64_t v)
Put(uint64_t tag, int8_t v, bool preserveSize)
Put(uint64_t tag, int16_t v, bool preserveSize)
Put(uint64_t tag, int32_t v, bool preserveSize)
Put(uint64_t tag, int64_t v, bool preserveSize)
Put(uint64_t tag, uint8_t v, bool preserveSize)
Put(uint64_t tag, uint16_t v, bool preserveSize)
Put(uint64_t tag, uint32_t v, bool preserveSize)
Put(uint64_t tag, uint64_t v, bool preserveSize)
Put(uint64_t tag, float v)
Put(uint64_t tag, double v)
PutBoolean(uint64_t tag, bool v)
PutBytes(uint64_t tag, const uint8_t *buf, uint32_t len)
PutNull(uint64_t tag)
PutString(uint64_t tag, const char *buf)
PutString(uint64_t tag, const char *buf, uint32_t len)
SetImplicitProfileId(uint32_t profileId)
void
Définissez l'ID de profil implicite pour l'objet TLVUpdater.
StartContainer(uint64_t tag, TLVType containerType, TLVType & outerContainerType)
VerifyEndOfContainer(void)

Fonctions publiques

CopyElement

WEAVE_ERROR CopyElement(
  TLVReader & reader
)

CopyElement

WEAVE_ERROR CopyElement(
  uint64_t tag,
  TLVReader & reader
)

DupBytes

WEAVE_ERROR DupBytes(
  uint8_t *& buf,
  uint32_t & dataLen
)

DupString

WEAVE_ERROR DupString(
  char *& buf
)

EndContainer

WEAVE_ERROR EndContainer(
  TLVType outerContainerType
)

EnterContainer

WEAVE_ERROR EnterContainer(
  TLVType & outerContainerType
)

Prépare un objet TLVUpdater pour lire les éléments d'un conteneur.

Il encode également un début d'objet conteneur dans le TLV de sortie.

La méthode EnterContainer() prépare l'objet TLVUpdater actuel pour commencer à lire les éléments membres d'un conteneur TLV (structure, tableau ou chemin d'accès). Pour chaque appel de la méthode EnterContainer(), les applications doivent effectuer un appel correspondant à ExitContainer().

Lorsque EnterContainer() est appelé, le lecteur de TLVUpdater doit être placé sur l'élément conteneur. La méthode utilise comme argument une référence à une valeur TLVType qui sera utilisée pour enregistrer le contexte de l'outil de mise à jour pendant qu'il lit le conteneur.

Lorsque la méthode EnterContainer() est renvoyée, l'outil de mise à jour est positionné immédiatement avant le premier membre du conteneur. Si vous appelez la fonction Next() de façon répétée, l'outil de mise à jour fera défiler les membres de la collection jusqu'à la fin. L'outil de mise à jour renverra alors WEAVE_END_OF_TLV.

Une fois que l'application a terminé la lecture d'un conteneur, elle peut continuer à lire les éléments après celui-ci en appelant la méthode ExitContainer().

Détails
Paramètres
[out] outerContainerType
Référence à une valeur TLVType qui recevra le contexte de l'outil de mise à jour.
Valeurs de retour
WEAVE_NO_ERROR
Si la méthode a réussi.
WEAVE_ERROR_INCORRECT_STATE
Le lecteur TLVUpdater n'est pas placé sur un élément conteneur.
other
Tout autre code d'erreur Weave ou de plate-forme renvoyé par TLVWriter::StartContainer() ou TLVReader::EnterContainer().

ExitContainer

WEAVE_ERROR ExitContainer(
  TLVType outerContainerType
)

Lecture complète d'un élément de conteneur TLV et encode une fin de l'élément TLV dans le TLV de sortie.

La méthode ExitContainer() restaure l'état d'un objet TLVUpdater après un appel à EnterContainer(). Pour chaque appel de EnterContainer(), les applications doivent effectuer un appel correspondant à ExitContainer(), en transmettant la valeur de contexte renvoyée par la méthode EnterContainer().

Lorsque ExitContainer() est renvoyé, le lecteur TLVUpdater est positionné juste avant le premier élément qui suit le conteneur dans le TLV d'entrée. Les applications peuvent alors appeler Next() pour passer d'un élément à l'autre.

Une fois EnterContainer() appelé, les applications peuvent appeler ExitContainer() sur le programme de mise à jour à tout moment, que tous les éléments du conteneur sous-jacent aient été lus ou non. Notez également que si vous appelez ExitContainer() avant de lire tous les éléments du conteneur, le conteneur mis à jour sera tronqué dans le TLV de sortie.

Détails
Paramètres
[in] outerContainerType
Valeur TLVType renvoyée par la méthode EnterContainer().
Valeurs de retour
WEAVE_NO_ERROR
Si la méthode a réussi.
WEAVE_ERROR_TLV_UNDERRUN
L'encodage TLV sous-jacent s'est terminé prématurément.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Si le programme de mise à jour a rencontré un type d'élément TLV non valide ou non compatible.
WEAVE_ERROR_INVALID_TLV_TAG
Si l'utilisateur a détecté une balise TLV dans un contexte non valide.
other
Tout autre code d'erreur Weave ou de plate-forme renvoyé par TLVWriter::EndContainer() ou TLVReader::ExitContainer().

Finaliser

WEAVE_ERROR Finalize(
  void
)

Télécharger

WEAVE_ERROR Get(
  bool & v
)

Télécharger

WEAVE_ERROR Get(
  int8_t & v
)

Télécharger

WEAVE_ERROR Get(
  int16_t & v
)

Télécharger

WEAVE_ERROR Get(
  int32_t & v
)

Télécharger

WEAVE_ERROR Get(
  int64_t & v
)

Télécharger

WEAVE_ERROR Get(
  uint8_t & v
)

Télécharger

WEAVE_ERROR Get(
  uint16_t & v
)

Télécharger

WEAVE_ERROR Get(
  uint32_t & v
)

Télécharger

WEAVE_ERROR Get(
  uint64_t & v
)

Télécharger

WEAVE_ERROR Get(
  float & v
)

Télécharger

WEAVE_ERROR Get(
  double & v
)

GetBytes

WEAVE_ERROR GetBytes(
  uint8_t *buf,
  uint32_t bufSize
)

GetContainerType

TLVType GetContainerType(
  void
) const 

GetDataPtr

WEAVE_ERROR GetDataPtr(
  const uint8_t *& data
)

GetImplicitProfileId

uint32_t GetImplicitProfileId(
  void
)

GetLength

uint32_t GetLength(
  void
) const 

GetLengthRead

uint32_t GetLengthRead(
  void
) const 

GetLengthWritten

uint32_t GetLengthWritten(
  void
)

GetReader

void GetReader(
  TLVReader & containerReader
)

GetRemainingFreeLength

uint32_t GetRemainingFreeLength(
  void
)

GetRemainingLength

uint32_t GetRemainingLength(
  void
) const 

GetString

WEAVE_ERROR GetString(
  char *buf,
  uint32_t bufSize
)

GetTag

uint64_t GetTag(
  void
) const 

GetType

TLVType GetType(
  void
) const 

Init

WEAVE_ERROR Init(
  uint8_t *buf,
  uint32_t dataLen,
  uint32_t maxLen
)

Initialisez un objet TLVUpdater pour modifier un seul tampon d'entrée.

Lorsque vous appelez cette méthode, les données TLV dans le tampon sont déplacées à la fin de celui-ci, et un objet TLVReader privé est initialisé sur ce tampon déplacé. Un objet TLVWriter privé est également initialisé sur l'espace libre désormais disponible au début. Les applications peuvent utiliser l'objet TLVUpdater pour analyser les données TLV, et modifier/supprimer des éléments existants ou en ajouter de nouveaux à l'encodage.

Détails
Paramètres
[in] buf
Pointeur vers un tampon contenant les données TLV à modifier.
[in] dataLen
Longueur des données TLV dans le tampon.
[in] maxLen
Longueur totale du tampon.
Valeurs de retour
WEAVE_NO_ERROR
Si la méthode a réussi.
WEAVE_ERROR_INVALID_ARGUMENT
Si l'adresse du tampon n'est pas valide.
WEAVE_ERROR_BUFFER_TOO_SMALL
La taille de la mémoire tampon est trop petite.

Init

WEAVE_ERROR Init(
  TLVReader & aReader,
  uint32_t freeLen
)

Initialisez un objet TLVUpdater à l'aide d'un TLVReader.

Lorsque vous appelez cette méthode, les données TLV dans le tampon pointées par le TLVReader sont déplacées du point de lecture actuel vers la fin du tampon. Un nouvel objet TLVReader privé est initialisé pour la lecture à partir de ce nouvel emplacement, tandis qu'un nouvel objet TLVWriter privé est initialisé pour écrire dans l'espace tampon libéré.

Notez que si le TLVReader est déjà positionné "sur" un élément, il s'éloigne d'abord au début de cet élément. Notez également que ce délai fonctionne bien avec les éléments du conteneur. Autrement dit, si le TLVReader a déjà été utilisé pour appeler EnterContainer(), il n'y a rien à renoncer. En revanche, si TLVReader a été placé sur l'élément de conteneur et que EnterContainer() n'a pas encore été appelé, l'objet TLVReader est arrêté au début de l'en-tête du conteneur.

L'objet TLVReader d'entrée est détruit avant d'être renvoyé, et l'application ne doit pas l'utiliser lors du retour.

Détails
Paramètres
[in,out] aReader
Référence à un objet TLVReader qui sera détruit avant d'être renvoyé.
[in] freeLen
Longueur de l'espace disponible (en octets) disponible dans le tampon de données précodé.
Valeurs de retour
WEAVE_NO_ERROR
Si la méthode a réussi.
WEAVE_ERROR_INVALID_ARGUMENT
Si l'adresse du tampon n'est pas valide.
WEAVE_ERROR_NOT_IMPLEMENTED
Si le lecteur a été initialisé sur une chaîne de tampons.

Déplacer

WEAVE_ERROR Move(
  void
)

Copie l'élément actuel à partir de l'entrée TLV dans la sortie TLV.

La méthode Move() copie l'élément actuel sur lequel le lecteur de TLVUpdater est positionné, vers le rédacteur de TLVUpdater. L'application doit appeler Next() et positionner le lecteur de TLVUpdater sur un élément avant d'appeler cette méthode. Tout comme la méthode TLVReader::Next(), si le lecteur est positionné sur un élément conteneur au moment de l'appel, tous les membres du conteneur seront copiés. Si le lecteur n'est positionné sur aucun élément, l'appel de cette méthode ne change rien.

Détails
Valeurs de retour
WEAVE_NO_ERROR
Le lecteur TLVUpdater a bien été positionné sur un nouvel élément.
WEAVE_END_OF_TLV
Si le lecteur de TLVUpdater pointe vers la fin du conteneur.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Si le lecteur du TLVIpdater n'est pas placé sur un élément TLV valide.
other
Renvoie d'autres codes d'erreur renvoyés par la méthode TLVReader::Skip().

MoveUntilEnd

void MoveUntilEnd(
  void
)

Déplacez tout, depuis le point de lecture actuel de TLVUpdater jusqu'à la fin du tampon TLV d'entrée et la sortie.

Cette méthode permet de déplacer tout, depuis le point de lecture actuel de TLVUpdater jusqu'à la fin du tampon du lecteur, vers le rédacteur TLVUpdater.

Suivant

WEAVE_ERROR Next(
  void
)

Ignorez l'élément actuel et faites avancer l'objet TLVUpdater jusqu'à l'élément suivant dans le TLV d'entrée.

La méthode Next() ignore l'élément actuel dans le TLV d'entrée et fait avancer le lecteur du TLVUpdater vers l'élément suivant qui se trouve dans le même contexte de confinement. En particulier, si le lecteur est positionné au niveau le plus externe d'un encodage TLV, appeler Next() permet de passer à l'élément suivant, tout en haut de la page. Si le lecteur est placé dans un élément de conteneur TLV (une structure, un tableau ou un chemin), l'appel de Next() le fait passer à l'élément membre suivant du conteneur.

Étant donné que Next() limite le mouvement du lecteur au contexte de confinement actuel, appeler Next() lorsque le lecteur est positionné sur un élément conteneur fait avancer sur le conteneur, en ignorant ses éléments membres (et les membres de tout conteneur imbriqué) jusqu'à ce qu'il atteigne le premier élément après le conteneur.

Lorsqu'il n'y a plus d'éléments dans un contexte de confinement particulier, la méthode Next() renvoie une erreur WEAVE_END_OF_TLV et la position du lecteur reste inchangée.

Détails
Valeurs de retour
WEAVE_NO_ERROR
Le lecteur TLVUpdater a bien été positionné sur un nouvel élément.
other
Renvoie les codes d'erreur Weave ou de plate-forme renvoyés par les méthodes TLVReader::Skip() et TLVReader::Next().

efficaces avec

WEAVE_ERROR Put(
  uint64_t tag,
  int8_t v
)

efficaces avec

WEAVE_ERROR Put(
  uint64_t tag,
  int16_t v
)

efficaces avec

WEAVE_ERROR Put(
  uint64_t tag,
  int32_t v
)

efficaces avec

WEAVE_ERROR Put(
  uint64_t tag,
  int64_t v
)

efficaces avec

WEAVE_ERROR Put(
  uint64_t tag,
  uint8_t v
)

efficaces avec

WEAVE_ERROR Put(
  uint64_t tag,
  uint16_t v
)

efficaces avec

WEAVE_ERROR Put(
  uint64_t tag,
  uint32_t v
)

efficaces avec

WEAVE_ERROR Put(
  uint64_t tag,
  uint64_t v
)

efficaces avec

WEAVE_ERROR Put(
  uint64_t tag,
  int8_t v,
  bool preserveSize
)

efficaces avec

WEAVE_ERROR Put(
  uint64_t tag,
  int16_t v,
  bool preserveSize
)

efficaces avec

WEAVE_ERROR Put(
  uint64_t tag,
  int32_t v,
  bool preserveSize
)

efficaces avec

WEAVE_ERROR Put(
  uint64_t tag,
  int64_t v,
  bool preserveSize
)

efficaces avec

WEAVE_ERROR Put(
  uint64_t tag,
  uint8_t v,
  bool preserveSize
)

efficaces avec

WEAVE_ERROR Put(
  uint64_t tag,
  uint16_t v,
  bool preserveSize
)

efficaces avec

WEAVE_ERROR Put(
  uint64_t tag,
  uint32_t v,
  bool preserveSize
)

efficaces avec

WEAVE_ERROR Put(
  uint64_t tag,
  uint64_t v,
  bool preserveSize
)

efficaces avec

WEAVE_ERROR Put(
  uint64_t tag,
  float v
)

efficaces avec

WEAVE_ERROR Put(
  uint64_t tag,
  double v
)

PutBoolean

WEAVE_ERROR PutBoolean(
  uint64_t tag,
  bool v
)

PutBytes

WEAVE_ERROR PutBytes(
  uint64_t tag,
  const uint8_t *buf,
  uint32_t len
)

PutNull

WEAVE_ERROR PutNull(
  uint64_t tag
)

PutString

WEAVE_ERROR PutString(
  uint64_t tag,
  const char *buf
)

PutString

WEAVE_ERROR PutString(
  uint64_t tag,
  const char *buf,
  uint32_t len
)

SetImplicitProfileId

void SetImplicitProfileId(
  uint32_t profileId
)

Définissez l'ID de profil implicite pour l'objet TLVUpdater.

Cette méthode définit l'ID de profil implicite pour l'objet TLVUpdater. Lorsque le programme de mise à jour est invité à encoder un nouvel élément, si l'ID de profil de la balise associée au nouvel élément correspond à la valeur de profileId, il encode la balise de manière implicite et omet donc l'ID de profil.

Détails
Paramètres
[in] profileId
ID de profil des balises qui doivent être encodées sous forme implicite.

StartContainer

WEAVE_ERROR StartContainer(
  uint64_t tag,
  TLVType containerType,
  TLVType & outerContainerType
)

VerifyEndOfContainer

WEAVE_ERROR VerifyEndOfContainer(
  void
)