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)
Completa la lectura de un elemento de contenedor TLV y codifica un final de un elemento TLV en el TLV de salida.
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)
Copia el elemento actual de TLV de entrada a TLV de salida.
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
[out] outerContainerType
Una referencia a un valor TLVType que recibirá el contexto del actualizador.
Valores de retorno
WEAVE_NO_ERROR
Si el método tuvo éxito.
WEAVE_ERROR_INCORRECT_STATE
Si el lector TLVUpdater no se posiciona en un elemento contenedor.
other
Cualquier otro código de error de Weave o de la plataforma que muestre TLVWriter::StartContainer() o TLVReader::EnterContainer()

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
[in] outerContainerType
El valor TLVType que mostró el método EnterContainer().
Valores de retorno
WEAVE_NO_ERROR
Si el método tuvo éxito.
WEAVE_ERROR_TLV_UNDERRUN
Si la codificación TLV subyacente finalizó de manera prematura.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Si el actualizador encontró un tipo de elemento TLV no válido o incompatible.
WEAVE_ERROR_INVALID_TLV_TAG
Si el actualizador encontró una etiqueta TLV en un contexto no válido
other
Cualquier otro código de error de Weave o plataforma que muestre TLVWriter::EndContainer() o TLVReader::ExitContainer()

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
[in] buf
Un puntero para un búfer que contiene los datos TLV que se editarán.
[in] dataLen
La longitud de los datos TLV en el búfer.
[in] maxLen
La longitud total del búfer.
Valores de retorno
WEAVE_NO_ERROR
Si el método tuvo éxito.
WEAVE_ERROR_INVALID_ARGUMENT
Si la dirección del búfer no es válida.
WEAVE_ERROR_BUFFER_TOO_SMALL
Si el búfer es demasiado pequeño.

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
[in,out] aReader
Es la referencia a un objeto TLVReader que se destruirá antes de devolverse.
[in] freeLen
La longitud del espacio libre (en bytes) disponible en el búfer de datos precodificados.
Valores de retorno
WEAVE_NO_ERROR
Si el método tuvo éxito.
WEAVE_ERROR_INVALID_ARGUMENT
Si la dirección del búfer no es válida.
WEAVE_ERROR_NOT_IMPLEMENTED
Si el lector se inicializó en una cadena de búferes.

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
WEAVE_NO_ERROR
Si el lector TLVUpdater se colocó correctamente en un elemento nuevo
WEAVE_END_OF_TLV
Si el lector de TLVUpdater apunta al final del contenedor.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Si el lector del TLVIpdater no está posicionado en un elemento TLV válido.
other
Muestra otros códigos de error que muestra el método TLVReader::Skip().

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
WEAVE_NO_ERROR
Si el lector TLVUpdater se colocó correctamente en un elemento nuevo
other
Devuelve los códigos de error de Weave o de la plataforma que muestran los métodos TLVReader::Skip() y TLVReader::Next().

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
[in] profileId
Es el ID de perfil de las etiquetas que se deben codificar de forma implícita.

StartContainer

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

VerifyEndOfContainer

WEAVE_ERROR VerifyEndOfContainer(
  void
)