nl:: Weave:: System:: PacketBuffer
#include <src/system/SystemPacketBuffer.h>
A classe de buffer de pacote é a estrutura central usada para manipular pacotes de dados serializados por octeto, geralmente no contexto de uma rede de comunicações de dados, como Bluetooth ou o protocolo de Internet.
Resumo
Em ambientes baseados em LwIP, essa classe é criada com base na estrutura pbuf definida nessa biblioteca. Na ausência de LwIP, o Weave oferece uma implementação baseada em problemas ou em pool, que se aproxima dos desafios de memória de dispositivos profundamente incorporados.
A classe PacketBuffer, como muitas estruturas semelhantes usadas em pilhas de rede em camadas, oferece um mecanismo para reservar espaço para cabeçalhos de protocolo em cada camada de uma pilha de comunicação configurável. Para mais detalhes, consulte PacketBuffer::New()
e a documentação do LwIP.
Os objetos PacketBuffer são contados por referência, e o modo de uso predominante no Weave é "disparar e esquecer". Como o pacote (e o objeto PacketBuffer subjacente) é enviado por várias camadas de protocolo, o upcall ou downcall bem-sucedidos entre as camadas implicam a transferência de propriedade, e o recebedor da chamada é responsável por liberar o buffer. Em caso de falha de uma chamada entre camadas, a responsabilidade por liberar o buffer é do autor da chamada.
Os novos objetos da classe PacketBuffer são inicializados no início de uma alocação de memória recebida do ambiente subjacente, por exemplo, de pools de destino pbuf do LwIP, da heap da biblioteca C padrão de um pool de buffers interno. No caso simples, o tamanho do buffer de dados é WEAVE_SYSTEM_PACKETBUFFER_SIZE. É fornecido um compositor que permite o uso de buffers de dados de outros tamanhos.
Objetos PacketBuffer podem ser encadeados para acomodar payloads maiores. No entanto, o encadeamento não é transparente, e os usuários da classe precisam decidir explicitamente oferecer suporte ao encadeamento. Confira alguns exemplos de classes escritas com suporte para encadeamento:
@ref nl::Weave::WeaveTLVReader @ref nl::Weave::WeaveTLVWriter
Herança
Herda de: pbuf
Funções públicas |
|
---|---|
AddRef(void)
|
void
Incrementa a contagem de referência do buffer atual.
|
AddToEnd(PacketBuffer *aPacket)
|
void
Adiciona o buffer de pacote especificado ao final da cadeia do buffer, ajustando o comprimento total de cada buffer na cadeia de acordo.
|
AlignPayload(uint16_t aAlignBytes)
|
bool
Alinha o payload do buffer no limite de bytes especificado.
|
AllocSize(void) const
|
size_t
Retorna o tamanho da alocação, incluindo os espaços de dados reservados e de payload, mas sem incluir o espaço alocado para a estrutura PacketBuffer.
|
AvailableDataLength(void) const
|
uint16_t
Extrai o número de bytes de dados que podem ser adicionados ao buffer atual, considerando a posição inicial e o tamanho dos dados atuais.
|
CompactHead(void)
|
void
Move dados de buffers subsequentes na cadeia para o buffer atual até que ele esteja cheio.
|
Consume(uint16_t aConsumeLength)
|
Consumir dados em uma cadeia de buffers.
|
ConsumeHead(uint16_t aConsumeLength)
|
void
Ajuste o buffer atual para indicar a quantidade de dados consumidas.
|
DataLength(void) const
|
uint16_t
Recebe o tamanho, em bytes, dos dados no buffer de pacote.
|
DetachTail(void)
|
Remover o buffer atual da cadeia e retornar um ponteiro para os buffers restantes.
|
EnsureReservedSize(uint16_t aReservedSize)
|
bool
Confira se o buffer tem pelo menos a quantidade especificada de espaço reservado.
|
MaxDataLength(void) const
|
uint16_t
Extrai a quantidade máxima, em bytes, de dados que cabem no buffer, considerando a posição inicial e o tamanho atuais do buffer.
|
Next(void) const
|
Recebe o ponteiro para o próximo buffer na cadeia.
|
ReservedSize(void) const
|
uint16_t
Consiga o número de bytes dentro do buffer atual entre o início dele e a posição inicial dos dados.
|
SetDataLength(uint16_t aNewLen, PacketBuffer *aChainHead)
|
void
Define o comprimento, em bytes, dos dados no buffer, ajustando o comprimento total conforme necessário.
|
SetStart(uint8_t *aNewStart)
|
void
Defina os dados iniciais no buffer, ajustando a duração e o comprimento total adequadamente.
|
Start(void) const
|
uint8_t *
Recebe o ponteiro para o início dos dados no buffer.
|
TotalLength(void) const
|
uint16_t
Extrai o comprimento total dos dados do pacote na cadeia de buffer.
|
Funções estáticas públicas |
|
---|---|
Free(PacketBuffer *aPacket)
|
void
Liberar todos os buffers de pacote em uma cadeia.
|
FreeHead(PacketBuffer *aPacket)
|
Liberar o primeiro buffer de uma cadeia, retornando um ponteiro para os buffers restantes.
|
New(void)
|
Aloca um único PacketBuffer do tamanho máximo padrão (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) com o tamanho reservado padrão (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) no payload.
|
New(uint16_t aReservedSize)
|
Aloca um único PacketBuffer de tamanho total máximo com um tamanho específico de reserva de cabeçalho.
|
NewWithAvailableSize(size_t aAvailableSize)
|
Aloca um PacketBuffer com o tamanho reservado padrão (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) no payload para cabeçalhos e pelo menos
aAllocSize bytes de espaço para dados adicionais depois do ponteiro inicial do cursor. |
NewWithAvailableSize(uint16_t aReservedSize, size_t aAvailableSize)
|
Aloca um objeto PacketBuffer com pelo menos
aReservedSize bytes reservados no payload para cabeçalhos e pelo menos aAllocSize bytes de espaço para dados adicionais após o ponteiro inicial do cursor. |
RightSize(PacketBuffer *aPacket)
|
Copie o buffer fornecido para um buffer de tamanho correto, se aplicável.
|
Funções públicas
AddRef
void AddRef( void )
Incrementa a contagem de referência do buffer atual.
AddToEnd
void AddToEnd( PacketBuffer *aPacket )
Adiciona o buffer de pacote especificado ao final da cadeia do buffer, ajustando o comprimento total de cada buffer na cadeia de acordo.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
AlignPayload
bool AlignPayload( uint16_t aAlignBytes )
Alinha o payload do buffer no limite de bytes especificado.
Mover o payload no buffer para frente, se necessário.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
||
Retorna |
true se o alinhamento for bem-sucedido, false se não houver espaço suficiente no buffer. |
AllocSize
size_t AllocSize( void ) const
Retorna o tamanho da alocação, incluindo os espaços de dados reservados e de payload, mas sem incluir o espaço alocado para a estrutura PacketBuffer.
Detalhes | |
---|---|
Retorna |
tamanho da alocação
|
AvailableDataLength
uint16_t AvailableDataLength( void ) const
Extrai o número de bytes de dados que podem ser adicionados ao buffer atual, considerando a posição inicial e o tamanho dos dados atuais.
Detalhes | |
---|---|
Retorna |
o tamanho, em bytes, dos dados que cabem no buffer atual, considerando a posição inicial e o comprimento dos dados.
|
CompactHead
void CompactHead( void )
Move dados de buffers subsequentes na cadeia para o buffer atual até que ele esteja cheio.
Somente o buffer atual é compactado: os dados nele são movidos para a frente do buffer, eliminando qualquer espaço reservado. O espaço disponível restante é preenchido com dados movidos de buffers subsequentes na cadeia, até que o buffer atual esteja cheio. Se um buffer subsequente na cadeia for movido para o buffer atual na íntegra, ele será removido da cadeia e liberado. O método não aceita parâmetros, não retorna resultados e não pode falhar.
consumo
PacketBuffer * Consume( uint16_t aConsumeLength )
Consumir dados em uma cadeia de buffers.
Consumir dados em uma cadeia de buffers começando com o buffer atual e avançando pelos buffers restantes na cadeia. Cada buffer completamente consumido é liberado, e a função retorna o primeiro buffer (se houver) contendo os dados restantes. O buffer atual precisa ser o líder da cadeia do buffer.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
||
Retorna |
o primeiro buffer da cadeia atual que contém os dados restantes. Se nenhum dado permanecer, um NULL será retornado.
|
ConsumeHead
void ConsumeHead( uint16_t aConsumeLength )
Ajuste o buffer atual para indicar a quantidade de dados consumidas.
A posição inicial dos dados no buffer atual é avançada pelo valor especificado, em bytes, até o comprimento dos dados no buffer. Diminua o comprimento e o comprimento total de acordo com a quantidade consumida.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
DataLength
uint16_t DataLength( void ) const
Recebe o tamanho, em bytes, dos dados no buffer de pacote.
Detalhes | |
---|---|
Retorna |
tamanho, em bytes (comprimento do payload atual).
|
DetachTail
PacketBuffer * DetachTail( void )
Remover o buffer atual da cadeia e retornar um ponteiro para os buffers restantes.
O buffer atual precisa ser o líder da cadeia.
Detalhes | |
---|---|
Retorna |
na cauda da cadeia de buffers atual ou NULL se o buffer atual for o único na cadeia.
|
EnsureReservedSize
bool EnsureReservedSize( uint16_t aReservedSize )
Confira se o buffer tem pelo menos a quantidade especificada de espaço reservado.
Certifique-se de que o buffer tenha pelo menos a quantidade especificada de espaço reservado, movendo os dados nele para frente a fim de liberar espaço, se necessário.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
||
Retorna |
true se o tamanho reservado solicitado estiver disponível, false se não houver espaço suficiente no buffer. |
MaxDataLength
uint16_t MaxDataLength( void ) const
Extrai a quantidade máxima, em bytes, de dados que cabem no buffer, considerando a posição inicial e o tamanho atuais do buffer.
Detalhes | |
---|---|
Retorna |
número de bytes que cabem no buffer de acordo com a posição inicial atual.
|
Próxima
PacketBuffer * Next( void ) const
Recebe o ponteiro para o próximo buffer na cadeia.
Detalhes | |
---|---|
Retorna |
um ponteiro para o próximo buffer na cadeia.
NULL é retornado quando não há buffers na cadeia. |
ReservedSize
uint16_t ReservedSize( void ) const
Consiga o número de bytes dentro do buffer atual entre o início dele e a posição inicial dos dados.
Detalhes | |
---|---|
Retorna |
a quantidade, em bytes, do espaço entre o início do buffer e a posição inicial dos dados atual.
|
SetDataLength
void SetDataLength( uint16_t aNewLen, PacketBuffer *aChainHead )
Define o comprimento, em bytes, dos dados no buffer, ajustando o comprimento total conforme necessário.
A função define o comprimento, em bytes, dos dados no buffer, ajustando o comprimento total adequadamente. Quando o buffer não é o líder da cadeia de buffers (caso comum: o autor da chamada adiciona dados ao último buffer na cadeia PacketBuffer antes de chamar camadas mais altas), o aChainHead precisa ser transmitido para ajustar corretamente o comprimento total de cada buffer antes do buffer atual.
Detalhes | |||||
---|---|---|---|---|---|
Parâmetros |
|
SetStart
void SetStart( uint8_t *aNewStart )
Defina os dados iniciais no buffer, ajustando a duração e o comprimento total adequadamente.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
Iniciar
uint8_t * Start( void ) const
Recebe o ponteiro para o início dos dados no buffer.
Detalhes | |
---|---|
Retorna |
ponteiro para o início dos dados.
|
TotalLength
uint16_t TotalLength( void ) const
Extrai o comprimento total dos dados do pacote na cadeia de buffer.
Detalhes | |
---|---|
Retorna |
tamanho total, em octetos.
|
Funções estáticas públicas
Sem custo financeiro
void Free( PacketBuffer *aPacket )
Liberar todos os buffers de pacote em uma cadeia.
Diminui a contagem de referência para todos os buffers na cadeia atual. Se a contagem de referência chegar a 0, os respectivos buffers serão liberados ou retornados aos pools de alocação, conforme apropriado. Como regra, os usuários precisam tratar esse método como um equivalente da função free()
e não usar o argumento após a chamada.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
FreeHead
PacketBuffer * FreeHead( PacketBuffer *aPacket )
Liberar o primeiro buffer de uma cadeia, retornando um ponteiro para os buffers restantes.
* @note When the buffer chain is referenced by multiple callers,
FreeHead()` removerá a cabeçalho, mas não forçará a desalocação do buffer principal.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
||
Retorna |
Cadeia de buffers de pacote que consiste na cauda do buffer de entrada (pode ser
NULL ). |
Novo
PacketBuffer * New( void )
Aloca um único PacketBuffer do tamanho máximo padrão (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) com o tamanho reservado padrão (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) no payload.
O tamanho reservado (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) é grande o suficiente para armazenar cabeçalhos da camada de transporte e os exigidos por WeaveMessageLayer
e WeaveExchangeLayer
.
Novo
PacketBuffer * New( uint16_t aReservedSize )
Aloca um único PacketBuffer de tamanho total máximo com um tamanho específico de reserva de cabeçalho.
O parâmetro transmitido tem o tamanho reservado antes do payload para acomodar os cabeçalhos dos pacotes de diferentes camadas da pilha, e não o tamanho total do buffer a ser alocado. O tamanho do buffer WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX e não, especificado na chamada.
PacketBuffer::New(0)
: quando chamado dessa maneira, o buffer é retornado sem nenhum cabeçalho reservado. Consequentemente, todo o payload pode ser usado pelo autor da chamada. Esse padrão é particularmente útil nas camadas mais baixas de pilhas de rede, nos casos em que o usuário sabe que o payload será copiado na mensagem final com as reservas de cabeçalho adequadas ou na criação de PacketBuffer que são anexados a uma cadeia de PacketBuffer viaPacketBuffer::AddToEnd()
. Parâmetros[in] aReservedSize
quantidade de espaço do cabeçalho a ser reservado.Em caso de sucesso, um ponteiro para o PacketBuffer, em caso de falhaNULL
.
NewWithAvailableSize
PacketBuffer * NewWithAvailableSize( size_t aAvailableSize )
Aloca um PacketBuffer com o tamanho reservado padrão (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) no payload para cabeçalhos e pelo menos aAllocSize
bytes de espaço para dados adicionais depois do ponteiro inicial do cursor.
Esse uso é mais apropriado ao alocar um PacketBuffer para uma mensagem na camada do aplicativo.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
||
Retorna |
Se for bem-sucedido, um ponteiro para o PacketBuffer no bloco alocado. Em caso de falha,
NULL . * |
NewWithAvailableSize
PacketBuffer * NewWithAvailableSize( uint16_t aReservedSize, size_t aAvailableSize )
Aloca um objeto PacketBuffer com pelo menos aReservedSize
bytes reservados no payload para cabeçalhos e pelo menos aAllocSize
bytes de espaço para dados adicionais após o ponteiro inicial do cursor.
Detalhes | |||||
---|---|---|---|---|---|
Parâmetros |
|
||||
Retorna |
Se for bem-sucedido, um ponteiro para o PacketBuffer no bloco alocado. Em caso de falha,
NULL . |
RightSize
PacketBuffer * RightSize( PacketBuffer *aPacket )
Copie o buffer fornecido para um buffer de tamanho correto, se aplicável.
Essa função é um ambiente autônomo para soquetes.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
||
Retorna |
um novo buffer de pacote ou o buffer original
|