nl::Weave::TLV::TLVReader

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

Fornece um analisador com eficiência de memória para dados codificados no formato TLV do Weave.

Resumo

O TLVReader implementa um analisador somente de encaminhamento para o estilo pull dos dados TLV do Weave. O objeto TLVReader opera como um cursor que pode ser usado para iterar uma sequência de elementos TLV e interpretar o conteúdo deles. Quando posicionados em um elemento, os aplicativos podem fazer chamadas para os métodos Get() do leitor para consultar o tipo e a tag do elemento atual e extrair qualquer valor associado. O método Next() do leitor é usado para avançar de um elemento a outro.

Um objeto TLVReader é sempre posicionado antes, sobre ou depois de um elemento TLV. Quando inicializado pela primeira vez, um TLVReader é posicionado imediatamente antes do primeiro elemento da codificação. Para começar a ler, um aplicativo precisa fazer uma chamada inicial ao método Next() para posicionar o leitor no primeiro elemento. Quando um elemento de contêiner é encontrado, seja uma estrutura, uma matriz ou um caminho, os métodos OpenContainer() ou EnterContainer() podem ser usados para iterar o conteúdo do contêiner.

Quando o leitor chega ao final de uma codificação TLV ou ao último elemento dentro de um contêiner, ele sinaliza ao aplicativo retornando um erro WEAVE_END_OF_TLV do método Next(). O leitor continuará retornando WEAVE_END_OF_TLV até que seja reinicializado ou até que o contêiner atual seja encerrado (via CloseContainer() / ExitContainer()).

Um objeto TLVReader pode analisar dados diretamente de um buffer de entrada fixo ou de uma cadeia de um ou mais PackageBuffers. Além disso, os aplicativos podem fornecer uma função GetNextBuffer para alimentar o leitor de uma fonte arbitrária, por exemplo, um soquete ou uma porta serial.

Herança

Subclasses conhecidas diretas:
  nl::Weave::Profiles::DataManagement_Current::CircularEventReader
  nl::Weave::TLV::CircularTLVReader

Tipos públicos

GetNextBufferFunct)(TLVReader &reader, uintptr_t &bufHandle, const uint8_t *&bufStart, uint32_t &bufLen) WEAVE_ERROR(*
Função que pode ser usada para recuperar dados TLV adicionais a serem analisados.

Atributos públicos

AppData
void *
Um campo de ponteiro que pode ser usado para dados específicos do aplicativo.
GetNextBuffer
Um ponteiro para uma função que produzirá dados de entrada para o objeto TLVReader.
ImplicitProfileId
uint32_t
O ID de perfil a ser usado para tags de perfil codificadas de forma implícita.

Atributos protegidos

mBufEnd
const uint8_t *
mBufHandle
uintptr_t
mContainerType
mControlByte
uint16_t
mElemLenOrVal
uint64_t
mElemTag
uint64_t
mLenRead
uint32_t
mMaxLen
uint32_t
mReadPoint
const uint8_t *

Funções públicas

CloseContainer(TLVReader & containerReader)
Conclui a leitura de um contêiner TLV após uma chamada para OpenContainer().
DupBytes(uint8_t *& buf, uint32_t & dataLen)
Aloca e retorna um buffer contendo o valor do byte atual ou da string UTF8.
DupString(char *& buf)
Aloca e retorna um buffer contendo o valor terminado em nulo do byte atual ou da string UTF8.
EnterContainer(TLVType & outerContainerType)
Prepara um objeto TLVReader para ler os membros do elemento de contêiner TLV.
ExitContainer(TLVType outerContainerType)
Conclui a leitura de um contêiner TLV e prepara um objeto TLVReader para ler elementos após o contêiner.
Get(bool & v)
Acessa o valor do elemento atual como um tipo booleano.
Get(int8_t & v)
Receba o valor do elemento atual como um número inteiro assinado de 8 bits.
Get(int16_t & v)
Receba o valor do elemento atual como um número inteiro assinado de 16 bits.
Get(int32_t & v)
Receba o valor do elemento atual como um número inteiro assinado de 32 bits.
Get(int64_t & v)
Receba o valor do elemento atual como um número inteiro assinado de 64 bits.
Get(uint8_t & v)
Receba o valor do elemento atual como um número inteiro não assinado de 8 bits.
Get(uint16_t & v)
Receba o valor do elemento atual como um número inteiro não assinado de 16 bits.
Get(uint32_t & v)
Receba o valor do elemento atual como um número inteiro não assinado de 32 bits.
Get(uint64_t & v)
Receba o valor do elemento atual como um número inteiro não assinado de 64 bits.
Get(float & v)
Get(double & v)
Acessa o valor do elemento atual como um número de ponto flutuante de precisão dupla.
GetBufHandle(void) const
uintptr_t
GetBytes(uint8_t *buf, uint32_t bufSize)
Acessa o valor do byte atual ou do elemento de string UTF8.
GetContainerType(void) const
Retorna o tipo do contêiner em que TLVReader está lendo no momento.
GetControlByte(void) const
uint16_t
Retorna o byte de controle associado ao elemento TLV atual.
GetDataPtr(const uint8_t *& data)
Mostra um ponteiro para o byte inicial codificado de um byte TLV ou um elemento de string UTF8.
GetLength(void) const
uint32_t
Retorna o tamanho dos dados associados ao elemento TLV atual.
GetLengthRead(void) const
uint32_t
Retorna o número total de bytes lidos desde que o leitor foi inicializado.
GetReadPoint(void) const
const uint8_t *
Acessa o ponto no buffer de entrada subjacente que corresponde à posição atual do leitor.
GetRemainingLength(void) const
uint32_t
Retorna o número total de bytes que podem ser lidos até que o tamanho máximo de leitura seja atingido.
GetString(char *buf, uint32_t bufSize)
Recebe o valor do byte atual ou do elemento de string UTF8 como uma string com terminação nula.
GetTag(void) const
uint64_t
Retorna a tag associada ao elemento TLV atual.
GetType(void) const
Retorna o tipo do elemento TLV atual.
Init(const TLVReader & aReader)
void
Inicializa um objeto TLVReader a partir de outro objeto TLVReader.
Init(const uint8_t *data, uint32_t dataLen)
void
Inicializa um objeto TLVReader para ler em um único buffer de entrada.
Init(PacketBuffer *buf, uint32_t maxLen)
void
Inicializa um objeto TLVReader para ler em um único PackageBuffer.
Init(PacketBuffer *buf, uint32_t maxLen, bool allowDiscontiguousBuffers)
void
Inicializa um objeto TLVReader para ler em um ou mais PackageBuffers.
Next(void)
avança o objeto TLVReader para o próximo elemento TLV a ser lido.
Next(TLVType expectedType, uint64_t expectedTag)
Avança o objeto TLVReader para o próximo elemento TLV a ser lido, declarando o tipo e a tag do novo elemento.
OpenContainer(TLVReader & containerReader)
Inicializa um novo objeto TLVReader para ler os membros de um elemento de contêiner TLV.
Skip(void)
avança o objeto TLVReader imediatamente após o elemento TLV atual.
VerifyEndOfContainer(void)
Verifica se o objeto TVLReader está no final de um contêiner TLV.

Funções protegidas

ClearElementState(void)
void
Limpe o estado do TLVReader.
ElementType(void) const
TLVElementType
Esse é um método particular que retorna o TLVElementType de mControlByte.
EnsureData(WEAVE_ERROR noDataErr)
GetElementHeadLength(uint8_t & elemHeadBytes) const
Trata-se de um método privado usado para calcular o comprimento de uma cabeça de elemento TLV.
IsContainerOpen(void) const
bool
ReadData(uint8_t *buf, uint32_t len)
ReadElement(void)
ReadTag(TLVTagControl tagControl, const uint8_t *& p)
uint64_t
SetContainerOpen(bool aContainerOpen)
void
SkipData(void)
Pule todos os dados contidos no TLV atual lendo-o sem um buffer de destino.
SkipToEndOfContainer(void)
VerifyElement(void)

Funções estáticas protegidas

FailGetNextBuffer(TLVReader & reader, uintptr_t & bufHandle, const uint8_t *& bufStart, uint32_t & bufLen)
GetNextPacketBuffer(TLVReader & reader, uintptr_t & bufHandle, const uint8_t *& bufStart, uint32_t & bufLen)

Tipos públicos

GetNextBufferFunct

WEAVE_ERROR(* GetNextBufferFunct)(TLVReader &reader, uintptr_t &bufHandle, const uint8_t *&bufStart, uint32_t &bufLen)

Função que pode ser usada para recuperar dados TLV adicionais a serem analisados.

As funções desse tipo são usadas para alimentar um TLVReader com dados de entrada. Quando chamada, a função precisa produzir dados adicionais para o leitor analisar ou sinalizar a ele que não há mais dados disponíveis.

Detalhes
Parâmetros
[in] reader
Uma referência ao objeto TLVReader que está solicitando dados de entrada.
[in,out] bufHandle
Uma referência a um valor uintptr_t que a função pode usar para armazenar dados de contexto entre chamadas. Esse valor é inicializado como 0 antes da primeira chamada.
[in,out] bufStart
Uma referência a um ponteiro de dados. Ao entrar na função, bufStart aponta para um byte além do último byte de dados TLV consumido pelo leitor. Na saída, o bufStart deve apontar para o primeiro byte dos novos dados TLV a serem analisados. O novo valor do ponteiro pode estar no mesmo buffer que os dados consumidos anteriormente ou pode apontar para um buffer totalmente novo.
[out] bufLen
Uma referência a um número inteiro não assinado que a função precisa definir para o número de bytes de dados TLV que estão sendo retornados. Se o fim dos dados de TLV de entrada tiver sido alcançado, a função deve definir esse valor como 0.
Valores de retorno
WEAVE_NO_ERROR
Se a função produziu com êxito mais dados TLV ou o fim dos dados de entrada foi alcançado (bufLen precisa ser definido como 0 neste caso).
other
Outros códigos de erro do Weave ou específicos da plataforma que indicam a ocorrência de um erro que impede a função de produzir os dados solicitados.

Atributos públicos

AppData

void * AppData

Um campo de ponteiro que pode ser usado para dados específicos do aplicativo.

GetNextBuffer

GetNextBufferFunct GetNextBuffer

Um ponteiro para uma função que produzirá dados de entrada para o objeto TLVReader.

Se definido como NULL (o valor padrão), o leitor vai presumir que não há mais dados de entrada disponíveis.

GetNextBuffer pode ser definido por um aplicativo a qualquer momento, mas normalmente é definido quando o leitor é inicializado.

Consulte a definição do tipo GetNextBufferFunct para ver mais informações sobre como implementar uma função GetNextBuffer.

ImplicitProfileId

uint32_t ImplicitProfileId

O ID de perfil a ser usado para tags de perfil codificadas de forma implícita.

Quando o leitor encontra uma tag específica do perfil que foi codificada de forma implícita, ele usa o valor da propriedade ImplicitProfileId como o ID de perfil presumido para a tag.

Por padrão, a propriedade ImplicitProfileId é definida como kProfileIdNotspecified. Ao decodificar TLV que contém tags codificadas implicitamente, os aplicativos precisam definir ImplicitProfileId antes de ler qualquer elemento TLV com essas tags. O ID de perfil apropriado geralmente depende do contexto do aplicativo ou do protocolo falado.

Se uma tag codificada implicitamente for encontrada enquanto ImplicitProfileId estiver definido como kProfileIdNotspecified, o leitor retornará um erro WEAVE_ERROR_UNKNOWN_IMPLICIT_TLV_TAG.

Atributos protegidos

mBufEnd

const uint8_t * mBufEnd

mBufHandle

uintptr_t mBufHandle

mContainerType

TLVType mContainerType

mControlByte

uint16_t mControlByte

mElemLenOrVal

uint64_t mElemLenOrVal

mElemTag

uint64_t mElemTag

mLenRead

uint32_t mLenRead

mMaxLen

uint32_t mMaxLen

mReadPoint

const uint8_t * mReadPoint

Funções públicas

CloseContainer

WEAVE_ERROR CloseContainer(
  TLVReader & containerReader
)

Conclui a leitura de um contêiner TLV após uma chamada para OpenContainer().

O método CloseContainer() restaura o estado de um objeto TLVReader pai após uma chamada para OpenContainer(). A cada chamada para OpenContainer(), os aplicativos precisam fazer uma chamada correspondente para CloseContainer(), passando uma referência ao mesmo leitor de contêiner para os dois métodos.

Quando CloseContainer() retorna, o leitor pai é posicionado imediatamente antes do primeiro elemento que segue o contêiner. A partir desse ponto, o aplicativo pode usar o método Next() para avançar pelos elementos restantes.

Os aplicativos podem chamar o fechamento CloseContainer() em um leitor pai a qualquer momento, independentemente de todos os elementos no contêiner subjacente terem sido lidos. Depois que CloseContainer() for chamado, o aplicativo deverá considerar o leitor do contêiner "desinicializado" e não poderá usá-lo novamente sem inicializá-lo.

Detalhes
Parâmetros
[in] containerReader
Uma referência ao objeto TLVReader que foi fornecido ao método OpenContainer().
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_INCORRECT_STATE
Se OpenContainer() não tiver sido chamado no leitor ou se o leitor do contêiner não corresponder ao transmitido para o método OpenContainer().
WEAVE_ERROR_TLV_UNDERRUN
Se a codificação TLV subjacente foi encerrada prematuramente.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Se o leitor encontrou um tipo de elemento TLV inválido ou incompatível.
WEAVE_ERROR_INVALID_TLV_TAG
Se o leitor encontrou uma tag TLV em um contexto inválido.
other
Outros códigos de erro do Weave ou da plataforma retornados pela função GetNextBuffer() configurada. Possível apenas quando GetNextBuffer não é NULL.

DupBytes

WEAVE_ERROR DupBytes(
  uint8_t *& buf,
  uint32_t & dataLen
)

Aloca e retorna um buffer contendo o valor do byte atual ou da string UTF8.

Esse método cria um buffer e retorna uma cópia dos dados associados ao elemento de byte ou de string UTF-8 na posição atual. A memória do buffer é recebida com Malloc() e deve ser liberada com free() pelo autor da chamada quando ela não for mais necessária.

Detalhes
Parâmetros
[out] buf
Uma referência a um ponteiro para o qual um buffer alocado por heap de dataLen bytes será atribuído em caso de sucesso.
[out] dataLen
Uma referência ao armazenamento para o tamanho, em bytes, de buf em caso de êxito.
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_WRONG_TLV_TYPE
Se o elemento atual não for um byte TLV ou uma string UTF8, ou o leitor não estiver posicionado em um elemento.
WEAVE_ERROR_NO_MEMORY
Se a memória não puder ser alocada para o buffer de saída.
WEAVE_ERROR_TLV_UNDERRUN
Se a codificação TLV subjacente foi encerrada prematuramente.
WEAVE_ERROR_UNSUPPORTED_WEAVE_FEATURE
Se a plataforma de destino não oferecer suporte para Malloc() e free().
other
Outros códigos de erro do Weave ou da plataforma retornados pela função GetNextBuffer() configurada. Possível apenas quando GetNextBuffer não é NULL.

DupString

WEAVE_ERROR DupString(
  char *& buf
)

Aloca e retorna um buffer contendo o valor terminado em nulo do byte atual ou da string UTF8.

Esse método cria um buffer e retorna uma cópia terminada em nulo dos dados associados ao elemento de byte ou string UTF-8 na posição atual. A memória do buffer é recebida com Malloc() e deve ser liberada com free() pelo autor da chamada quando ela não for mais necessária.

Detalhes
Parâmetros
[out] buf
Uma referência a um ponteiro ao qual um buffer alocado por heap será atribuído em caso de sucesso.
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_WRONG_TLV_TYPE
Se o elemento atual não for um byte TLV ou uma string UTF8, ou o leitor não estiver posicionado em um elemento.
WEAVE_ERROR_NO_MEMORY
Se a memória não puder ser alocada para o buffer de saída.
WEAVE_ERROR_TLV_UNDERRUN
Se a codificação TLV subjacente foi encerrada prematuramente.
WEAVE_ERROR_UNSUPPORTED_WEAVE_FEATURE
Se a plataforma de destino não oferecer suporte para Malloc() e free().
other
Outros códigos de erro do Weave ou da plataforma retornados pela função GetNextBuffer() configurada. Possível apenas quando GetNextBuffer não é NULL.

EnterContainer

WEAVE_ERROR EnterContainer(
  TLVType & outerContainerType
)

Prepara um objeto TLVReader para ler os membros do elemento de contêiner TLV.

O método EnterContainer() prepara o objeto TLVReader 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 objeto TLVReader precisa ser posicionado no elemento contêiner a ser lido. O método usa como argumento uma referência a um valor TLVType que será usado para salvar o contexto do leitor enquanto ele lê o contêiner.

Quando o método EnterContainer() retorna, o leitor é posicionado imediatamente antes do primeiro membro do contêiner. Chamar Next() repetidamente fará o leitor avançar para os membros da coleção até chegar ao fim. Nesse momento, o leitor 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 leitor.
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_INCORRECT_STATE
Se o elemento atual não estiver posicionado em um elemento de contêiner.

ExitContainer

WEAVE_ERROR ExitContainer(
  TLVType outerContainerType
)

Conclui a leitura de um contêiner TLV e prepara um objeto TLVReader para ler elementos após o contêiner.

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

Quando ExitContainer() retorna, o leitor é posicionado imediatamente antes do primeiro elemento que segue o contêiner. A partir desse ponto, o aplicativo pode usar o método Next() para avançar pelos elementos restantes.

Depois que EnterContainer() é chamado, os aplicativos podem chamar ExitContainer() em um leitor a qualquer momento, independentemente de todos os elementos no contêiner subjacente terem sido lidos.

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_INCORRECT_STATE
Se OpenContainer() não tiver sido chamado no leitor ou se o leitor do contêiner não corresponder ao transmitido para o método OpenContainer().
WEAVE_ERROR_TLV_UNDERRUN
Se a codificação TLV subjacente foi encerrada prematuramente.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Se o leitor encontrou um tipo de elemento TLV inválido ou incompatível.
WEAVE_ERROR_INVALID_TLV_TAG
Se o leitor encontrou uma tag TLV em um contexto inválido.
other
Outros códigos de erro do Weave ou da plataforma retornados pela função GetNextBuffer() configurada. Possível apenas quando GetNextBuffer não é NULL.

Get

WEAVE_ERROR Get(
  bool & v
)

Acessa o valor do elemento atual como um tipo booleano.

Detalhes
Parâmetros
[out] v
Recebe o valor associado ao elemento TLV atual.
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_WRONG_TLV_TYPE
Se o elemento atual não for um tipo booleano TLV ou o leitor não estiver posicionado em um elemento.

Get

WEAVE_ERROR Get(
  int8_t & v
)

Receba o valor do elemento atual como um número inteiro assinado de 8 bits.

Se o valor inteiro codificado for maior que o tipo de dados de saída, o valor resultante será truncado.

Detalhes
Parâmetros
[out] v
Recebe o valor associado ao elemento TLV atual.
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_WRONG_TLV_TYPE
Se o elemento atual não for um tipo inteiro TLV (assinado ou não) ou se o leitor não estiver posicionado em um elemento.

Get

WEAVE_ERROR Get(
  int16_t & v
)

Receba o valor do elemento atual como um número inteiro assinado de 16 bits.

Se o valor inteiro codificado for maior que o tipo de dados de saída, o valor resultante será truncado.

Detalhes
Parâmetros
[out] v
Recebe o valor associado ao elemento TLV atual.
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_WRONG_TLV_TYPE
Se o elemento atual não for um tipo inteiro TLV (assinado ou não) ou se o leitor não estiver posicionado em um elemento.

Get

WEAVE_ERROR Get(
  int32_t & v
)

Receba o valor do elemento atual como um número inteiro assinado de 32 bits.

Se o valor inteiro codificado for maior que o tipo de dados de saída, o valor resultante será truncado.

Detalhes
Parâmetros
[out] v
Recebe o valor associado ao elemento TLV atual.
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_WRONG_TLV_TYPE
Se o elemento atual não for um tipo inteiro TLV (assinado ou não) ou se o leitor não estiver posicionado em um elemento.

Get

WEAVE_ERROR Get(
  int64_t & v
)

Receba o valor do elemento atual como um número inteiro assinado de 64 bits.

Se o valor inteiro codificado for maior que o tipo de dados de saída, o valor resultante será truncado.

Detalhes
Parâmetros
[out] v
Recebe o valor associado ao elemento TLV atual.
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_WRONG_TLV_TYPE
Se o elemento atual não for um tipo inteiro TLV (assinado ou não) ou se o leitor não estiver posicionado em um elemento.

Get

WEAVE_ERROR Get(
  uint8_t & v
)

Receba o valor do elemento atual como um número inteiro não assinado de 8 bits.

Se o valor inteiro codificado for maior que o tipo de dados de saída, o valor resultante será truncado. Da mesma forma, se o valor inteiro codificado for negativo, o valor será convertido em sem sinal.

Detalhes
Parâmetros
[out] v
Recebe o valor associado ao elemento TLV atual.
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_WRONG_TLV_TYPE
Se o elemento atual não for um tipo inteiro TLV (assinado ou não) ou se o leitor não estiver posicionado em um elemento.

Get

WEAVE_ERROR Get(
  uint16_t & v
)

Receba o valor do elemento atual como um número inteiro não assinado de 16 bits.

Se o valor inteiro codificado for maior que o tipo de dados de saída, o valor resultante será truncado. Da mesma forma, se o valor inteiro codificado for negativo, o valor será convertido em sem sinal.

Detalhes
Parâmetros
[out] v
Recebe o valor associado ao elemento TLV atual.
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_WRONG_TLV_TYPE
Se o elemento atual não for um tipo inteiro TLV (assinado ou não) ou se o leitor não estiver posicionado em um elemento.

Get

WEAVE_ERROR Get(
  uint32_t & v
)

Receba o valor do elemento atual como um número inteiro não assinado de 32 bits.

Se o valor inteiro codificado for maior que o tipo de dados de saída, o valor resultante será truncado. Da mesma forma, se o valor inteiro codificado for negativo, o valor será convertido em sem sinal.

Detalhes
Parâmetros
[out] v
Recebe o valor associado ao elemento TLV atual.
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_WRONG_TLV_TYPE
Se o elemento atual não for um tipo inteiro TLV (assinado ou não) ou se o leitor não estiver posicionado em um elemento.

Get

WEAVE_ERROR Get(
  uint64_t & v
)

Receba o valor do elemento atual como um número inteiro não assinado de 64 bits.

Se o valor inteiro codificado for negativo, o valor será convertido em sem sinal.

Detalhes
Parâmetros
[out] v
Recebe o valor associado ao elemento TLV atual.
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_WRONG_TLV_TYPE
Se o elemento atual não for um tipo inteiro TLV (assinado ou não) ou se o leitor não estiver posicionado em um elemento.

Get

WEAVE_ERROR Get(
  float & v
)

Get

WEAVE_ERROR Get(
  double & v
)

Acessa o valor do elemento atual como um número de ponto flutuante de precisão dupla.

Detalhes
Parâmetros
[out] v
Recebe o valor associado ao elemento TLV atual.
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_WRONG_TLV_TYPE
Se o elemento atual não for um tipo de ponto flutuante TLV ou se o leitor não estiver posicionado em um elemento.

GetBufHandle

uintptr_t GetBufHandle(
  void
) const 

GetBytes

WEAVE_ERROR GetBytes(
  uint8_t *buf,
  uint32_t bufSize
)

Acessa o valor do byte atual ou do elemento de string UTF8.

Para determinar o tamanho necessário do buffer de entrada, chame o método GetLength() antes de chamar GetBytes().

Detalhes
Parâmetros
[in] buf
Um ponteiro para um buffer para receber os dados da string.
[in] bufSize
O tamanho em bytes do buffer apontado por buf.
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_WRONG_TLV_TYPE
Se o elemento atual não for um byte TLV ou uma string UTF8, ou o leitor não estiver posicionado em um elemento.
WEAVE_ERROR_BUFFER_TOO_SMALL
Se o buffer fornecido for muito pequeno para conter os dados associados ao elemento atual.
WEAVE_ERROR_TLV_UNDERRUN
Se a codificação TLV subjacente foi encerrada prematuramente.
other
Outros códigos de erro do Weave ou da plataforma retornados pela função GetNextBuffer() configurada. Possível apenas quando GetNextBuffer não é NULL.

GetContainerType

TLVType GetContainerType(
  void
) const 

Retorna o tipo do contêiner em que TLVReader está lendo no momento.

O método GetContainerType() retorna o tipo do contêiner TLV em que o TLVReader está lendo. Se o TLVReader estiver posicionado no nível mais externo de uma codificação TLV (ou seja, antes, no ou depois do elemento TLV mais externo), o método retornará kTLVType_NotSpecified.

Detalhes
Retorna
O TLVType do contêiner atual ou kTLVType_Notspecified se o TLVReader não estiver posicionado em um contêiner.

GetControlByte

uint16_t GetControlByte(
  void
) const 

Retorna o byte de controle associado ao elemento TLV atual.

O ideal é que ninguém precise conhecer o byte de controle e apenas a implementação interna de TLV terá acesso a ele. No entanto, ter acesso ao byte de controle é útil para fins de depuração pelos Utilitários dedepuraçãode TLV, que tentam decodificar o byte de controle da tag ao imprimir o conteúdo do buffer TLV.

Detalhes
Retorna
Um número inteiro não assinado que contém o byte de controle associado ao elemento TLV atual. kTLVControlByte_Notspecified será retornado se o leitor não estiver posicionado em um elemento.

GetDataPtr

WEAVE_ERROR GetDataPtr(
  const uint8_t *& data
)

Mostra um ponteiro para o byte inicial codificado de um byte TLV ou um elemento de string UTF8.

Esse método retorna um ponteiro direto para o valor da string codificada no buffer de entrada subjacente. Para ter sucesso, o método exige que todo o valor da string esteja presente em um único buffer. Caso contrário, o método retornará WEAVE_ERROR_TLV_UNDERRUN. Isso torna o método de uso limitado ao ler dados de vários buffers descontínuos.

Detalhes
Parâmetros
[out] data
Uma referência a um ponteiro constante que receberá um ponteiro para os dados de string subjacentes.
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_WRONG_TLV_TYPE
Se o elemento atual não for um byte TLV ou uma string UTF8, ou o leitor não estiver posicionado em um elemento.
WEAVE_ERROR_TLV_UNDERRUN
Se a codificação TLV subjacente foi encerrada prematuramente ou o valor do elemento da string atual não estiver contido em um único buffer contíguo.
other
Outros códigos de erro do Weave ou da plataforma retornados pela função GetNextBuffer() configurada. Possível apenas quando GetNextBuffer não é NULL.

GetLength

uint32_t GetLength(
  void
) const 

Retorna o tamanho dos dados associados ao elemento TLV atual.

O comprimento dos dados só se aplica a elementos do tipo string UTF8 ou de bytes. Para strings UTF8, o valor retornado é o número de bytes da string, não o número de caracteres.

Detalhes
Retorna
O tamanho (em bytes) dos dados associados ao elemento TLV atual, ou 0 se o elemento atual não for uma string UTF8 ou de bytes, ou se o leitor não estiver posicionado em um elemento.

GetLengthRead

uint32_t GetLengthRead(
  void
) const 

Retorna o número total de bytes lidos desde que o leitor foi inicializado.

Detalhes
Retorna
Número total de bytes lidos desde que o leitor foi inicializado.

GetReadPoint

const uint8_t * GetReadPoint(
  void
) const 

Acessa o ponto no buffer de entrada subjacente que corresponde à posição atual do leitor.

Detalhes
Retorna
Um ponteiro para o buffer de entrada subjacente que corresponde à posição atual do leitor.

GetRemainingLength

uint32_t GetRemainingLength(
  void
) const 

Retorna o número total de bytes que podem ser lidos até que o tamanho máximo de leitura seja atingido.

Detalhes
Retorna
Número total de bytes que podem ser lidos até que o tamanho máximo de leitura seja atingido.

GetString

WEAVE_ERROR GetString(
  char *buf,
  uint32_t bufSize
)

Recebe o valor do byte atual ou do elemento de string UTF8 como uma string com terminação nula.

Para determinar o tamanho necessário do buffer de entrada, chame o método GetLength() antes de chamar GetBytes(). O buffer de entrada precisa ter pelo menos um byte maior que o comprimento da string para acomodar o caractere nulo.

Detalhes
Parâmetros
[in] buf
Um ponteiro para um buffer para receber os dados da string de bytes.
[in] bufSize
O tamanho em bytes do buffer apontado por buf.
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_WRONG_TLV_TYPE
Se o elemento atual não for um byte TLV ou uma string UTF8, ou o leitor não estiver posicionado em um elemento.
WEAVE_ERROR_BUFFER_TOO_SMALL
Se o buffer fornecido for muito pequeno para conter os dados associados ao elemento atual.
WEAVE_ERROR_TLV_UNDERRUN
Se a codificação TLV subjacente foi encerrada prematuramente.
other
Outros códigos de erro do Weave ou da plataforma retornados pela função GetNextBuffer() configurada. Possível apenas quando GetNextBuffer não é NULL.

GetTag

uint64_t GetTag(
  void
) const 

Retorna a tag associada ao elemento TLV atual.

O valor retornado por GetTag() pode ser usado com as funções utilitárias de tag (IsProfileTag(), IsContextTag(), ProfileIdFromTag() etc.) para determinar o tipo de tag e extrair vários valores de campo dela.

Detalhes
Retorna
Um número inteiro sem assinatura contendo informações sobre a tag associada ao elemento TLV atual.

GetType

TLVType GetType(
  void
) const 

Retorna o tipo do elemento TLV atual.

Detalhes
Retorna
Um valor de TLVType que descreve o tipo de dados do elemento TLV atual. Se o leitor não estiver posicionado em um elemento TLV, o valor de retorno será kTLVType_Notspecified.

Init

void Init(
  const TLVReader & aReader
)

Inicializa um objeto TLVReader a partir de outro objeto TLVReader.

Detalhes
Parâmetros
[in] aReader
Uma referência somente leitura ao TLVReader para inicializar isso.

Init

void Init(
  const uint8_t *data,
  uint32_t dataLen
)

Inicializa um objeto TLVReader para ler em um único buffer de entrada.

Detalhes
Parâmetros
[in] data
Um ponteiro para um buffer que contém os dados de TLV a serem analisados.
[in] dataLen
O tamanho dos dados de TLV a serem analisados.

Init

void Init(
  PacketBuffer *buf,
  uint32_t maxLen
)

Inicializa um objeto TLVReader para ler em um único PackageBuffer.

A análise começa na posição inicial do buffer (buf->DataStart()) e continua até o fim dos dados no buffer (conforme indicado por buf->Datalen()), ou até que os bytes maxLen tenham sido analisados.

Detalhes
Parâmetros
[in] buf
Um ponteiro para um PackageBuffer que contém os dados de TLV a serem analisados.
[in] maxLen
O máximo de bytes para análise. O padrão é a quantidade de dados no buffer de entrada.

Init

void Init(
  PacketBuffer *buf,
  uint32_t maxLen,
  bool allowDiscontiguousBuffers
)

Inicializa um objeto TLVReader para ler em um ou mais PackageBuffers.

A análise começa na posição inicial do buffer inicial (buf->DataStart()). Se allowDiscontiguousBuffers for verdadeiro, o leitor avançará pela cadeia de buffers vinculados pelos ponteiros Next(). A análise continua até que todos os dados na cadeia do buffer tenham sido consumidos (conforme indicado por buf->Datalen()) ou até que os bytes maxLen tenham sido analisados.

Detalhes
Parâmetros
[in] buf
Um ponteiro para um PackageBuffer que contém os dados de TLV a serem analisados.
[in] maxLen
O máximo de bytes para análise. O padrão é a quantidade total de dados na cadeia do buffer de entrada.
[in] allowDiscontiguousBuffers
Se verdadeiro, avança para o próximo buffer na cadeia depois que todos os dados no buffer atual tiverem sido consumidos. Se for falso, pare de analisar no final do buffer inicial.

Próxima

WEAVE_ERROR Next(
  void
)

avança o objeto TLVReader para o próximo elemento TLV a ser lido.

O método Next() posiciona o objeto do leitor no próximo elemento em uma codificação TLV 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 levar o leitor para o próximo elemento superior. Se o leitor estiver posicionado dentro de um elemento de contêiner TLV (uma estrutura, matriz ou caminho), chamar Next() vai fazer o leitor 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, 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 foi posicionado com sucesso em um novo elemento.
WEAVE_END_OF_TLV
Se não houver mais elementos disponíveis.
WEAVE_ERROR_TLV_UNDERRUN
Se a codificação TLV subjacente foi encerrada prematuramente.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Se o leitor encontrou um tipo de elemento TLV inválido ou incompatível.
WEAVE_ERROR_INVALID_TLV_TAG
Se o leitor encontrou uma tag TLV em um contexto inválido.
WEAVE_ERROR_UNKNOWN_IMPLICIT_TLV_TAG
Se o leitor encontrou uma tag TLV codificada implicitamente para a qual o ID do perfil correspondente é desconhecido.
other
Outros códigos de erro do Weave ou da plataforma retornados pela função GetNextBuffer() configurada. Possível apenas quando GetNextBuffer não é NULL.

Próxima

WEAVE_ERROR Next(
  TLVType expectedType,
  uint64_t expectedTag
)

Avança o objeto TLVReader para o próximo elemento TLV a ser lido, declarando o tipo e a tag do novo elemento.

O método Next(TLVTypeexpectedType, uint64_texpectedTag) é um método de conveniência que tem o mesmo comportamento que Next(), mas também verifica se o tipo e a tag do novo elemento TLV correspondem aos argumentos fornecidos.

Detalhes
Parâmetros
[in] expectedType
O tipo de dados esperado para o próximo elemento.
[in] expectedTag
A tag esperada para o próximo elemento.
Valores de retorno
WEAVE_NO_ERROR
Se o leitor foi posicionado com sucesso em um novo elemento.
WEAVE_END_OF_TLV
Se não houver mais elementos disponíveis.
WEAVE_ERROR_WRONG_TLV_TYPE
Se o tipo do novo elemento não corresponder ao valor do argumento expectedType.
WEAVE_ERROR_UNEXPECTED_TLV_ELEMENT
Se a tag associada ao novo elemento não corresponder ao valor do argumento expectedTag.
WEAVE_ERROR_TLV_UNDERRUN
Se a codificação TLV subjacente foi encerrada prematuramente.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Se o leitor encontrou um tipo de elemento TLV inválido ou incompatível.
WEAVE_ERROR_INVALID_TLV_TAG
Se o leitor encontrou uma tag TLV em um contexto inválido.
other
Outros códigos de erro do Weave ou da plataforma retornados pela função GetNextBuffer() configurada. Possível apenas quando GetNextBuffer não é NULL.

OpenContainer

WEAVE_ERROR OpenContainer(
  TLVReader & containerReader
)

Inicializa um novo objeto TLVReader para ler os membros de um elemento de contêiner TLV.

O método OpenContainer() inicializa um novo objeto TLVReader para ler os elementos membros de um contêiner TLV (uma estrutura, matriz ou caminho). Quando OpenContainer() é chamado, o objeto TLVReader atual precisa estar posicionado no elemento contêiner a ser lido. O método usa como único argumento uma referência a um novo leitor que será inicializado para ler o contêiner. Esse leitor é conhecido como leitor de contêiner, enquanto o leitor em que OpenContainer() é chamado é conhecido como leitor pai.

Quando o método OpenContainer() retorna, o leitor do contêiner é posicionado imediatamente antes do primeiro membro do contêiner. Chamar Next() no leitor do contêiner avançará pelos membros da coleção até chegar ao fim. Nesse momento, o leitor retornará WEAVE_END_OF_TLV.

Enquanto o leitor do contêiner estiver aberto, os aplicativos não poderão fazer chamadas nem alterar o estado do leitor pai. Depois que um aplicativo terminar de usar o leitor de contêiner, ele precisa fechá-lo chamando CloseContainer() no leitor pai, transmitindo o leitor do contêiner como um argumento. Os aplicativos podem fechar o leitor do contêiner a qualquer momento, com ou sem a leitura de todos os elementos contidos no contêiner subjacente. Depois que o leitor de contêiner é fechado, os aplicativos podem continuar usando o leitor pai.

O leitor de contêiner herda várias propriedades de configuração do leitor pai. São estes:

  • O ID de perfil implícito (ImplicitProfileId)
  • O ponteiro de dados do aplicativo (AppData)
  • O ponteiro da função GetNextBuffer

Detalhes
Parâmetros
[out] containerReader
Uma referência a um objeto TLVReader que será inicializado para ler os membros do elemento contêiner atual. Todos os dados associados ao objeto fornecido serão substituídos.
Valores de retorno
WEAVE_NO_ERROR
Se o método tiver sido bem-sucedido,
WEAVE_ERROR_INCORRECT_STATE
Se o elemento atual não estiver posicionado em um elemento de contêiner.

Pular

WEAVE_ERROR Skip(
  void
)

avança o objeto TLVReader imediatamente após o elemento TLV atual.

O método Skip() posiciona o objeto do leitor imediatamente após o elemento TLV atual, de modo que uma chamada subsequente para Next() faça o leitor avançar para o elemento seguinte. Assim como Next(), se o leitor estiver posicionado em um elemento de contêiner no momento da chamada, os membros do contêiner serão ignorados. Se o leitor não estiver posicionado em nenhum elemento, a posição dele vai permanecer inalterada.

Detalhes
Valores de retorno
WEAVE_NO_ERROR
Se o leitor foi posicionado com sucesso em um novo elemento.
WEAVE_END_OF_TLV
Se não houver mais elementos disponíveis.
WEAVE_ERROR_TLV_UNDERRUN
Se a codificação TLV subjacente foi encerrada prematuramente.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Se o leitor encontrou um tipo de elemento TLV inválido ou incompatível.
WEAVE_ERROR_INVALID_TLV_TAG
Se o leitor encontrou uma tag TLV em um contexto inválido.
other
Outros códigos de erro do Weave ou da plataforma retornados pela função GetNextBuffer() configurada. Possível apenas quando GetNextBuffer não é NULL.

VerifyEndOfContainer

WEAVE_ERROR VerifyEndOfContainer(
  void
)

Verifica se o objeto TVLReader está no final de um contêiner TLV.

O método VerifyEndOfContainer() verifica se não há mais elementos TLV a serem lidos no contêiner TLV atual. Esse é um método de conveniência que é equivalente a chamar Next() e verificar um valor de retorno de WEAVE_END_OF_TLV.

Detalhes
Valores de retorno
WEAVE_NO_ERROR
Se não houver mais elementos TLV a serem lidos.
WEAVE_ERROR_UNEXPECTED_TLV_ELEMENT
Se outro elemento TLV foi encontrado na coleção.
WEAVE_ERROR_TLV_UNDERRUN
Se a codificação TLV subjacente foi encerrada prematuramente.
WEAVE_ERROR_INVALID_TLV_ELEMENT
Se o leitor encontrou um tipo de elemento TLV inválido ou incompatível.
WEAVE_ERROR_INVALID_TLV_TAG
Se o leitor encontrou uma tag TLV em um contexto inválido.
other
Outros códigos de erro do Weave ou da plataforma retornados pela função GetNextBuffer() configurada. Possível apenas quando GetNextBuffer não é NULL.

Funções protegidas

ClearElementState

void ClearElementState(
  void
)

Limpe o estado do TLVReader.

Esse método é usado para posicionar o leitor antes do primeiro TLV, entre os TLVs ou após o último TLV.

ElementType

TLVElementType ElementType(
  void
) const 

Esse é um método particular que retorna o TLVElementType de mControlByte.

EnsureData

WEAVE_ERROR EnsureData(
  WEAVE_ERROR noDataErr
)

GetElementHeadLength

WEAVE_ERROR GetElementHeadLength(
  uint8_t & elemHeadBytes
) const 

Trata-se de um método privado usado para calcular o comprimento de uma cabeça de elemento TLV.

IsContainerOpen

bool IsContainerOpen(
  void
) const 

ReadData

WEAVE_ERROR ReadData(
  uint8_t *buf,
  uint32_t len
)

ReadElement

WEAVE_ERROR ReadElement(
  void
)

ReadTag

uint64_t ReadTag(
  TLVTagControl tagControl,
  const uint8_t *& p
)

SetContainerOpen

void SetContainerOpen(
  bool aContainerOpen
)

SkipData

WEAVE_ERROR SkipData(
  void
)

Pule todos os dados contidos no TLV atual lendo-o sem um buffer de destino.

Detalhes
Valores de retorno
WEAVE_NO_ERROR
Se o leitor foi posicionado com sucesso ao final dos dados.
other
Outros códigos de erro do Weave ou da plataforma retornados pela função GetNextBuffer() configurada. Possível apenas quando GetNextBuffer não é NULL.

SkipToEndOfContainer

WEAVE_ERROR SkipToEndOfContainer(
  void
)

VerifyElement

WEAVE_ERROR VerifyElement(
  void
)

Funções estáticas protegidas

FailGetNextBuffer

WEAVE_ERROR FailGetNextBuffer(
  TLVReader & reader,
  uintptr_t & bufHandle,
  const uint8_t *& bufStart,
  uint32_t & bufLen
)

GetNextPacketBuffer

WEAVE_ERROR GetNextPacketBuffer(
  TLVReader & reader,
  uintptr_t & bufHandle,
  const uint8_t *& bufStart,
  uint32_t & bufLen
)