nl:: Weave:: TLV:: TLVUpdater
#include <src/lib/core/WeaveTLV.h>
Fornece uma interface unificada de leitor/gravador para editar/adicionar/excluir 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, além de adicionar novos elementos à codificação TLV. O objeto TLVUpdater age basicamente como dois cursores, um para ler a codificação existente e outro para gravar (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 parecidos com relação aos equivalentes com nomes semelhantes em TLVReader/TLVWriter. Quando houver diferenças na semântica, elas serã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 eles podem deixar a codificação em um estado corrompido apenas com o cabeçalho do elemento gravado quando ocorre um estouro. Os aplicativos podem chamar GetResFreeLength() para garantir que haja espaço livre aproximadamente suficiente para gravar a codificação. Observe que GetResFreeLength() informa apenas os bytes livres disponíveis e não há como o aplicativo saber o comprimento dos dados codificados que são gravados. No caso de um estouro, PutBytes() e PutString() retornam WEAVE_ERROR_BUFFER_TOO_small ao autor da chamada.
Além disso, o método Next() está 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 alteração das variáveis de estado de espaço livre do gravador interno para considerar o novo espaço liberado (disponibilizado ao pular), é esperado que o aplicativo chame Next() no atualizador após um método Get() cujo valor não queira escrever de volta (o que equivale a ignorar 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)
|
|
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)
|
|
MoveUntilEnd(void)
|
void
Mova tudo do ponto de leitura atual do TLVUpdater até o fim do buffer TLV de entrada para a saída.
|
Next(void)
|
Ignora 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 do objeto de contêiner na TLV de saída.
O método EnterContainer() prepara o objeto TLVUpdater atual para começar a ler os elementos de um contêiner TLV (uma estrutura, matriz ou caminho). Para cada chamada para EnterContainer(), os aplicativos precisam fazer uma chamada correspondente para ExitContainer().
Quando EnterContainer() é chamado, o leitor do TLVUpdater precisa ser 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 lê o contêiner.
Quando o método EnterContainer() retorna, o atualizador é posicionado imediatamente antes do primeiro membro do contêiner. Chamar Next() repetidamente vai avançar o atualizador entre os membros da coleção até chegar ao fim. Nesse momento, o atualizador retornará WEAVE_END_OF_TLV.
Depois que o aplicativo terminar de ler um contêiner, ele poderá continuar lendo os elementos após o contêiner chamando o método ExitContainer().
Detalhes | |||||||
---|---|---|---|---|---|---|---|
Parâmetros |
|
||||||
Valores de retorno |
|
ExitContainer
WEAVE_ERROR ExitContainer( TLVType outerContainerType )
Completa a leitura de um elemento de contêiner TLV e codifica um final de elemento TLV na saída TLV.
O método ExitContainer() restaura o estado de um objeto TLVUpdater após uma chamada para EnterContainer(). Para cada chamada para EnterContainer(), os aplicativos precisam 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 na entrada TLV. A partir desse ponto, os aplicativos podem chamar Next() para avançar pelos elementos restantes.
Uma vez 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 TLV de saída.
Detalhes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Parâmetros |
|
||||||||||
Valores de retorno |
|
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 TLV do buffer são movidos para o fim do buffer, e um objeto TLVReader particular é inicializado no 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 TLV e modificar/excluir elementos existentes ou adicionar novos elementos à codificação.
Detalhes | |||||||
---|---|---|---|---|---|---|---|
Parâmetros |
|
||||||
Valores de retorno |
|
Init
WEAVE_ERROR Init( TLVReader & aReader, uint32_t freeLen )
Inicialize um objeto TLVUpdater usando um TLVReader.
Ao chamar esse método, os dados TLV do buffer apontados pelo TLVReader são movidos do ponto de leitura atual para o fim do buffer. Um novo objeto TLVReader é inicializado para ler esse novo local, enquanto um novo objeto TLVWriter particular é inicializado para gravar no espaço do buffer liberado.
Se o TLVReader já estiver posicionado como "ativado", um elemento, ele é primeiro recuado para o início desse elemento. Observe também que essa espera funciona bem com elementos de contêiner, ou seja, se o TLVReader já foi usado para chamar EnterContainer(), não há nada para recuar. No entanto, se o TLVReader tiver sido posicionado no elemento do contêiner e o EnterContainer() ainda não tiver sido chamado, o objeto TLVReader será retirado do início do cabeçalho do contêiner.
O objeto TLVReader de entrada será destruído antes de retornar, e o aplicativo não poderá usar o mesmo ao retornar.
Detalhes | |||||||
---|---|---|---|---|---|---|---|
Parâmetros |
|
||||||
Valores de retorno |
|
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 no qual o leitor do TLVUpdater está posicionado para o gravador do TLVUpdater. O aplicativo deve chamar Next() e posicionar o leitor do TLVUpdater em um elemento antes de chamar esse método. Assim como no método TLVReader::Next(), se o leitor estiver posicionado em um elemento de 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, nada vai mudar ao chamar esse método.
Detalhes | |||||||||
---|---|---|---|---|---|---|---|---|---|
Valores de retorno |
|
MoveUntilEnd
void MoveUntilEnd( void )
Mova tudo do ponto de leitura atual do TLVUpdater até o fim do buffer TLV de entrada para a saída.
Esse método suporta a movimentação de tudo, desde o ponto de leitura atual do TLVUpdater até o final do buffer do leitor, para o gravador do TLVUpdater.
Próxima
WEAVE_ERROR Next( void )
Ignora o elemento atual e avance o objeto TLVUpdater para o próximo elemento na entrada TLV.
O método Next() pula o elemento atual na entrada TLV e avança o leitor do TLVUpdater para o próximo elemento que reside no mesmo contexto de contenção. Em particular, se o leitor estiver posicionado no nível mais externo de uma codificação TLV, chamar Next() o avançará para o próximo elemento no topo. Se o leitor estiver posicionado dentro de um elemento de contêiner TLV (uma estrutura, matriz ou caminho), chamar Next() vai avançar 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, pulando os elementos membros (e os membros de qualquer contêiner aninhado) até alcançar o primeiro elemento após o contêiner.
Quando não houver outros elementos em um contexto de contenção específico, o método Next() retornará um erro WEAVE_END_OF_TLV e a posição do leitor permanecerá inalterada.
Detalhes | |||||
---|---|---|---|---|---|
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 )
Defina o ID do perfil implícito para o objeto TLVUpdater.
Esse método define o ID de perfil implícito para o objeto TLVUpdater. Quando o Updater for solicitado a codificar um novo elemento, se o ID de perfil da tag associada ao novo elemento corresponder ao valor de profileId
, o Updater codificará a tag de forma implícita, omitindo o ID de perfil no processo.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
StartContainer
WEAVE_ERROR StartContainer( uint64_t tag, TLVType containerType, TLVType & outerContainerType )