nl::Weave::TLV::TLVUpdater

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

Fournit une interface Reader/Writer unifiée permettant de modifier, d'ajouter et de supprimer des éléments au format TLV.

Résumé

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

Sur le plan sémantique, l'objet TLVUpdater fonctionne comme une union entre TLVReader et TLVWriter. Les méthodes TLVUpdater ont des significations plus ou moins similaires à celles de leurs homologues similaires dans TLVReader/TLVWriter. En cas de différences dans la sémantique, celles-ci sont clairement documentées dans la section des commentaires de la fonction dans WeaveTLVUpdater.cpp.

Remarque particulièrement importante concernant les méthodes PutBytes() et PutString() de TLVUpdater : il peut laisser l'encodage dans un état corrompu, seul l'en-tête de l'élément étant écrit en cas de débordement. Les applications peuvent appeler GetRestezFreeLength() pour s'assurer qu'il y a environ assez d'espace libre pour écrire l'encodage. Notez que GetRestezFreeLength() ne vous indique que les octets disponibles disponibles. De plus, il n'existe aucun moyen pour l'application de connaître la longueur des données encodées qui sont écrites. En cas de débordement, PutBytes() et PutString() renvoient WEAVE_ERROR_BUFFER_TOO_Small à l'appelant.

En outre, notez que la méthode Next() est surchargée pour ignorer l'élément actuel et faire passer le lecteur interne à l'élément suivant. Étant donné que le fait d'ignorer des éléments déjà encodés nécessite de modifier les variables d'état de l'espace libre du rédacteur interne pour tenir compte du nouvel espace libéré (mis à disposition en les ignorant), l'application doit 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)
Effectue la lecture d'un élément de conteneur TLV et encode une fin de l'élément TLV dans la sortie TLV.
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 de l'entrée TLV vers la sortie TLV.
MoveUntilEnd(void)
void
Déplacez tout le contenu du point de lecture actuel du TLVUpdater jusqu'à la fin du tampon d'entrée TLV vers la sortie.
Next(void)
Ignore l'élément actuel et fait avancer l'objet TLVUpdater vers l'élément suivant dans la 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.

Elle encode également un début d'objet conteneur dans la sortie TLV.

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 à EnterContainer(), les applications doivent effectuer un appel correspondant à ExitContainer().

Lorsque la méthode EnterContainer() est appelée, le lecteur TLVUpdater doit être positionné 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 du programme de mise à jour pendant la lecture du conteneur.

Lorsque la méthode EnterContainer() est renvoyée, le programme de mise à jour est positionné immédiatement avant le premier membre du conteneur. L'appel répété de Next() fait avancer le programme de mise à jour parmi les membres de la collection jusqu'à la fin, auquel cas il renvoie WEAVE_END_OF_TLV.

Une fois que l'application a fini de lire un conteneur, elle peut continuer à lire les éléments situés après le conteneur 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 renvoyées
WEAVE_NO_ERROR
Si la méthode aboutit.
WEAVE_ERROR_INCORRECT_STATE
Si le lecteur TLVUpdater n'est pas positionné sur un élément de 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
)

Effectue la lecture d'un élément de conteneur TLV et encode une fin de l'élément TLV dans la sortie TLV.

La méthode ExitContainer() restaure l'état d'un objet TLVUpdater après un appel à EnterContainer(). Pour chaque appel à 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é immédiatement avant le premier élément qui suit le conteneur dans l'entrée TLV. À ce stade, les applications peuvent appeler Next() pour faire défiler les éléments restants.

Une fois que la méthode EnterContainer() a été appelée, 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 la sortie TLV.

Détails
Paramètres
[in] outerContainerType
Valeur TLVType renvoyée par la méthode EnterContainer().
Valeurs renvoyées
WEAVE_NO_ERROR
Si la méthode aboutit.
WEAVE_ERROR_TLV_UNDERRUN
Si l'encodage TLV sous-jacent s'est terminé prématurément.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Si le programme de mise à jour a détecté un type d'élément TLV non valide ou non compatible.
WEAVE_ERROR_INVALID_TLV_TAG
Si le programme de mise à jour 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.

Lors de l'appel de cette méthode, les données TLV du tampon sont déplacées à la fin du tampon 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 ajouter de nouveaux éléments à 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 la mémoire tampon.
[in] maxLen
Longueur totale du tampon.
Valeurs renvoyées
WEAVE_NO_ERROR
Si la méthode aboutit.
WEAVE_ERROR_INVALID_ARGUMENT
Si l'adresse de la mémoire tampon n'est pas valide.
WEAVE_ERROR_BUFFER_TOO_SMALL
Si 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.

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

Notez que si TLVReader est déjà "activé", d'un élément, elle est d'abord retirée par rapport au début de cet élément. Notez également que cet écart fonctionne bien avec les éléments de conteneur. En d'autres termes, si TLVReader a déjà été utilisé pour appeler EnterContainer(), il n'y a rien à faire. Toutefois, si TLVReader a été positionné sur l'élément conteneur et que EnterContainer() n'a pas encore été appelé, l'objet TLVReader est sauvegardé au début de l'en-tête du conteneur.

L'objet TLVReader d'entrée est détruit avant le renvoi, et l'application ne doit pas l'utiliser à nouveau.

Détails
Paramètres
[in,out] aReader
Référence à un objet TLVReader qui sera détruit avant le renvoi.
[in] freeLen
Longueur de l'espace disponible (en octets) disponible dans le tampon de données pré-codé.
Valeurs renvoyées
WEAVE_NO_ERROR
Si la méthode aboutit.
WEAVE_ERROR_INVALID_ARGUMENT
Si l'adresse de la mémoire 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 de l'entrée TLV vers la sortie TLV.

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

Détails
Valeurs renvoyées
WEAVE_NO_ERROR
Indique si le lecteur TLVUpdater a bien été positionné sur un nouvel élément.
WEAVE_END_OF_TLV
Si le lecteur du TLVUpdater pointe vers la fin du conteneur.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Si le lecteur du TLVIpdater n'est pas positionné 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 le contenu du point de lecture actuel du TLVUpdater jusqu'à la fin du tampon d'entrée TLV vers la sortie.

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

Suivant

WEAVE_ERROR Next(
  void
)

Ignore l'élément actuel et fait avancer l'objet TLVUpdater vers l'élément suivant dans la TLV d'entrée.

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

Étant donné que Next() contraint les mouvements du lecteur au contexte actuel de structuration, l'appel de Next() lorsque le lecteur est placé sur un élément de conteneur avance au-dessus du conteneur, en ignorant ses éléments membres (et ceux des conteneurs imbriqués) jusqu'à ce qu'il atteigne le premier élément après le conteneur.

En l'absence d'autres éléments dans un contexte de structuration particulier, la méthode Next() renvoie une erreur WEAVE_END_OF_TLV et la position du lecteur reste inchangée.

Détails
Valeurs renvoyées
WEAVE_NO_ERROR
Indique si 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().

Écrire

WEAVE_ERROR Put(
  uint64_t tag,
  int8_t v
)

Écrire

WEAVE_ERROR Put(
  uint64_t tag,
  int16_t v
)

Écrire

WEAVE_ERROR Put(
  uint64_t tag,
  int32_t v
)

Écrire

WEAVE_ERROR Put(
  uint64_t tag,
  int64_t v
)

Écrire

WEAVE_ERROR Put(
  uint64_t tag,
  uint8_t v
)

Écrire

WEAVE_ERROR Put(
  uint64_t tag,
  uint16_t v
)

Écrire

WEAVE_ERROR Put(
  uint64_t tag,
  uint32_t v
)

Écrire

WEAVE_ERROR Put(
  uint64_t tag,
  uint64_t v
)

Écrire

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

Écrire

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

Écrire

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

Écrire

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

Écrire

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

Écrire

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

Écrire

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

Écrire

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

Écrire

WEAVE_ERROR Put(
  uint64_t tag,
  float v
)

Écrire

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 sous forme implicite et omet ainsi l'ID de profil dans le processus.

Détails
Paramètres
[in] profileId
ID de profil des tags devant être encodés de manière implicite.

StartContainer

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

VerifyEndOfContainer

WEAVE_ERROR VerifyEndOfContainer(
  void
)