nl::Weave::TLV::TLVUpdater

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

Proporciona una interfaz de lector y escritor unificada para editar, agregar y borrar elementos en la codificación TLV.

Resumen

El TLVUpdater es una unión de los objetos TLVReader y TLVWriter y proporciona métodos de interfaz para editar o borrar datos en una codificación, además de agregar elementos nuevos a la codificación TLV. En esencia, el objeto TLVUpdater actúa como dos cursores: uno para leer la codificación existente y otro para escribir (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 un estado dañado con solo el encabezado del elemento escrito cuando se produce un desbordamiento. Las aplicaciones pueden llamar a GetRemainingFreeLength() para asegurarse de que haya espacio libre aproximadamente suficiente para escribir la codificación. Ten en cuenta que GetRemainingFreeLength() solo te indica los bytes libres disponibles y que no hay forma de que la aplicación sepa 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 hacer avanzar al lector interno al siguiente elemento. Debido a que omitir elementos ya codificados requiere cambiar las variables de estado de espacio libre del escritor interno para tener en cuenta el nuevo espacio liberado (que está disponible mediante la omisión), se espera que la aplicación llame a Next() en el actualizador después de un método Get() cuyo valor no quiera 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 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 búfer de entrada único.
Init(TLVReader & aReader, uint32_t freeLen)
Inicializa un objeto TLVUpdater con un TLVReader.
Move(void)
Copia el elemento actual del TLV de entrada en el TLV de salida.
MoveUntilEnd(void)
void
Mueve todo desde el punto de lectura actual de TLVUpdater hasta el final del búfer de entrada TLV con el resultado.
Next(void)
Omite el elemento actual y pasa 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
Configura 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 un inicio de objeto de contenedor en el TLV de salida.

El método EnterContainer() prepara el objeto TLVUpdater actual para comenzar a leer los elementos miembro de un contenedor de TLV (una estructura, un array o una ruta). Para cada llamada a EnterContainer(), las aplicaciones deben realizar la llamada correspondiente a ExitContainer().

Cuando se llama a EnterContainer(), el lector del TLVUpdater se debe colocar en el elemento del contenedor. El método toma como argumento una referencia a un valor TLVType que se usará para guardar el contexto del actualizador mientras lee el contenedor.

Cuando se muestra el método EnterContainer(), el actualizador se posiciona justo antes del primer miembro del contenedor. Llamar repetidamente a Next() hará que el actualizador pase por los miembros de la colección hasta llegar al final, momento en el cual el actualizador mostrará WEAVE_END_OF_TLV.

Una vez que la aplicación termina de leer un contenedor, puede continuar leyendo los elementos después de este llamando al método ExitContainer().

Detalles
Parámetros
[out] outerContainerType
Es una referencia a un valor TLVType que recibirá el contexto del actualizador.
Valores que se muestran
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 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 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(). Para cada llamada a EnterContainer(), las aplicaciones deben realizar una llamada correspondiente a ExitContainer() y pasar el valor del contexto que muestra el método EnterContainer().

Cuando se muestra ExitContainer(), el lector TLVUpdater se posiciona justo 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 haya llamado 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 llamar a ExitContainer() antes de leer todos los elementos en el contenedor hará que el contenedor actualizado se trunque en el TLV de salida.

Detalles
Parámetros
[in] outerContainerType
El valor TLVType que mostró el método EnterContainer()
Valores que se muestran
WEAVE_NO_ERROR
Si el método tuvo éxito.
WEAVE_ERROR_TLV_UNDERRUN
Si la codificación TLV subyacente finalizó de forma prematura.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Si el actualizador encontró un tipo de elemento TLV no válido o no compatible
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 de 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 búfer de entrada único.

Cuando se llama a este método, los datos de TLV en el búfer se mueven al final del búfer 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 principio. Las aplicaciones pueden usar el objeto TLVUpdater para analizar los datos de TLV y modificar y borrar elementos existentes, o agregar nuevos a la codificación.

Detalles
Parámetros
[in] buf
Un puntero para un búfer que contiene los datos de TLV que se editarán.
[in] dataLen
La longitud de los datos de TLV en el búfer.
[in] maxLen
Es la longitud total del búfer.
Valores que se muestran
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 de TLV en el búfer al que apunta TLVReader se mueven del punto de lectura actual al final del búfer. Se inicializa un nuevo objeto TLVReader privado para leer desde esta ubicación nueva, mientras que un objeto TLVWriter nuevo privado se inicializa para escribir en el espacio de búfer liberado.

Ten en cuenta que, si TLVReader está posicionado en un elemento, primero se realiza una copia de seguridad al inicio de ese elemento. Además, ten en cuenta que esta copia de seguridad funciona bien con elementos de contenedor, es decir, si TLVReader se usó para llamar a EnterContainer(), no hay nada que retirar. Sin embargo, si TLVReader se colocó en el elemento del contenedor y aún no se llama a EnterContainer(), se realiza una copia de seguridad del objeto TLVReader al inicio del encabezado del contenedor.

El objeto TLVReader de entrada se destruirá antes de regresar y la aplicación no debe usarlo cuando se muestre.

Detalles
Parámetros
[in,out] aReader
Referencia a un objeto TLVReader que se destruirá antes de mostrarse.
[in] freeLen
La longitud del espacio libre (en bytes) disponible en el búfer de datos codificado previamente.
Valores que se muestran
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 del TLV de entrada en el TLV de salida.

El método Move() copia el elemento actual en el que se posiciona el lector 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 cambiará cuando se llame a este método.

Detalles
Valores que se muestran
WEAVE_NO_ERROR
Si el lector TLVUpdater se colocó correctamente en un elemento nuevo
WEAVE_END_OF_TLV
Si el lector del 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 de TLVUpdater hasta el final del búfer de entrada TLV con el resultado.

Este método admite mover todo desde el punto de lectura actual de TLVUpdater hasta el final del búfer de lector hasta el escritor de TLVUpdater.

Siguiente

WEAVE_ERROR Next(
  void
)

Omite el elemento actual y pasa 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 avanzar el lector del TLVUpdater al siguiente elemento que se encuentra 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 hará avanzar al siguiente elemento más arriba. Si el lector se posiciona dentro de un elemento contenedor TLV (una estructura, un array o una ruta), llamar a Next() lo hará avanzar al siguiente elemento miembro del contenedor.

Dado que Next() restringe el movimiento del lector al contexto de contención actual, si se llama a Next() cuando el lector se ubica en un elemento de contenedor, se avanzará sobre el contenedor y se omitirán sus elementos miembros (y los miembros de cualquier contenedor anidado) hasta que llegue al primer elemento después del contenedor.

Cuando no haya más elementos dentro de un contexto de contención particular, el método Next() mostrará un error WEAVE_END_OF_TLV y la posición del lector no cambiará.

Detalles
Valores que se muestran
WEAVE_NO_ERROR
Si el lector TLVUpdater se colocó correctamente en un elemento nuevo
other
Muestra los códigos de error de Weave o plataforma que muestran los métodos TLVReader::Skip() y TLVReader::Next().

con prácticas

WEAVE_ERROR Put(
  uint64_t tag,
  int8_t v
)

con prácticas

WEAVE_ERROR Put(
  uint64_t tag,
  int16_t v
)

con prácticas

WEAVE_ERROR Put(
  uint64_t tag,
  int32_t v
)

con prácticas

WEAVE_ERROR Put(
  uint64_t tag,
  int64_t v
)

con prácticas

WEAVE_ERROR Put(
  uint64_t tag,
  uint8_t v
)

con prácticas

WEAVE_ERROR Put(
  uint64_t tag,
  uint16_t v
)

con prácticas

WEAVE_ERROR Put(
  uint64_t tag,
  uint32_t v
)

con prácticas

WEAVE_ERROR Put(
  uint64_t tag,
  uint64_t v
)

con prácticas

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

con prácticas

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

con prácticas

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

con prácticas

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

con prácticas

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

con prácticas

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

con prácticas

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

con prácticas

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

con prácticas

WEAVE_ERROR Put(
  uint64_t tag,
  float v
)

con prácticas

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
)

Configura 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 nuevo elemento coincide con el valor de profileId, el actualizador codificará la etiqueta en forma implícita, y omitirá el ID de perfil en el proceso.

Detalles
Parámetros
[in] profileId
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
)