nl::Weave::System::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

La classe di buffer dei pacchetti è la struttura principale utilizzata per manipolare pacchetti di dati serializzati a ottetto, di solito nel contesto di una rete di comunicazione dati come il Bluetooth o il protocollo Internet.

Riepilogo

Negli ambienti basati su LwIP, questa classe è basata sulla struttura pbuf definita nella libreria. In assenza di LwIP, Weave fornisce un'implementazione basata su Malloc o 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 su ciascun livello di uno stack di comunicazione configurabile. Per maggiori dettagli, consulta PacketBuffer::New() e la documentazione LwIP.

Gli oggetti PacketBuffer vengono conteggiati per riferimento e la modalità di utilizzo prevalente in Weave è "fire-and-forget". Poiché il pacchetto (e l'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 il destinatario della chiamata è responsabile di liberare il buffer. In caso di errore di una chiamata cross-layer, la responsabilità di liberare il buffer resta del chiamante.

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

Gli oggetti PacketBuffer possono essere concatenati per ospitare payload più grandi. Il concatenamento, tuttavia, non è trasparente e gli utenti della classe devono decidere esplicitamente se supportarlo. Ecco alcuni esempi di classi scritte con il supporto per concatenamento: 

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

Eredità

Eredita da: pbuf

Funzioni pubbliche
AddRef(void)
void
Aumenta il conteggio dei riferimenti del buffer attuale.
AddToEnd(PacketBuffer *aPacket)
void
Aggiungi il buffer di pacchetti specificato alla fine della catena, 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 attuale in base alla posizione iniziale e alla lunghezza dei dati correnti.
CompactHead(void)
void
Sposta i dati dai buffer successivi della catena nel buffer attuale fino a esaurimento.
Consume(uint16_t aConsumeLength)
Consuma i dati in una catena di buffer.
ConsumeHead(uint16_t aConsumeLength)
void
Regola il buffer attuale per indicare la quantità di dati consumati.
DataLength(void) const
uint16_t
Ottieni la lunghezza, in byte, dei dati nel buffer di pacchetti.
DetachTail(void)
Scollega il buffer corrente dalla sua catena e restituisce 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 possono essere inseriti nel buffer in base alla posizione iniziale e alle dimensioni del buffer attuali.
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 dei dati corrente.
SetDataLength(uint16_t aNewLen, PacketBuffer *aChainHead)
void
Imposta la lunghezza, in byte, dei dati nel buffer, regolando la lunghezza totale di conseguenza.
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 dei pacchetti nella catena di buffer.

Funzioni statiche pubbliche
Free(PacketBuffer *aPacket)
void
Libera tutti i buffer dei pacchetti in una catena.
FreeHead(PacketBuffer *aPacket)
Libera il primo buffer di una catena, restituendo un puntatore ai 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 specifica della riserva di intestazioni.
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 i 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 i dati aggiuntivi dopo il puntatore iniziale del cursore.
RightSize(PacketBuffer *aPacket)
Copia il buffer specificato in un buffer di dimensioni corrette, se applicabile.

Funzioni pubbliche

AddRef

void AddRef(
  void
)

Aumenta il conteggio dei riferimenti del buffer attuale.

AddToEnd

void AddToEnd(
  PacketBuffer *aPacket
)

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

Dettagli
Parametri
[in] aPacket
- il buffer dei pacchetti da aggiungere alla fine della catena attuale.

AlignPayload

bool AlignPayload(
  uint16_t aAlignBytes
)

Allinea il payload del buffer al limite di byte specificato.

Sposta il payload nel buffer in avanti, se necessario.

Dettagli
Parametri
[in] aAlignBytes
- specifica l'allineamento del numero di byte per il puntatore di inizio del payload.
Restituisce
true se l'allineamento riesce, 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 attuale in base alla posizione iniziale e alla lunghezza dei dati correnti.

Dettagli
Restituisce
la lunghezza, in byte, dei dati che rientreranno nel buffer attuale in base alla posizione iniziale e alla lunghezza dei dati correnti.

CompactHead

void CompactHead(
  void
)

Sposta i dati dai buffer successivi della catena nel buffer attuale fino a esaurimento.

Viene compattato solo il buffer attuale: i dati all'interno del buffer vengono spostati nella parte anteriore del buffer, eliminando lo spazio riservato. Lo spazio disponibile rimanente viene riempito di dati spostati dai buffer successivi della catena, finché il buffer attuale non è pieno. Se un buffer successivo della catena viene spostato completamente nel buffer 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.

Consumare i dati in una catena di buffer che inizia con il buffer attuale e prosegue attraverso i buffer rimanenti della catena. Ogni buffer completamente utilizzato viene liberato e la funzione restituisce il primo buffer (se presente) contenente i dati rimanenti. Il buffer attuale deve essere l'intestazione della catena di buffer.

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

ConsumeHead

void ConsumeHead(
  uint16_t aConsumeLength
)

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

Fai avanzare la posizione iniziale dei dati nel buffer attuale in base alla quantità specificata, in byte, fino alla lunghezza dei dati nel buffer. Riduci la durata e la durata totale in base all'importo consumato.

Dettagli
Parametri
[in] aConsumeLen
- Numero di byte da utilizzare dal buffer attuale.

DataLength

uint16_t DataLength(
  void
) const

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

Dettagli
Restituisce
lunghezza del payload, in byte (lunghezza del payload attuale).

DetachTail

PacketBuffer * DetachTail(
  void
)

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

Il buffer attuale deve essere l'intestazione della catena.

Dettagli
Restituisce
alla coda della catena di buffer attuale oppure NULL se il buffer attuale è l'unico buffer della 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à di spazio riservato specificata, spostando i dati nel buffer in avanti per liberare spazio, se necessario.

Dettagli
Parametri
[in] aReservedSize
- Il 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 possono essere inseriti nel buffer in base alla posizione iniziale e alle dimensioni attuali del buffer.

Dettagli
Restituisce
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 la catena non contiene buffer.

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 dei dati corrente.

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

SetDataLength

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

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

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

Dettagli
Parametri
[in] aNewLen
- la nuova lunghezza, in byte, di questo buffer.
[in,out] aChainHead
- L'intestazione della catena di buffer a cui appartiene il buffer corrente. Può essere NULL se il buffer attuale è l'intestazione 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 dovrebbe iniziare il nuovo payload. newStart verrà modificato 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 dei pacchetti nella catena di buffer.

Dettagli
Restituisce
lunghezza totale, in ottetti.

Funzioni statiche pubbliche

Gratis

void Free(
  PacketBuffer *aPacket
)

Libera tutti i buffer dei pacchetti in una catena.

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

Dettagli
Parametri
[in] aPacket
- buffer di pacchetti da liberare.

FreeHead

PacketBuffer * FreeHead(
  PacketBuffer *aPacket
)

Libera il primo buffer di una catena, restituendo un puntatore ai buffer rimanenti.

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

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

Nuovo

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.

La dimensione riservata (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) è sufficientemente grande da contenere le intestazioni del livello di trasporto, così come le intestazioni richieste da WeaveMessageLayer e WeaveExchangeLayer.

Nuovo

PacketBuffer * New(
  uint16_t aReservedSize
)

Alloca un singolo PacketBuffer di dimensione totale massima con una dimensione specifica della riserva di intestazioni.

Il parametro passato corrisponde alla dimensione riservata prima del payload per contenere le intestazioni dei pacchetti da diversi livelli di stack, non la dimensione complessiva del buffer da allocare. Le dimensioni del buffer WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX e non, specificate nella chiamata.

  • PacketBuffer::New(0) : quando viene chiamato in questo modo, il buffer viene restituito senza nessuna intestazione riservata, di conseguenza l'intero payload è utilizzabile dal chiamante. Questo pattern è particolarmente utile nei livelli inferiori degli stack di rete, nei casi in cui l'utente sa che il payload verrà copiato nel messaggio finale con riserve di intestazioni appropriate o nella creazione di PacketBuffer che vengono aggiunti a una catena di PacketBuffer tramite PacketBuffer::AddToEnd(). Parametri
    [in] aReservedSize
    di spazio di intestazione da riservare.
    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 i dati aggiuntivi dopo il puntatore iniziale del cursore.

Questo utilizzo è più appropriato quando si alloca un PacketBuffer per un messaggio a livello di applicazione.

Dettagli
Parametri
[in] aAvailableSize
Numero di ottetti da allocare dopo il cursore.
Restituisce
Se l'operazione riesce, 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 i 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
Se l'operazione riesce, un puntatore a PacketBuffer nel blocco allocato. In caso di errore, NULL.

RightSize

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

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

Questa funzione è autonoma per i socket.

Dettagli
Parametri
[in] aPacket
- buffer chain o catena di buffer.
Restituisce
nuovo buffer di pacchetti o il buffer originale