nl :: Tecer:: Sistema:: 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ção de dados, como Bluetooth ou o protocolo da Internet.
Resumo
Em ambientes baseados em LwIP, esta classe é construída sobre a estrutura pbuf definida nessa biblioteca. Na ausência de LwIP, o Weave fornece uma implementação baseada em malloc ou uma implementação baseada em pool que se aproxima muito dos desafios de memória de dispositivos profundamente integrados.
A classe PacketBuffer , como muitas estruturas semelhantes usadas em pilhas de rede em camadas, fornece um mecanismo para reservar espaço para cabeçalhos de protocolo em cada camada de uma pilha de comunicação configurável. Para obter detalhes, consulte PacketBuffer::New()
, bem como a documentação LwIP.
Os objetos PacketBuffer são contados por referência e o modo de uso predominante no Weave é "dispare e esqueça". Como o pacote (e seu objeto PacketBuffer subjacente) é despachado através de várias camadas de protocolo, o upcall ou downcall bem-sucedido entre as camadas implica transferência de propriedade, e o receptor é responsável por liberar o buffer. Em caso de falha de uma chamada de camada cruzada, a responsabilidade de liberar o buffer recai sobre o chamador.
Novos objetos da classe PacketBuffer são inicializados no início de uma alocação de memória obtida do ambiente subjacente, por exemplo, de pools de destino LwIP pbuf, do heap da biblioteca C padrão, de um pool de buffer 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.
Os objetos PacketBuffer podem ser encadeados para acomodar cargas úteis maiores. O encadeamento, no entanto, não é transparente e os usuários da classe devem decidir explicitamente oferecer suporte ao encadeamento. Exemplos de classes escritas com suporte a encadeamento são os seguintes:
@ref nl::Weave::WeaveTLVReader @ref nl::Weave::WeaveTLVWriter
Herança
Herda de: pbufFunções públicas | |
---|---|
AddRef (void) | void Aumente a contagem de referência do buffer atual. |
AddToEnd ( PacketBuffer *aPacket) | void Adicione o buffer de pacote fornecido ao final da cadeia de buffer, ajustando o comprimento total de cada buffer na cadeia de acordo. |
AlignPayload (uint16_t aAlignBytes) | bool Alinha a carga útil 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 carga útil, mas não incluindo o espaço alocado para a estrutura PacketBuffer . |
AvailableDataLength (void) const | uint16_t Obtenha o número de bytes de dados que podem ser adicionados ao buffer atual, considerando a posição inicial atual e o comprimento dos dados. |
CompactHead (void) | void Mova os dados de buffers subsequentes na cadeia para o buffer atual até que 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 consumidos. |
DataLength (void) const | uint16_t Obtenha o comprimento, em bytes, dos dados no buffer de pacotes. |
DetachTail (void) | Desanexe o buffer atual de sua cadeia e retorne um ponteiro para os buffers restantes. |
EnsureReservedSize (uint16_t aReservedSize) | bool Certifique-se de que o buffer tenha pelo menos a quantidade especificada de espaço reservado. |
MaxDataLength (void) const | uint16_t Obtenha a quantidade máxima, em bytes, de dados que caberão no buffer de acordo com a posição inicial atual e o tamanho do buffer. |
Next (void) const | Obtém o ponteiro para o próximo buffer na cadeia. |
ReservedSize (void) const | uint16_t Obtenha o número de bytes dentro do buffer atual entre o início do buffer e a posição inicial dos dados atuais. |
SetDataLength (uint16_t aNewLen, PacketBuffer *aChainHead) | void Defina o comprimento, em bytes, dos dados no buffer, ajustando o comprimento total de acordo. |
SetStart (uint8_t *aNewStart) | void Defina os dados iniciais no buffer, ajustando o comprimento e o comprimento total de acordo. |
Start (void) const | uint8_t * Obtém o ponteiro para o início dos dados no buffer. |
TotalLength (void) const | uint16_t Obtenha o comprimento total dos dados do pacote na cadeia de buffer. |
Funções estáticas públicas | |
---|---|
Free ( PacketBuffer *aPacket) | void Libere todos os buffers de pacotes 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_HEADER_RESERVE_SIZE ) na carga útil. |
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 tamanho padrão reservado ( WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE ) na carga útil para cabeçalhos e pelo menos aAllocSize bytes de espaço para dados adicionais após o ponteiro do cursor inicial. |
NewWithAvailableSize (uint16_t aReservedSize, size_t aAvailableSize) | Aloca um objeto PacketBuffer com pelo menos aReservedSize bytes reservados na carga útil para cabeçalhos e pelo menos aAllocSize bytes de espaço para dados adicionais após o ponteiro do cursor inicial. |
RightSize ( PacketBuffer *aPacket) | Copie o buffer fornecido para um buffer de tamanho correto, se aplicável. |
Funções públicas
AddRef
void AddRef( void )
Aumente a contagem de referência do buffer atual.
AddToEnd
void AddToEnd( PacketBuffer *aPacket )
Adicione o buffer de pacote fornecido ao final da cadeia de buffer, ajustando o comprimento total de cada buffer na cadeia de acordo.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
AlignPayload
bool AlignPayload( uint16_t aAlignBytes )
Alinha a carga útil do buffer no limite de bytes especificado.
Movendo a carga útil no buffer para frente, se necessário.
Detalhes | |||
---|---|---|---|
Parâmetros |
| ||
Devoluções | true se o alinhamento for bem-sucedido, false se não houver espaço suficiente no buffer. |
AllocSize
size_t AllocSize( void ) const
Retorne o tamanho da alocação incluindo os espaços de dados reservados e de carga útil, mas não incluindo o espaço alocado para a estrutura PacketBuffer .
Detalhes | |
---|---|
Devoluções | tamanho da alocação |
AvailableDataLength
uint16_t AvailableDataLength( void ) const
Obtenha o número de bytes de dados que podem ser adicionados ao buffer atual, considerando a posição inicial atual e o comprimento dos dados.
Detalhes | |
---|---|
Devoluções | o comprimento, em bytes, dos dados que caberão no buffer atual, considerando a posição inicial atual e o comprimento dos dados. |
CompactHead
void CompactHead( void )
Mova os dados de buffers subsequentes na cadeia para o buffer atual até que esteja cheio.
Apenas o buffer atual é compactado: os dados dentro do buffer atual 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 em sua totalidade, ele será removido da cadeia e liberado. O método não aceita 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 continuando pelos buffers restantes na cadeia. Cada buffer que é completamente consumido é liberado e a função retorna o primeiro buffer (se houver) contendo os dados restantes. O buffer atual deve ser o chefe da cadeia de buffer.
Detalhes | |||
---|---|---|---|
Parâmetros |
| ||
Devoluções | o primeiro buffer da cadeia atual que contém todos 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 consumidos.
Avança a posição inicial dos dados no buffer atual pela quantidade especificada, em bytes, até o comprimento dos dados no buffer. Diminua o comprimento e o comprimento total pela quantidade consumida.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
DataLength
uint16_t DataLength( void ) const
Obtenha o comprimento, em bytes, dos dados no buffer de pacotes.
Detalhes | |
---|---|
Devoluções | comprimento, em bytes (comprimento da carga útil atual). |
DetachTail
PacketBuffer * DetachTail( void )
Desanexe o buffer atual de sua cadeia e retorne um ponteiro para os buffers restantes.
O buffer atual deve ser o chefe da cadeia.
Detalhes | |
---|---|
Devoluções | o final da cadeia de buffer atual ou NULL se o buffer atual for o único buffer da cadeia. |
VerifyReservedSize
bool EnsureReservedSize( uint16_t aReservedSize )
Certifique-se de que o buffer tenha 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 no buffer para frente para liberar espaço, se necessário.
Detalhes | |||
---|---|---|---|
Parâmetros |
| ||
Devoluções | 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
Obtenha a quantidade máxima, em bytes, de dados que caberão no buffer de acordo com a posição inicial atual e o tamanho do buffer.
Detalhes | |
---|---|
Devoluções | número de bytes que cabe no buffer dada a posição inicial atual. |
Próximo
PacketBuffer * Next( void ) const
Obtém o ponteiro para o próximo buffer na cadeia.
Detalhes | |
---|---|
Devoluções | um ponteiro para o próximo buffer na cadeia. NULL é retornado quando não há buffers na cadeia. |
ReservedSize
uint16_t ReservedSize( void ) const
Obtenha o número de bytes dentro do buffer atual entre o início do buffer e a posição inicial dos dados atuais.
Detalhes | |
---|---|
Devoluções | a quantidade, em bytes, de espaço entre o início do buffer e a posição inicial dos dados atuais. |
SetDataLength
void SetDataLength( uint16_t aNewLen, PacketBuffer *aChainHead )
Defina o comprimento, em bytes, dos dados no buffer, ajustando o comprimento total de acordo.
A função define o comprimento, em bytes, dos dados no buffer, ajustando o comprimento total apropriadamente. Quando o buffer não é o chefe da cadeia de buffer (caso comum: o chamador adiciona dados ao último buffer na cadeia PacketBuffer antes de chamar as camadas superiores), o aChainHead deve ser passado para ajustar adequadamente os comprimentos totais de cada buffer à frente do buffer atual.
Detalhes | |||||
---|---|---|---|---|---|
Parâmetros |
|
SetStart
void SetStart( uint8_t *aNewStart )
Defina os dados iniciais no buffer, ajustando o comprimento e o comprimento total de acordo.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
Começar
uint8_t * Start( void ) const
Obtém o ponteiro para o início dos dados no buffer.
Detalhes | |
---|---|
Devoluções | ponteiro para o início dos dados. |
Comprimento total
uint16_t TotalLength( void ) const
Obtenha o comprimento total dos dados do pacote na cadeia de buffer.
Detalhes | |
---|---|
Devoluções | comprimento total, em octetos. |
Funções estáticas públicas
Livre
void Free( PacketBuffer *aPacket )
Libere todos os buffers de pacotes em uma cadeia.
Diminua 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 devem 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 )
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 () `desanexará o cabeçote, mas não desalocará forçosamente o buffer principal.
Detalhes | |||
---|---|---|---|
Parâmetros |
| ||
Devoluções | 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_HEADER_RESERVE_SIZE ) na carga útil.
O tamanho reservado ( WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE ) é grande o suficiente para conter cabeçalhos da camada de transporte, bem como 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 passado é o tamanho reservado antes da carga útil para acomodar cabeçalhos de pacote de diferentes camadas da pilha, 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 desta forma, o buffer será retornado sem nenhum cabeçalho reservado, conseqüentemente, toda a carga útil é utilizável pelo chamador. Este padrão é particularmente útil nas camadas inferiores de pilhas de rede, nos casos em que o usuário sabe que a carga útil será copiada para a mensagem final com reservas de cabeçalho apropriadas ou na criação de PacketBuffer que é anexado a uma cadeia de PacketBuffer viaPacketBuffer::AddToEnd()
.Parâmetros [in] aReservedSize
quantidade de espaço do cabeçalho a ser reservada.Devoluções Em caso de sucesso, um ponteiro para o PacketBuffer , em caso de falhaNULL
.
NewWithAvailableSize
PacketBuffer * NewWithAvailableSize( size_t aAvailableSize )
Aloca um PacketBuffer com tamanho padrão reservado ( WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE ) na carga útil para cabeçalhos e pelo menos aAllocSize
bytes de espaço para dados adicionais após o ponteiro do cursor inicial.
Esse uso é mais apropriado ao alocar um PacketBuffer para uma mensagem da camada de aplicativo.
Detalhes | |||
---|---|---|---|
Parâmetros |
| ||
Devoluções | Em caso de sucesso, 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 na carga útil para cabeçalhos e pelo menos aAllocSize
bytes de espaço para dados adicionais após o ponteiro do cursor inicial.
Detalhes | |||||
---|---|---|---|---|---|
Parâmetros |
| ||||
Devoluções | Em caso de sucesso, um ponteiro para o PacketBuffer no bloco alocado. Em caso de falha, NULL . |
Tamanho certo
PacketBuffer * RightSize( PacketBuffer *aPacket )
Copie o buffer fornecido para um buffer de tamanho correto, se aplicável.
Esta função é autônoma para sockets.
Detalhes | |||
---|---|---|---|
Parâmetros |
| ||
Devoluções | novo buffer de pacote ou o buffer original |