nl:: Weave:: TLV:: TLVUpdater
#include <src/lib/core/WeaveTLV.h>
Proporciona una interfaz Lector/Escritorio unificada para editar, agregar o borrar elementos en codificación TLV.
Resumen
TLVUpdater es una unión de los objetos TLVReader y TLVWriter y proporciona métodos de interfaz para editar o borrar datos de una codificación, además de agregar elementos nuevos a la codificación TLV. El objeto TLVUpdater esencialmente actúa como dos cursores: uno para leer la codificación existente y otro para la escritura (ya sea para copiar datos existentes o escribir datos nuevos).
Semánticamente, el objeto TLVUpdater funciona como una unión de TLVReader y TLVWriter. Los métodos TLVUpdater tienen significados más o menos similares a los equivalentes con nombres similares en TLVReader/TLVWriter. Cuando existen diferencias en la semántica, las diferencias se documentan con claridad en la sección de comentarios de la función en WeaveTLVUpdater.cpp.
Una nota particularmente importante sobre los métodos PutBytes() y PutString() de TLVUpdater es que puede dejar la codificación en estado dañado con solo el encabezado del elemento escrito cuando se produce un desbordamiento. Las aplicaciones pueden llamar a GetProvideingFreeLength() a fin de asegurarse de que haya aproximadamente espacio libre suficiente para escribir la codificación. Ten en cuenta que GetREMAININGingFreeLength() solo indica los bytes libres disponibles y no hay manera de que la aplicación conozca la longitud de los datos codificados que se escriben. En el caso de un desbordamiento, tanto PutBytes() como PutString() mostrarán WEAVE_ERROR_BUFFER_TOO_SMALL al emisor.
Además, ten en cuenta que el método Next() se sobrecarga para omitir el elemento actual y, además, hacer avanzar el lector interno al siguiente elemento. Debido a que omitir elementos ya codificados requiere cambiar las variables de estado del espacio libre del escritor interno para dar cuenta del nuevo espacio libre (que está disponible cuando se omite), se espera que la aplicación llame a Next() en el actualizador después de un método Get() cuyo valor no desea volver a escribir (lo que equivale a omitir el elemento actual).
Funciones públicas |
|
---|---|
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)
|
Prepara un objeto TLVUpdater para leer elementos de un contenedor.
|
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)
|
Inicializa un objeto TLVUpdater para editar un solo búfer de entrada.
|
Init(TLVReader & aReader, uint32_t freeLen)
|
Inicializa un objeto TLVUpdater con un TLVReader.
|
Move(void)
|
|
MoveUntilEnd(void)
|
void
Mueve todo desde el punto de lectura actual del TLVUpdater hasta el final del búfer TLV de entrada a la salida.
|
Next(void)
|
Se omite el elemento actual y hace avanzar el objeto TLVUpdater al siguiente elemento en el TLV de entrada.
|
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
Establece el ID de perfil implícito para el objeto TLVUpdater.
|
StartContainer(uint64_t tag, TLVType containerType, TLVType & outerContainerType)
|
|
VerifyEndOfContainer(void)
|
Funciones públicas
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 )
Prepara un objeto TLVUpdater para leer elementos de un contenedor.
También codifica el inicio del objeto del contenedor en el TLV de salida.
El método EnterContainer() prepara el objeto TLVUpdater actual para comenzar a leer los elementos miembros de un contenedor TLV (una estructura, un array o una ruta). Por cada llamada a EnterContainer(), las aplicaciones deben hacer la llamada correspondiente a ExitContainer().
Cuando se llama a EnterContainer(), el lector de TLVUpdater se debe colocar en el elemento contenedor. El método toma como argumento una referencia a un valor TLVType que se usará para guardar el contexto del actualizador mientras se lee el contenedor.
Cuando se muestra el método EnterContainer(), la herramienta de actualización se posiciona inmediatamente antes del primer miembro del contenedor. Las llamadas repetidas a Next() hacen que el actualizador avance entre los miembros de la colección hasta el final. A partir de ese momento, el actualizador devolverá WEAVE_END_OF_TLV.
Una vez que la aplicación termina de leer un contenedor, puede continuar leyendo los elementos después del contenedor mediante una llamada al método ExitContainer().
Detalles | |||||||
---|---|---|---|---|---|---|---|
Parámetros |
|
||||||
Valores de retorno |
|
ExitContainer
WEAVE_ERROR ExitContainer( TLVType outerContainerType )
Completa la lectura de un elemento de contenedor TLV y codifica un final de un elemento TLV en el TLV de salida.
El método ExitContainer() restablece el estado de un objeto TLVUpdater después de una llamada a EnterContainer(). Por cada llamada a EnterContainer(), las aplicaciones deben realizar la llamada correspondiente a ExitContainer() y pasar el valor de contexto que muestra el método EnterContainer().
Cuando se muestra ExitContainer(), el lector de TLVUpdater se posiciona inmediatamente antes del primer elemento que sigue al contenedor en el TLV de entrada. Desde este punto, las aplicaciones pueden llamar a Next() para avanzar por los elementos restantes.
Una vez que se llama a EnterContainer(), las aplicaciones pueden llamar a ExitContainer() en el actualizador en cualquier momento, sin importar si se leyeron todos los elementos del contenedor subyacente. Además, ten en cuenta que si llamas a ExitContainer() antes de leer todos los elementos del contenedor, el contenedor actualizado se truncará en el TLV de salida.
Detalles | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Parámetros |
|
||||||||||
Valores de retorno |
|
Finalizar
WEAVE_ERROR Finalize( void )
Obtener
WEAVE_ERROR Get( bool & v )
Obtener
WEAVE_ERROR Get( int8_t & v )
Obtener
WEAVE_ERROR Get( int16_t & v )
Obtener
WEAVE_ERROR Get( int32_t & v )
Obtener
WEAVE_ERROR Get( int64_t & v )
Obtener
WEAVE_ERROR Get( uint8_t & v )
Obtener
WEAVE_ERROR Get( uint16_t & v )
Obtener
WEAVE_ERROR Get( uint32_t & v )
Obtener
WEAVE_ERROR Get( uint64_t & v )
Obtener
WEAVE_ERROR Get( float & v )
Obtener
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 )
Inicializa un objeto TLVUpdater para editar un solo búfer de entrada.
Cuando se llama a este método, los datos TLV del búfer se mueven al final de este y se inicializa un objeto TLVReader privado en este búfer reubicado. También se inicializa un objeto TLVWriter privado en el espacio libre que ahora está disponible al comienzo. Las aplicaciones pueden usar el objeto TLVUpdater para analizar los datos TLV y modificar o borrar elementos existentes, o agregar elementos nuevos a la codificación.
Detalles | |||||||
---|---|---|---|---|---|---|---|
Parámetros |
|
||||||
Valores de retorno |
|
Init
WEAVE_ERROR Init( TLVReader & aReader, uint32_t freeLen )
Inicializa un objeto TLVUpdater con un TLVReader.
Cuando se llama a este método, los datos TLV en el búfer al que hace referencia TLVReader se mueven del punto de lectura actual al final del búfer. Se inicializa un objeto TLVReader nuevo para leer desde esta ubicación nueva, mientras que se inicializa un objeto TLVWriter nuevo para escribir en el espacio de búfer liberado.
Ten en cuenta que si el TLVReader ya se encuentra "encendido" elemento, primero se retira hasta el inicio de ese elemento. Además, ten en cuenta que esta operación de copia de seguridad funciona bien con los elementos de contenedor, es decir, si el TLVReader ya se usó para llamar a EnterContainer(), no hay nada para retirar. Sin embargo, si TLVReader se colocó en el elemento contenedor y aún no se llamó a EnterContainer(), se quitará el objeto TLVReader al comienzo del encabezado del contenedor.
El objeto de entrada TLVReader se destruirá antes de devolverse y la aplicación no debe usar el mismo cuando se devuelva.
Detalles | |||||||
---|---|---|---|---|---|---|---|
Parámetros |
|
||||||
Valores de retorno |
|
Mover
WEAVE_ERROR Move( void )
Copia el elemento actual de TLV de entrada a TLV de salida.
El método Move() copia el elemento actual en el que se posiciona el lector de TLVUpdater en el escritor de TLVUpdater. La aplicación debe llamar a Next() y posicionar el lector de TLVUpdater en un elemento antes de llamar a este método. Al igual que con el método TLVReader::Next(), si el lector se posiciona en un elemento de contenedor en el momento de la llamada, se copiarán todos los miembros del contenedor. Si el lector no se posiciona en ningún elemento, nada cambia cuando se llama a este método.
Detalles | |||||||||
---|---|---|---|---|---|---|---|---|---|
Valores de retorno |
|
MoveUntilEnd
void MoveUntilEnd( void )
Mueve todo desde el punto de lectura actual del TLVUpdater hasta el final del búfer TLV de entrada a la salida.
Este método admite mover todo desde el punto de lectura actual de TLVUpdater hasta el final del búfer de lector al escritor de TLVUpdater.
Siguiente
WEAVE_ERROR Next( void )
Se omite el elemento actual y hace avanzar el objeto TLVUpdater al siguiente elemento en el TLV de entrada.
El método Next() omite el elemento actual en el TLV de entrada y hace que el lector del TLVUpdater pase al siguiente elemento que reside en el mismo contexto de contención. En particular, si el lector se coloca en el nivel más externo de una codificación TLV, llamar a Next() lo avanzará al siguiente elemento superior. Si el lector se posiciona dentro de un elemento de contenedor TLV (una estructura, un array o una ruta), llamar a Next() lo avanzará al siguiente elemento miembro del contenedor.
Dado que Next() restringe el movimiento del lector al contexto de contención actual, llamar a Next() cuando el lector se encuentre en un elemento de contenedor avanzará por el contenedor y omitirá sus elementos miembros (y los miembros de cualquier contenedor anidado) hasta llegar al primer elemento después del contenedor.
Cuando no haya más elementos dentro de un contexto de contención en particular, el método Next() mostrará un error WEAVE_END_OF_TLV y la posición del lector no se modificará.
Detalles | |||||
---|---|---|---|---|---|
Valores de retorno |
|
Put
WEAVE_ERROR Put( uint64_t tag, int8_t v )
Put
WEAVE_ERROR Put( uint64_t tag, int16_t v )
Put
WEAVE_ERROR Put( uint64_t tag, int32_t v )
Put
WEAVE_ERROR Put( uint64_t tag, int64_t v )
Put
WEAVE_ERROR Put( uint64_t tag, uint8_t v )
Put
WEAVE_ERROR Put( uint64_t tag, uint16_t v )
Put
WEAVE_ERROR Put( uint64_t tag, uint32_t v )
Put
WEAVE_ERROR Put( uint64_t tag, uint64_t v )
Put
WEAVE_ERROR Put( uint64_t tag, int8_t v, bool preserveSize )
Put
WEAVE_ERROR Put( uint64_t tag, int16_t v, bool preserveSize )
Put
WEAVE_ERROR Put( uint64_t tag, int32_t v, bool preserveSize )
Put
WEAVE_ERROR Put( uint64_t tag, int64_t v, bool preserveSize )
Put
WEAVE_ERROR Put( uint64_t tag, uint8_t v, bool preserveSize )
Put
WEAVE_ERROR Put( uint64_t tag, uint16_t v, bool preserveSize )
Put
WEAVE_ERROR Put( uint64_t tag, uint32_t v, bool preserveSize )
Put
WEAVE_ERROR Put( uint64_t tag, uint64_t v, bool preserveSize )
Put
WEAVE_ERROR Put( uint64_t tag, float v )
Put
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 )
Establece el ID de perfil implícito para el objeto TLVUpdater.
Este método establece el ID de perfil implícito para el objeto TLVUpdater. Cuando se le solicita al actualizador que codifique un elemento nuevo, si el ID de perfil de la etiqueta asociada con el elemento nuevo coincide con el valor de profileId
, el actualizador codificará la etiqueta de forma implícita y omitirá el ID de perfil en el proceso.
Detalles | |||
---|---|---|---|
Parámetros |
|
StartContainer
WEAVE_ERROR StartContainer( uint64_t tag, TLVType containerType, TLVType & outerContainerType )