nl::Weave::TLV::TLVUpdater

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

Fornece uma interface unificada de leitor/gravador para edição/adição/exclusão de elementos na codificação TLV.

Resumo

O TLVUpdater é uma união dos objetos TLVReader e TLVWriter e fornece métodos de interface para editar/excluir dados em uma codificação, bem como adicionar novos elementos à codificação TLV. O objeto TLVUpdater atua essencialmente como dois cursores: um para ler a codificação existente e outro para gravar (seja para copiar dados existentes ou gravar novos dados).

Semanticamente, o objeto TLVUpdater funciona como uma união de TLVReader e TLVWriter. Os métodos TLVUpdater têm significados mais ou menos semelhantes aos dos métodos semelhantes em TLVReader/TLVWriter. Quando houver diferenças na semântica, elas estão claramente documentadas na seção de comentários da função em WeaveTLVUpdater.cpp.

Uma observação particularmente importante sobre os métodos PutBytes() e PutString() do TLVUpdater é que ele pode deixar a codificação em um estado corrompido com apenas o cabeçalho do elemento escrito quando ocorre um estouro. Os aplicativos podem chamar GetRESTFreeLength() para garantir que haja aproximadamente espaço livre suficiente para gravar a codificação. Observe que o Get exibindoFreeLength() informa somente os bytes sem custo financeiro disponíveis, e não há como o aplicativo saber o tamanho dos dados codificados que são gravados. No caso de estouro, PutBytes() e PutString() retornarão WEAVE_ERROR_BUFFER_TOO_ reduzir para o autor da chamada.

Além disso, observe que o método Next() é sobrecarregado para pular o elemento atual e também avançar o leitor interno para o próximo elemento. Como pular elementos já codificados requer a mudança das variáveis de estado de espaço livre do gravador interno para contabilizar o novo espaço liberado (disponibilizado ao pular), espera-se que o aplicativo chame Next() no atualizador depois de um método Get() cujo valor ele não quer gravar (o que é equivalente a pular o elemento atual).

Funções 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 um objeto TLVUpdater para ler elementos de um contêiner.
ExitContainer(TLVType outerContainerType)
Completa a leitura de um elemento de contêiner TLV e codifica uma extremidade do elemento TLV na saída 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)
Inicialize um objeto TLVUpdater para editar um único buffer de entrada.
Init(TLVReader & aReader, uint32_t freeLen)
Inicialize um objeto TLVUpdater usando um TLVReader.
Move(void)
Copia o elemento atual da entrada TLV para a saída TLV.
MoveUntilEnd(void)
void
Mova tudo do ponto de leitura atual de TLVUpdater até o fim do buffer TLV de entrada para a saída.
Next(void)
Pule o elemento atual e avance o objeto TLVUpdater para o próximo elemento na entrada TLV.
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
Defina o ID do perfil implícito para o objeto TLVUpdater.
StartContainer(uint64_t tag, TLVType containerType, TLVType & outerContainerType)
VerifyEndOfContainer(void)

Funções 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 um objeto TLVUpdater para ler elementos de um contêiner.

Ele também codifica um início de objeto de contêiner na saída TLV.

O método EnterContainer() prepara o objeto TLVUpdater atual para começar a ler os elementos membros de um contêiner TLV (uma estrutura, matriz ou caminho). Para cada chamada para EnterContainer(), os aplicativos devem fazer uma chamada correspondente para ExitContainer().

Quando EnterContainer() é chamado, o leitor de TLVUpdater precisa estar posicionado no elemento do contêiner. O método usa como argumento uma referência a um valor TLVType que será usado para salvar o contexto do atualizador enquanto ele lê o contêiner.

Quando o método EnterContainer() retorna, o atualizador é posicionado imediatamente antes do primeiro membro do contêiner. Chamar Next() repetidamente avançará o atualizador por meio dos membros da coleção até que o final seja atingido. Nesse momento, o atualizador retornará WEAVE_END_OF_TLV.

Depois que o aplicativo termina de ler um contêiner, ele pode continuar lendo os elementos depois do contêiner chamando o método ExitContainer().

Detalhes
Parâmetros
[out] outerContainerType
Uma referência a um valor TLVType que receberá o contexto do atualizador.
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_INCORRECT_STATE
Se o leitor TLVUpdater não estiver posicionado em um elemento de contêiner.
other
Qualquer outro código de erro do Weave ou da plataforma retornado por TLVWriter::StartContainer() ou TLVReader::EnterContainer().

ExitContainer

WEAVE_ERROR ExitContainer(
  TLVType outerContainerType
)

Completa a leitura de um elemento de contêiner TLV e codifica uma extremidade do elemento TLV na saída TLV.

O método ExitContainer() restaura o estado de um objeto TLVUpdater após uma chamada para EnterContainer(). A cada chamada para EnterContainer(), os aplicativos devem fazer uma chamada correspondente para ExitContainer(), transmitindo o valor de contexto retornado pelo método EnterContainer().

Quando ExitContainer() retorna, o leitor TLVUpdater é posicionado imediatamente antes do primeiro elemento que segue o contêiner no TLV de entrada. A partir desse ponto, os aplicativos podem chamar Next() para avançar pelos elementos restantes.

Depois que EnterContainer() é chamado, os aplicativos podem chamar ExitContainer() no atualizador a qualquer momento, independentemente de todos os elementos no contêiner subjacente terem sido lidos. Além disso, chamar ExitContainer() antes de ler todos os elementos no contêiner fará com que o contêiner atualizado fique truncado na saída TLV.

Detalhes
Parâmetros
[in] outerContainerType
O valor de TLVType retornado pelo método EnterContainer().
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_TLV_UNDERRUN
Se a codificação TLV subjacente foi encerrada prematuramente.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Se o atualizador encontrou um tipo de elemento TLV inválido ou incompatível.
WEAVE_ERROR_INVALID_TLV_TAG
Se o atualizador encontrou uma tag TLV em um contexto inválido.
other
Qualquer outro código de erro do Weave ou da plataforma retornado por TLVWriter::EndContainer() ou TLVReader::ExitContainer().

Finalizar

WEAVE_ERROR Finalize(
  void
)

Get

WEAVE_ERROR Get(
  bool & v
)

Get

WEAVE_ERROR Get(
  int8_t & v
)

Get

WEAVE_ERROR Get(
  int16_t & v
)

Get

WEAVE_ERROR Get(
  int32_t & v
)

Get

WEAVE_ERROR Get(
  int64_t & v
)

Get

WEAVE_ERROR Get(
  uint8_t & v
)

Get

WEAVE_ERROR Get(
  uint16_t & v
)

Get

WEAVE_ERROR Get(
  uint32_t & v
)

Get

WEAVE_ERROR Get(
  uint64_t & v
)

Get

WEAVE_ERROR Get(
  float & v
)

Get

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
)

Inicialize um objeto TLVUpdater para editar um único buffer de entrada.

Ao chamar esse método, os dados de TLV no buffer são movidos para o final do buffer, e um objeto TLVReader particular é inicializado nesse buffer realocado. Um objeto TLVWriter particular também é inicializado no espaço livre que agora está disponível no início. Os aplicativos podem usar o objeto TLVUpdater para analisar os dados de TLV e modificar/excluir elementos existentes ou adicionar novos elementos à codificação.

Detalhes
Parâmetros
[in] buf
Um ponteiro para um buffer que contém os dados de TLV a serem editados.
[in] dataLen
O tamanho dos dados de TLV no buffer.
[in] maxLen
O comprimento total do buffer.
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_INVALID_ARGUMENT
Se o endereço do buffer for inválido.
WEAVE_ERROR_BUFFER_TOO_SMALL
Se o buffer for muito pequeno.

Init

WEAVE_ERROR Init(
  TLVReader & aReader,
  uint32_t freeLen
)

Inicialize um objeto TLVUpdater usando um TLVReader.

Ao chamar esse método, os dados TLV no buffer apontados pelo TLVReader são movidos do ponto de leitura atual para o final do buffer. Um novo objeto TLVReader particular é inicializado para ler nesse novo local, enquanto um novo objeto TLVWriter particular é inicializado para gravar no espaço liberado do buffer.

Se o TLVReader já estiver posicionado "em" um elemento, primeiro ele será retirado do início desse elemento. Observe também que essa retirada funciona bem com elementos de contêiner, ou seja, se o TLVReader já tiver sido usado para chamar EnterContainer(), não há nada para retirar. Mas, se o TLVReader foi posicionado no elemento de contêiner e EnterContainer() ainda não foi chamado, o objeto TLVReader é enviado para o início do cabeçalho do contêiner.

O objeto TLVReader de entrada será destruído antes do retorno, e o aplicativo não deve usá-lo ao retornar.

Detalhes
Parâmetros
[in,out] aReader
Referência a um objeto TLVReader que será destruído antes de retornar.
[in] freeLen
O tamanho do espaço livre (em bytes) disponível no buffer de dados pré-codificado.
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_INVALID_ARGUMENT
Se o endereço do buffer for inválido.
WEAVE_ERROR_NOT_IMPLEMENTED
Se o leitor foi inicializado em uma cadeia de buffers.

Mover

WEAVE_ERROR Move(
  void
)

Copia o elemento atual da entrada TLV para a saída TLV.

O método Move() copia o elemento atual em que o leitor de TLVUpdater está posicionado no gravador do TLVUpdater. O aplicativo precisa chamar Next() e posicionar o leitor do TLVUpdater em um elemento antes de chamar esse método. Assim como o método TLVReader::Next(), se o leitor estiver posicionado em um elemento contêiner no momento da chamada, todos os membros do contêiner serão copiados. Se o leitor não estiver posicionado em nenhum elemento, a chamada desse método não vai mudar.

Detalhes
Valores de retorno
WEAVE_NO_ERROR
Se o leitor TLVUpdater tiver sido posicionado com sucesso em um novo elemento.
WEAVE_END_OF_TLV
Se o leitor do TLVUpdater estiver apontando para o fim do contêiner.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Se o leitor do TLVIpdate não estiver posicionado em um elemento TLV válido.
other
Retorna outros códigos de erro retornados pelo método TLVReader::Skip().

MoveUntilEnd

void MoveUntilEnd(
  void
)

Mova tudo do ponto de leitura atual de TLVUpdater até o fim do buffer TLV de entrada para a saída.

Esse método permite mover tudo do ponto de leitura atual do TLVUpdater até o final do buffer do leitor para o gravador do TLVUpdater.

Próxima

WEAVE_ERROR Next(
  void
)

Pule o elemento atual e avance o objeto TLVUpdater para o próximo elemento na entrada TLV.

O método Next() ignora o elemento atual no TLV de entrada e avança o leitor do TLVUpdater para o próximo elemento que reside no mesmo contexto de contenção. Se o leitor estiver posicionado no nível mais externo de uma codificação TLV, chamar Next() vai avançá-lo para o próximo elemento na parte superior. Se o leitor estiver posicionado em um elemento de contêiner TLV (uma estrutura, matriz ou caminho), chamar Next() vai levá-lo para o próximo elemento membro do contêiner.

Como Next() restringe o movimento do leitor ao contexto de contenção atual, chamar Next() quando o leitor estiver posicionado em um elemento de contêiner avançará sobre o contêiner, ignorando os elementos membros (e os membros de qualquer contêiner aninhado) até alcançar o primeiro elemento depois do contêiner.

Quando não há mais elementos dentro de um contexto de contenção específico, o método Next() retorna um erro WEAVE_END_OF_TLV e a posição do leitor permanece inalterada.

Detalhes
Valores de retorno
WEAVE_NO_ERROR
Se o leitor TLVUpdater tiver sido posicionado com sucesso em um novo elemento.
other
Retorna os códigos de erro do Weave ou da plataforma retornados pelo método TLVReader::Skip() e 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
)

Defina o ID do perfil implícito para o objeto TLVUpdater.

Esse método define o ID implícito do perfil para o objeto TLVUpdater. Quando o atualizador for solicitado a codificar um novo elemento, se o ID de perfil da tag associada ao novo elemento corresponder ao valor de profileId, o atualizador codificará a tag de forma implícita, omitindo o ID de perfil no processo.

Detalhes
Parâmetros
[in] profileId
O ID do perfil das tags que devem ser codificadas de forma implícita.

StartContainer

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

VerifyEndOfContainer

WEAVE_ERROR VerifyEndOfContainer(
  void
)