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)
|
|
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)
|
|
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 |
|
||||||
Valeurs de retour |
|
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 |
|
||||||||||
Valeurs de retour |
|
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 |
|
||||||
Valeurs de retour |
|
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 |
|
||||||
Valeurs de retour |
|
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 |
|
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 |
|
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 |
|
StartContainer
WEAVE_ERROR StartContainer( uint64_t tag, TLVType containerType, TLVType & outerContainerType )