nl::Weave::System::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

A classe de buffer de pacote é a estrutura principal usada para manipular pacotes de dados serializados de octetos, 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 falta de LwIP, o Weave oferece uma implementação baseada em malloc ou baseada em pool que se aproxima dos desafios de memória de dispositivos profundamente incorporados.

A classe PacketBuffer, assim como muitas estruturas semelhantes usadas em pilhas de redes 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. Veja os detalhes em PacketBuffer::New() e na documentação de LwIP.

Objetos PacketBuffer são contados por referência, e o modo de uso predominante no Weave é "fire-and-forget". Como o pacote (e o objeto PacketBuffer subjacente) é enviado por várias camadas de protocolo, o aumento ou a redução de chamada entre as camadas implica a transferência de propriedade, e o recebedor da chamada é responsável por liberar o buffer. Em caso de falha em uma chamada entre camadas, a responsabilidade por liberar o buffer fica com o autor da chamada.

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, do heap padrão da biblioteca C de um pool de buffer interno. No caso simples, o tamanho do buffer de dados é WEAVE_SYSTEM_PACKETBUFFER_SIZE. Um compositor é fornecido para permitir o uso de buffers de dados de outros tamanhos.

Os objetos PacketBuffer podem ser encadeados para acomodar payloads maiores. No entanto, encadear não é transparente, e os usuários da classe precisam decidir explicitamente oferecer compatibilidade com o encadeamento. Exemplos de classes escritas compatíveis com encadeamento são as seguintes:

@ref nl::Weave::WeaveTLVReader
@ref nl::Weave::WeaveTLVWriter

Herança

Herda de: pbuf

Funções públicas

AddRef(void)
void
Incrementar a contagem de referência do buffer atual.
AddToEnd(PacketBuffer *aPacket)
void
Adiciona o buffer de pacote especificado ao final da cadeia de buffers, ajustando o comprimento total de cada buffer na cadeia.
AlignPayload(uint16_t aAlignBytes)
bool
Alinha o payload do buffer no limite de bytes especificado.
AllocSize(void) const
size_t
Retorne o tamanho da alocação, incluindo os espaços de dados reservados e de payload, mas não incluindo o espaço alocado para a estrutura PacketBuffer.
AvailableDataLength(void) const
uint16_t
Encontre o número de bytes de dados que podem ser adicionados ao buffer atual de acordo com a posição inicial e o comprimento de dados atuais.
CompactHead(void)
void
Mova os dados dos buffers subsequentes na cadeia para o buffer atual até que eles fiquem cheios.
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 consumidos.
DataLength(void) const
uint16_t
Receber o comprimento, em bytes, de dados no buffer do pacote.
DetachTail(void)
Remover o buffer atual da cadeia e retornar um ponteiro para os buffers restantes.
EnsureReservedSize(uint16_t aReservedSize)
bool
Verifique se o buffer tem pelo menos a quantidade especificada de espaço reservado.
MaxDataLength(void) const
uint16_t
Encontre a quantidade máxima, em bytes, de dados que caberão no buffer considerando a posição atual e o tamanho do buffer.
Next(void) const
Ponteiro para o próximo buffer na cadeia.
ReservedSize(void) const
uint16_t
Exibe o número de bytes no buffer atual entre o início do buffer e a posição atual dos dados.
SetDataLength(uint16_t aNewLen, PacketBuffer *aChainHead)
void
Defina o tamanho, em bytes, dos dados em buffer, ajustando o tamanho total adequadamente.
SetStart(uint8_t *aNewStart)
void
Defina os dados iniciais no buffer, ajustando o tamanho e o comprimento total adequadamente.
Start(void) const
uint8_t *
Receber ponteiro para iniciar os dados no buffer.
TotalLength(void) const
uint16_t
Receber o tamanho total dos dados do pacote na cadeia de buffers.

Funções estáticas públicas

Free(PacketBuffer *aPacket)
void
Libere todos os buffers de pacote em uma cadeia.
FreeHead(PacketBuffer *aPacket)
Libere o primeiro buffer em uma cadeia, retornando um ponteiro para os buffers restantes.
New(void)
Aloca um único PacketBuffer de tamanho máximo padrão (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) com tamanho reservado padrão (WEAVE_SYSTEM_CONFIG_Headers_RESERVE_SIZE) no payload.
New(uint16_t aReservedSize)
Aloca um único PacketBuffer de tamanho total máximo com um tamanho de reserva de cabeçalho específico.
NewWithAvailableSize(size_t aAvailableSize)
Aloca um PacketBuffer com o tamanho reservado padrão (WEAVE_SYSTEM_CONFIG_Headers_RESERVE_SIZE) no payload dos cabeçalhos e pelo menos aAllocSize bytes de espaço para dados adicionais após o 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 especificado para um buffer de tamanho correto, se aplicável.

Funções públicas

Adicionar referência

void AddRef(
  void
)

Incrementar a contagem de referência do buffer atual.

AddToEnd.

void AddToEnd(
  PacketBuffer *aPacket
)

Adiciona o buffer de pacote especificado ao final da cadeia de buffers, ajustando o comprimento total de cada buffer na cadeia.

Detalhes
Parâmetros
[in] aPacket
- O buffer de pacote a ser adicionado ao fim da cadeia atual.

AlignPayload

bool AlignPayload(
  uint16_t aAlignBytes
)

Alinha o payload do buffer no limite de bytes especificado.

Se necessário, mova o payload para o buffer.

Detalhes
Parâmetros
[in] aAlignBytes
- especifica o número de bytes de alinhamento para o ponteiro de início do payload.
Retorna
true se o alinhamento for bem-sucedido, false se não houver espaço suficiente no buffer.

TamanhoAloc

size_t AllocSize(
  void
) const 

Retorne o tamanho da alocação, incluindo os espaços de dados reservados e de payload, mas não incluindo o espaço alocado para a estrutura PacketBuffer.

Detalhes
Retorna
tamanho da alocação

DisponíveisDataData

uint16_t AvailableDataLength(
  void
) const 

Encontre o número de bytes de dados que podem ser adicionados ao buffer atual de acordo com a posição inicial e o comprimento de dados atuais.

Detalhes
Retorna
o comprimento, em bytes, dos dados que caberão no buffer atual de acordo com a posição inicial e o comprimento de dados atuais;

CompactHead

void CompactHead(
  void
)

Mova os dados dos buffers subsequentes na cadeia para o buffer atual até que eles fiquem cheios.

Apenas o buffer atual é compactado: os dados no buffer atual são movidos para a frente do buffer, eliminando qualquer espaço reservado. O espaço disponível restante é preenchido com os dados movidos dos buffers subsequentes na cadeia, até que o buffer atual esteja cheio. Se um buffer subsequente na cadeia for movido totalmente para o buffer atual, ele será removido da cadeia e liberado. O método não recebe parâmetros, não retorna resultados e não pode falhar.

Consumir

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çar pelos buffers restantes na cadeia. Cada buffer consumido é liberado, e a função retorna o primeiro buffer (se houver) com os dados restantes. O buffer atual precisa ser o cabeçalho da cadeia de buffers.

Detalhes
Parâmetros
[in] aConsumeLength
- número de bytes a serem consumidos da cadeia atual.
Retorna
o primeiro buffer da cadeia atual que contém qualquer dado restante. Se não houver dados restantes, um NULL é retornado.

Cabeça do consumo

void ConsumeHead(
  uint16_t aConsumeLength
)

Ajuste o buffer atual para indicar a quantidade de dados consumidos.

avança a posição inicial dos dados no buffer atual de acordo com o valor especificado em bytes, até o tamanho dos dados no buffer; Reduza a duração e o comprimento total de acordo com o valor consumido.

Detalhes
Parâmetros
[in] aConsumeLen
- número de bytes a serem consumidos do buffer atual.

Comprimento dos dados

uint16_t DataLength(
  void
) const 

Receber o comprimento, em bytes, de dados no buffer do pacote.

Detalhes
Retorna
comprimento, em bytes (tamanho do payload atual).

Tailtail

PacketBuffer * DetachTail(
  void
)

Remover o buffer atual da cadeia e retornar um ponteiro para os buffers restantes.

O buffer atual precisa ser o cabeçalho da cadeia.

Detalhes
Retorna
A cauda da cadeia de buffer atual ou NULL se o buffer atual for o único buffer na cadeia.

GarantirReservaSize

bool EnsureReservedSize(
  uint16_t aReservedSize
)

Verifique se o buffer tem pelo menos a quantidade especificada de espaço reservado.

Verifique se o buffer tem pelo menos a quantidade especificada de espaço reservado movendo os dados para o buffer para liberar espaço, se necessário.

Detalhes
Parâmetros
[in] aReservedSize
- número de bytes desejado para os cabeçalhos.
Retorna
true se o tamanho reservado solicitado estiver disponível, false se não houver espaço suficiente no buffer.

Comprimento máximo de dados

uint16_t MaxDataLength(
  void
) const 

Encontre a quantidade máxima, em bytes, de dados que caberão no buffer considerando a posição atual e o tamanho do buffer.

Detalhes
Retorna
Número de bytes que se encaixa no buffer considerando a posição inicial atual.

Próxima

PacketBuffer * Next(
  void
) const 

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.

Tamanho reservado

uint16_t ReservedSize(
  void
) const 

Exibe o número de bytes no buffer atual entre o início do buffer e a posição atual dos dados.

Detalhes
Retorna
A quantidade, em bytes, de espaço entre o início do buffer e a posição inicial atual dos dados.

Definição de DataData

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

Defina o tamanho, em bytes, dos dados em buffer, ajustando o tamanho total adequadamente.

A função define o comprimento, em bytes, dos dados no buffer, ajustando adequadamente o comprimento total. Quando o buffer não é o cabeçalho 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 passado para ajustar corretamente os comprimentos atuais de cada buffer antes de cada um.

Detalhes
Parâmetros
[in] aNewLen
- novo comprimento, em bytes, desse buffer.
[in,out] aChainHead
- o cabeçalho da cadeia de buffers a que o buffer atual pertence. Poderá ser NULL se o buffer atual for o cabeçalho da cadeia de buffers.

Inicialização

void SetStart(
  uint8_t *aNewStart
)

Defina os dados iniciais no buffer, ajustando o tamanho e o comprimento total adequadamente.

Detalhes
Parâmetros
[in] aNewStart
- Um ponteiro para o ponto de partida do novo payload. O newStart será ajustado internamente para ficar dentro dos limites do primeiro buffer na cadeia PacketBuffer.

Iniciar

uint8_t * Start(
  void
) const 

Receber ponteiro para iniciar os dados no buffer.

Detalhes
Retorna
ponteiro para o início dos dados.

Comprimento total

uint16_t TotalLength(
  void
) const 

Receber o tamanho total dos dados do pacote na cadeia de buffers.

Detalhes
Retorna
tamanho total, em octetos

Funções estáticas públicas

Gratuito

void Free(
  PacketBuffer *aPacket
)

Libere todos os buffers de pacote em uma cadeia.

Reduzir a contagem de referência para todos os buffers na cadeia atual. Se a contagem de referência atingir 0, os respectivos buffers são liberados ou retornados aos pools de alocação conforme apropriado. Como regra, os usuários devem tratar esse método como um equivalente à função free() e não usar o argumento após a chamada.

Detalhes
Parâmetros
[in] aPacket
- buffer de pacote a ser liberado.

Cabeça livre

PacketBuffer * FreeHead(
  PacketBuffer *aPacket
)

Libere o primeiro buffer em uma cadeia, retornando um ponteiro para os buffers restantes.

* @note When the buffer chain is referenced by multiple callers,FreeHead() vai remover a cabeça, mas não desaplicará o buffer de cabeça.

Detalhes
Parâmetros
[in] aPacket
- cadeia de buffers.
Retorna
cadeia de buffer de pacote que consiste na cauda do buffer de entrada (pode ser NULL).

Novo

PacketBuffer * New(
  void
)

Aloca um único PacketBuffer de tamanho máximo padrão (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) com tamanho reservado padrão (WEAVE_SYSTEM_CONFIG_Headers_RESERVE_SIZE) no payload.

O tamanho reservado (WEAVE_SYSTEM_CONFIG_Headers_RESERVE_SIZE) é grande o suficiente para armazenar cabeçalhos de camada de transporte e cabeçalhos exigidos por WeaveMessageLayer e WeaveExchangeLayer.

Novo

PacketBuffer * New(
  uint16_t aReservedSize
)

Aloca um único PacketBuffer de tamanho total máximo com um tamanho de reserva de cabeçalho específico.

O parâmetro transmitido é o tamanho reservado antes do payload para acomodar cabeçalhos de pacotes de diferentes camadas da pilha, e não o tamanho geral 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 será retornado sem qualquer cabeçalho reservado. Consequentemente, todo o payload será utilizável pelo autor da chamada. Esse padrão é particularmente útil nas camadas mais baixas das pilhas de rede, nos casos em que o usuário sabe que o payload será copiado para a mensagem final com as reservas de cabeçalho adequadas ou na criação de PacketBuffer anexado a uma cadeia de PacketBuffer via PacketBuffer::AddToEnd(). Parâmetros
    [in] aReservedSize
    espaço do cabeçalho a ser reservado.
    Retorna
    Em caso de sucesso, um ponteiro para o PacketBuffer, na falha NULL.

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

Aloca um PacketBuffer com o tamanho reservado padrão (WEAVE_SYSTEM_CONFIG_Headers_RESERVE_SIZE) no payload dos cabeçalhos e pelo menos aAllocSize bytes de espaço para dados adicionais após o ponteiro inicial do cursor

Esse uso é mais apropriado ao alocar um PacketBuffer para uma mensagem da camada de aplicativos.

Detalhes
Parâmetros
[in] aAvailableSize
Número de octetos a serem alocados após o cursor.
Retorna
Em caso de sucesso, um ponteiro para 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
[in] aReservedSize
Número de octetos a serem reservados atrás do cursor.
[in] aAvailableSize
Número de octetos a serem alocados após o cursor.
Retorna
Em caso de sucesso, um ponteiro para PacketBuffer no bloco alocado. Em caso de falha, NULL.

Direita

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

Copie o buffer especificado para um buffer de tamanho correto, se aplicável.

Essa função é um ambiente autônomo para soquetes.

Detalhes
Parâmetros
[in] aPacket
- buffer ou cadeia de buffers.
Retorna
novo buffer de pacote ou o buffer original