nl::Weave::System::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

La classe del buffer dei pacchetti è la struttura di base utilizzata per manipolare i pacchetti di dati di tipo ottetto-serializzato, solitamente nel contesto di una rete di comunicazione dati, come il Bluetooth o il protocollo internet.

Riepilogo

Negli ambienti basati su LwIP, questa classe si basa sulla struttura pbuf definita in tale libreria. In assenza di LwIP, Weave offre un'implementazione basata su Malloc o un'implementazione basata su pool che si avvicina molto alle sfide di memoria dei dispositivi profondamente incorporati.

La classe PacketBuffer, come molte strutture simili utilizzate negli stack di rete a più livelli, fornisce un meccanismo per riservare spazio per le intestazioni di protocollo in ogni livello di uno stack di comunicazione configurabile. Per maggiori dettagli, consulta la pagina PacketBuffer::New() e la documentazione relativa a LwIP.

Gli oggetti PacketBuffer vengono conteggiati come riferimento e la modalità di utilizzo prevalente all'interno di Weave è "fire-and-forget". Poiché il pacchetto (e il relativo oggetto PacketBuffer sottostante) viene inviato attraverso vari livelli di protocollo, l'upcall o il downcall riuscito tra i livelli implica il trasferimento della proprietà e la chiamata è responsabile della liberazione del buffer. In caso di errore di una chiamata a più livelli, la responsabilità di liberare il buffer spetta al chiamante.

I nuovi oggetti della classe PacketBuffer vengono inizializzati all'inizio di un'allocazione di memoria ottenuta dall'ambiente sottostante, ad esempio dai pool di destinazione pbuf LwIP, dall'heap della libreria C standard, da un pool di buffer interno. Nel caso semplice, la dimensione del buffer dei dati è WEAVE_SYSTEM_PACKETBUFFER_SIZE. È disponibile un compositore che consente l'utilizzo di buffer di dati di altre dimensioni.

Gli oggetti PacketBuffer possono essere concatenati per ospitare payload più grandi. La concatenazione, tuttavia, non è trasparente e gli utenti della classe devono decidere esplicitamente di supportarla. Ecco alcuni esempi di classi scritte che supportano il concatenamento: 

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

Eredità

Eredita da: pbuf

Funzioni pubbliche
AddRef(void)
void
Incrementa il conteggio del riferimento del buffer attuale.
AddToEnd(PacketBuffer *aPacket)
void
Aggiungere il buffer di pacchetti specificato alla fine della catena di buffer, regolando di conseguenza la lunghezza totale di ciascun buffer nella catena.
AlignPayload(uint16_t aAlignBytes)
bool
Allinea il payload del buffer al limite di byte specificato.
AllocSize(void) const
size_t
Restituisce la dimensione dell'allocazione, inclusi gli spazi di dati riservati e di payload, ma escluso lo spazio allocato per la struttura PacketBuffer.
AvailableDataLength(void) const
uint16_t
Ottieni il numero di byte di dati che possono essere aggiunti al buffer corrente in base alla posizione iniziale e alla lunghezza dei dati correnti.
CompactHead(void)
void
Sposta i dati dai buffer successivi della catena al buffer corrente fino a quando non è pieno.
Consume(uint16_t aConsumeLength)
Consuma i dati in una catena di buffer.
ConsumeHead(uint16_t aConsumeLength)
void
Regola il buffer corrente per indicare la quantità di dati consumati.
DataLength(void) const
uint16_t
Ottieni la lunghezza, in byte, dei dati nel buffer dei pacchetti.
DetachTail(void)
Scollega il buffer corrente dalla sua catena e restituisci un puntatore ai buffer rimanenti.
EnsureReservedSize(uint16_t aReservedSize)
bool
Assicurati che il buffer abbia almeno la quantità specificata di spazio riservato.
MaxDataLength(void) const
uint16_t
Ottieni la quantità massima, in byte, di dati che potrà essere inserita nel buffer in base alla posizione iniziale e alla dimensione del buffer correnti.
Next(void) const
Ottieni il puntatore al buffer successivo nella catena.
ReservedSize(void) const
uint16_t
Ottieni il numero di byte all'interno del buffer attuale tra l'inizio del buffer e la posizione di inizio dati corrente.
SetDataLength(uint16_t aNewLen, PacketBuffer *aChainHead)
void
Imposta la lunghezza, in byte, dei dati nel buffer, regolando di conseguenza la lunghezza totale.
SetStart(uint8_t *aNewStart)
void
Imposta i dati iniziali nel buffer, regolando di conseguenza la lunghezza e la lunghezza totale.
Start(void) const
uint8_t *
Ottieni il puntatore all'inizio dei dati nel buffer.
TotalLength(void) const
uint16_t
Ottieni la lunghezza totale dei dati del pacchetto nella catena del buffer.

Funzioni statiche pubbliche
Free(PacketBuffer *aPacket)
void
Libera tutti i buffer di pacchetto in una catena.
FreeHead(PacketBuffer *aPacket)
Libera il primo buffer in una catena, restituendo un puntatore nei buffer rimanenti.
New(void)
Alloca un singolo PacketBuffer di dimensione massima predefinita (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) con dimensione riservata predefinita (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) nel payload.
New(uint16_t aReservedSize)
Alloca un singolo PacketBuffer di dimensione totale massima con una dimensione di prenotazione dell'intestazione specifica.
NewWithAvailableSize(size_t aAvailableSize)
Alloca un PacketBuffer con una dimensione riservata predefinita (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) nel payload per le intestazioni e almeno aAllocSize byte di spazio per dati aggiuntivi dopo il puntatore iniziale del cursore.
NewWithAvailableSize(uint16_t aReservedSize, size_t aAvailableSize)
Alloca un oggetto PacketBuffer con almeno aReservedSize byte riservati nel payload per le intestazioni e almeno aAllocSize byte di spazio per dati aggiuntivi dopo il puntatore iniziale del cursore.
RightSize(PacketBuffer *aPacket)
Copia il buffer specificato in un buffer delle dimensioni corrette, se applicabile.

Funzioni pubbliche

AddRef

void AddRef(
  void
)

Incrementa il conteggio del riferimento del buffer attuale.

AddToEnd

void AddToEnd(
  PacketBuffer *aPacket
)

Aggiungere il buffer di pacchetti specificato alla fine della catena di buffer, regolando di conseguenza la lunghezza totale di ciascun buffer nella catena.

Dettagli
Parametri
[in] aPacket
il buffer del pacchetto da aggiungere alla fine della catena corrente.

AlignPayload

bool AlignPayload(
  uint16_t aAlignBytes
)

Allinea il payload del buffer al limite di byte specificato.

Spostamento del payload nel buffer in avanti, se necessario.

Dettagli
Parametri
[in] aAlignBytes
- specifica il numero di byte di allineamento per il puntatore di avvio del payload.
Restituisce
true se l'allineamento ha esito positivo, false se non c'è abbastanza spazio nel buffer.

AllocSize

size_t AllocSize(
  void
) const

Restituisce la dimensione dell'allocazione, inclusi gli spazi di dati riservati e di payload, ma escluso lo spazio allocato per la struttura PacketBuffer.

Dettagli
Restituisce
dimensione dell'allocazione

AvailableDataLength

uint16_t AvailableDataLength(
  void
) const

Ottieni il numero di byte di dati che possono essere aggiunti al buffer corrente in base alla posizione iniziale e alla lunghezza dei dati correnti.

Dettagli
Restituisce
la lunghezza, in byte, dei dati che verranno inseriti nel buffer corrente data la posizione iniziale e la lunghezza dei dati correnti.

CompactHead

void CompactHead(
  void
)

Sposta i dati dai buffer successivi della catena al buffer corrente fino a quando non è pieno.

Viene compattato solo il buffer corrente: i dati contenuti nel buffer corrente vengono spostati nella parte anteriore del buffer, eliminando qualsiasi spazio riservato. Lo spazio disponibile rimanente viene riempito con dati spostati dai buffer successivi nella catena, fino a esaurimento del buffer attuale. Se un tampone successivo della catena viene completamente spostato nel tampone di corrente, viene rimosso dalla catena e liberato. Il metodo non accetta parametri, non restituisce risultati e non può avere esito negativo.

Consuma

PacketBuffer * Consume(
  uint16_t aConsumeLength
)

Consuma i dati in una catena di buffer.

Consuma i dati in una catena di buffer a partire dal buffer attuale e procedendo attraverso i buffer rimanenti nella catena. Ogni buffer completamente utilizzato viene liberato e la funzione restituisce il primo buffer (se presente) contenente i dati rimanenti. Il buffer corrente deve essere l'inizio della catena del buffer.

Dettagli
Parametri
[in] aConsumeLength
- numero di byte da consumare dalla catena attuale.
Restituisce
il primo buffer della catena corrente che contiene i dati rimanenti. Se non rimangono dati, viene restituito un valore NULL.

ConsumeHead

void ConsumeHead(
  uint16_t aConsumeLength
)

Regola il buffer corrente per indicare la quantità di dati consumati.

Fai avanzare la posizione di inizio dei dati nel buffer corrente della quantità specificata, in byte, fino alla lunghezza dei dati nel buffer. Riduci la durata e la lunghezza totale in base alla quantità consumata.

Dettagli
Parametri
[in] aConsumeLen
- numero di byte da consumare dal buffer attuale.

DataLength

uint16_t DataLength(
  void
) const

Ottieni la lunghezza, in byte, dei dati nel buffer dei pacchetti.

Dettagli
Restituisce
in byte (lunghezza del payload attuale).

DetachTail

PacketBuffer * DetachTail(
  void
)

Scollega il buffer corrente dalla sua catena e restituisci un puntatore ai buffer rimanenti.

Il buffer corrente deve essere l'inizio della catena.

Dettagli
Restituisce
la coda della catena buffer corrente o NULL se il buffer corrente è l'unico buffer nella catena.

EnsureReservedSize

bool EnsureReservedSize(
  uint16_t aReservedSize
)

Assicurati che il buffer abbia almeno la quantità specificata di spazio riservato.

Assicurati che il buffer abbia almeno la quantità specificata di spazio riservato, spostando i dati nel buffer in avanti per liberare spazio, se necessario.

Dettagli
Parametri
[in] aReservedSize
- numero di byte desiderati per le intestazioni.
Restituisce
true se la dimensione prenotata richiesta è disponibile, false se non c'è abbastanza spazio nel buffer.

MaxDataLength

uint16_t MaxDataLength(
  void
) const

Ottieni la quantità massima, in byte, di dati che potrà essere inserita nel buffer in base alla posizione iniziale e alla dimensione del buffer correnti.

Dettagli
Restituisce
numero di byte che rientrano nel buffer data la posizione iniziale corrente.

Avanti

PacketBuffer * Next(
  void
) const

Ottieni il puntatore al buffer successivo nella catena.

Dettagli
Restituisce
un puntatore al buffer successivo nella catena. NULL viene restituito quando non ci sono buffer nella catena.

ReservedSize

uint16_t ReservedSize(
  void
) const

Ottieni il numero di byte all'interno del buffer attuale tra l'inizio del buffer e la posizione di inizio dati corrente.

Dettagli
Restituisce
la quantità, in byte, di spazio tra l'inizio del buffer e la posizione attuale di inizio dei dati.

SetDataLength

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

Imposta la lunghezza, in byte, dei dati nel buffer, regolando di conseguenza la lunghezza totale.

La funzione imposta la lunghezza, in byte, dei dati nel buffer, regolando la lunghezza totale in modo appropriato. Quando il buffer non è la testa della catena buffer (caso comune: il chiamante aggiunge dati all'ultimo buffer nella catena PacketBuffer prima di chiamare i livelli più alti), deve essere passato aChainHead per regolare correttamente le lunghezze totali di ciascun buffer prima del buffer corrente.

Dettagli
Parametri
[in] aNewLen
nuova lunghezza, in byte, di questo buffer.
[in,out] aChainHead
l'intestazione della catena a cui appartiene il buffer corrente. Può essere NULL se il buffer corrente è l'inizio della catena del buffer.

SetStart

void SetStart(
  uint8_t *aNewStart
)

Imposta i dati iniziali nel buffer, regolando di conseguenza la lunghezza e la lunghezza totale.

Dettagli
Parametri
[in] aNewStart
- Un puntatore al punto in cui deve iniziare il nuovo payload. Il valore newStart verrà regolato internamente in modo che rientri nei limiti del primo buffer nella catena PacketBuffer.

Inizia

uint8_t * Start(
  void
) const

Ottieni il puntatore all'inizio dei dati nel buffer.

Dettagli
Restituisce
all'inizio dei dati.

TotalLength

uint16_t TotalLength(
  void
) const

Ottieni la lunghezza totale dei dati del pacchetto nella catena del buffer.

Dettagli
Restituisce
lunghezza totale, in ottetti.

Funzioni statiche pubbliche

Senza costi

void Free(
  PacketBuffer *aPacket
)

Libera tutti i buffer di pacchetto in una catena.

Riduci il conteggio di riferimento a tutti i buffer nella catena corrente. Se il conteggio dei riferimenti raggiunge 0, i rispettivi buffer vengono liberati o restituiti ai pool di allocazione, a seconda dei casi. Come regola generale, gli utenti devono considerare questo metodo come equivalente della funzione free() e non utilizzare l'argomento dopo la chiamata.

Dettagli
Parametri
[in] aPacket
- buffer del pacchetto da liberare.

FreeHead

PacketBuffer * FreeHead(
  PacketBuffer *aPacket
)

Libera il primo buffer in una catena, restituendo un puntatore nei buffer rimanenti.

* @note When the buffer chain is referenced by multiple callers,FreeHead()` scollega la testina, ma non dilaziona forzatamente il buffer.

Dettagli
Parametri
[in] aPacket
- catena buffer.
Restituisce
catena di buffer di pacchetti costituita dalla coda del buffer di input (può essere NULL).

Novità

PacketBuffer * New(
  void
)

Alloca un singolo PacketBuffer di dimensione massima predefinita (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) con dimensione riservata predefinita (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) nel payload.

Le dimensioni riservate (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) sono abbastanza grandi da contenere le intestazioni del livello di trasporto e le intestazioni richieste da WeaveMessageLayer e WeaveExchangeLayer.

Novità

PacketBuffer * New(
  uint16_t aReservedSize
)

Alloca un singolo PacketBuffer di dimensione totale massima con una dimensione di prenotazione dell'intestazione specifica.

Il parametro trasmesso è la dimensione riservata prima del payload per ospitare le intestazioni dei pacchetti di diversi livelli di stack, non la dimensione complessiva del buffer da allocare. La dimensione del buffer WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX e non, specificata nella chiamata.

  • PacketBuffer::New(0) : se chiamato in questo modo, il buffer viene restituito senza intestazione riservata; di conseguenza, il chiamante può utilizzare l'intero payload. Questo pattern è particolarmente utile nei livelli inferiori degli stack di rete, nei casi in cui l'utente sappia che il payload verrà copiato nel messaggio finale con riserve di intestazione appropriate o per la creazione di PacketBuffer che vengono aggiunti a una catena di PacketBuffer tramite PacketBuffer::AddToEnd(). Parametri
    [in] aReservedSize
    molto spazio per le intestazioni da prenotare.
    Restituisce
    In caso di esito positivo, un puntatore a PacketBuffer, in caso di errore NULL.

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

Alloca un PacketBuffer con una dimensione riservata predefinita (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) nel payload per le intestazioni e almeno aAllocSize byte di spazio per dati aggiuntivi dopo il puntatore iniziale del cursore.

Questo è l'utilizzo più appropriato per l'allocazione di un PacketBuffer per un messaggio a livello di applicazione.

Dettagli
Parametri
[in] aAvailableSize
Numero di ottetti da allocare dopo il cursore.
Restituisce
In caso di esito positivo, un puntatore a PacketBuffer nel blocco allocato. In caso di errore, NULL. *

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

Alloca un oggetto PacketBuffer con almeno aReservedSize byte riservati nel payload per le intestazioni e almeno aAllocSize byte di spazio per dati aggiuntivi dopo il puntatore iniziale del cursore.

Dettagli
Parametri
[in] aReservedSize
Numero di ottetti da prenotare dietro il cursore.
[in] aAvailableSize
Numero di ottetti da allocare dopo il cursore.
Restituisce
In caso di esito positivo, un puntatore a PacketBuffer nel blocco allocato. In caso di errore, NULL.

RightSize

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

Copia il buffer specificato in un buffer delle dimensioni corrette, se applicabile.

Questa funzione è autonoma per i socket.

Dettagli
Parametri
[in] aPacket
- buffer o catena buffer.
Restituisce
buffer nuovo o originale