nl::Weave::System::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

Die Paketpufferklasse ist die Kernstruktur zur Bearbeitung von Paketen mit okttet-serialisierten Daten, in der Regel im Zusammenhang mit einem Datenkommunikationsnetzwerk wie Bluetooth oder dem Internetprotokoll.

Zusammenfassung

In LwIP-basierten Umgebungen basiert diese Klasse auf der PBuf-Struktur, die in dieser Bibliothek definiert ist. Ohne LwIP bietet Weave entweder eine Malloc-basierte Implementierung oder eine Pool-basierte Implementierung an, die den Speicherherausforderungen von tief eingebetteten Geräten genau annähert.

Wie viele ähnliche Strukturen, die in mehrschichtigen Netzwerkstacks verwendet werden, bietet die Klasse PacketBuffer einen Mechanismus, mit dem auf jeder Ebene eines konfigurierbaren Kommunikationspakets Platz für Protokollheader reserviert wird. Weitere Informationen finden Sie unter PacketBuffer::New() sowie in der LwIP-Dokumentation.

Für PacketBuffer-Objekte wird Verweis gezählt und der vorherrschende Nutzungsmodus in Weave ist der Fire-and-Forget-Modus. Da das Paket (und das zugrunde liegende PacketBuffer-Objekt) über verschiedene Protokollebenen weitergeleitet werden, stellt der erfolgreiche Upcall oder Downcall zwischen den Ebenen eine Übertragung der Inhaberschaft dar und der Aufgerufene ist für die Freigabe des Puffers verantwortlich. Bei einem Fehler bei einem schichtübergreifenden Aufruf liegt die Verantwortung für die Freigabe des Puffers beim Aufrufer.

Neue Objekte der Klasse PacketBuffer werden zu Beginn einer Arbeitsspeicherzuweisung aus der zugrunde liegenden Umgebung initialisiert, z.B. aus LwIP-pbuf-Zielpools, aus dem Standard-C-Bibliotheks-Heap oder aus einem internen Pufferpool. Im einfachen Fall beträgt die Größe des Datenpuffers WEAVE_SYSTEM_PACKETBUFFER_SIZE. Es wird ein Composer bereitgestellt, der die Verwendung von Datenpuffern anderer Größen ermöglicht.

PacketBuffer-Objekte können verkettet werden, um größere Nutzlasten zu unterstützen. Verkettungen sind jedoch nicht transparent und die Nutzer der Klasse müssen explizit entscheiden, ob Verkettungen unterstützt werden. Beispiele für Klassen, die Verkettungen unterstützen: 

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

Übernahme

Übernommen von : pbuf

Öffentliche Funktionen
AddRef(void)
void
Erhöhen Sie die Referenzanzahl des aktuellen Puffers.
AddToEnd(PacketBuffer *aPacket)
void
Fügen Sie den angegebenen Paketpuffer am Ende der Pufferkette hinzu und passen Sie die Gesamtlänge jedes Puffers in der Kette entsprechend an.
AlignPayload(uint16_t aAlignBytes)
bool
Richten Sie die Zwischenspeichernutzlast an der angegebenen Bytegrenze aus.
AllocSize(void) const
size_t
Gibt die Größe der Zuweisung zurück, einschließlich der reservierten Datenbereiche und der Nutzlastdatenbereiche, jedoch ohne den für die PacketBuffer-Struktur zugewiesenen Speicherplatz.
AvailableDataLength(void) const
uint16_t
Ruft die Anzahl der Datenbyte ab, die dem aktuellen Puffer unter Berücksichtigung der aktuellen Startposition und Datenlänge hinzugefügt werden können.
CompactHead(void)
void
Verschieben Sie Daten aus nachfolgenden Puffern in der Kette in den aktuellen Puffer, bis dieser voll ist.
Consume(uint16_t aConsumeLength)
Daten in einer Pufferkette verarbeiten.
ConsumeHead(uint16_t aConsumeLength)
void
Passen Sie den aktuellen Puffer an, um die Menge der verbrauchten Daten anzuzeigen.
DataLength(void) const
uint16_t
Ruft die Länge der Daten im Paketpuffer in Byte ab.
DetachTail(void)
Den aktuellen Puffer von seiner Kette trennen und einen Zeiger an die verbleibenden Puffer zurückgeben.
EnsureReservedSize(uint16_t aReservedSize)
bool
Achten Sie darauf, dass der Zwischenspeicher mindestens die angegebene Menge an reserviertem Speicherplatz enthält.
MaxDataLength(void) const
uint16_t
Ruft die maximale Datenmenge in Byte ab, die unter Berücksichtigung der aktuellen Startposition und der Puffergröße in den Puffer passen.
Next(void) const
Ruft den Zeiger zum nächsten Zwischenspeicher in der Kette ab.
ReservedSize(void) const
uint16_t
Ruft die Anzahl der Byte im aktuellen Puffer zwischen dem Start des Puffers und der aktuellen Datenstartposition ab.
SetDataLength(uint16_t aNewLen, PacketBuffer *aChainHead)
void
Legen Sie die Länge der Daten im Puffer in Byte fest und passen Sie die Gesamtlänge entsprechend an.
SetStart(uint8_t *aNewStart)
void
Legen Sie die Startdaten im Puffer fest und passen Sie Länge und Gesamtlänge entsprechend an.
Start(void) const
uint8_t *
Ruft den Zeiger zum Anfang der Daten im Puffer ab.
TotalLength(void) const
uint16_t
Ruft die Gesamtlänge der Paketdaten in der Zwischenspeicherkette ab.

Öffentliche statische Funktionen
Free(PacketBuffer *aPacket)
void
Geben Sie alle Paketpuffer in einer Kette kostenlos.
FreeHead(PacketBuffer *aPacket)
Geben Sie den ersten Puffer in einer Kette kostenlos und geben Sie einen Zeiger zu den verbleibenden Puffern zurück.
New(void)
Weist einen einzelnen PacketBuffer mit der maximalen Standardgröße (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) mit der standardmäßig reservierten Größe (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) in der Nutzlast zu.
New(uint16_t aReservedSize)
Weist einen einzelnen PacketBuffer der maximalen Gesamtgröße mit einer bestimmten Header-Reservegröße zu.
NewWithAvailableSize(size_t aAvailableSize)
Weist einen PacketBuffer mit standardmäßig reservierter Größe (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) in der Nutzlast für Header und mindestens aAllocSize Byte Speicherplatz für zusätzliche Daten nach dem ersten Cursorzeiger zu.
NewWithAvailableSize(uint16_t aReservedSize, size_t aAvailableSize)
Weist ein PacketBuffer-Objekt mit mindestens aReservedSize Byte in der Nutzlast für Header und mindestens aAllocSize Byte Speicherplatz für zusätzliche Daten nach dem ersten Cursorzeiger zu.
RightSize(PacketBuffer *aPacket)
Kopieren Sie den angegebenen Puffer in einen Puffer der richtigen Größe (falls zutreffend).

Öffentliche Funktionen

AddRef

void AddRef(
  void
)

Erhöhen Sie die Referenzanzahl des aktuellen Puffers.

AddToEnd

void AddToEnd(
  PacketBuffer *aPacket
)

Fügen Sie den angegebenen Paketpuffer am Ende der Pufferkette hinzu und passen Sie die Gesamtlänge jedes Puffers in der Kette entsprechend an.

Details
Parameter
[in] aPacket
– der Paketpuffer, der dem Ende der aktuellen Kette hinzugefügt werden soll.

AlignPayload

bool AlignPayload(
  uint16_t aAlignBytes
)

Richten Sie die Zwischenspeichernutzlast an der angegebenen Bytegrenze aus.

Die Nutzlast im Puffer weiter nach vorne verschieben, falls erforderlich.

Details
Parameter
[in] aAlignBytes
– gibt die Anzahl der Byte-Ausrichtung für den Nutzlast-Startzeiger an.
Rückgabe
true, wenn der Abgleich erfolgreich ist, und false, wenn im Zwischenspeicher nicht genügend Platz ist.

AllocSize

size_t AllocSize(
  void
) const

Gibt die Größe der Zuweisung zurück, einschließlich der reservierten Datenbereiche und der Nutzlastdatenbereiche, jedoch ohne den für die PacketBuffer-Struktur zugewiesenen Speicherplatz.

Details
Rückgabe
Größe der Zuweisung

AvailableDataLength

uint16_t AvailableDataLength(
  void
) const

Ruft die Anzahl der Datenbyte ab, die dem aktuellen Puffer unter Berücksichtigung der aktuellen Startposition und Datenlänge hinzugefügt werden können.

Details
Rückgabe
Die Länge der Daten in Byte, die unter Berücksichtigung der aktuellen Startposition und Datenlänge in den aktuellen Puffer passen.

CompactHead

void CompactHead(
  void
)

Verschieben Sie Daten aus nachfolgenden Puffern in der Kette in den aktuellen Puffer, bis dieser voll ist.

Nur der aktuelle Puffer wird verdichtet: Die Daten innerhalb des aktuellen Puffers werden an den Anfang des Puffers verschoben, wodurch jeder reservierte Platz eliminiert wird. Der verbleibende verfügbare Speicherplatz wird mit Daten gefüllt, die aus nachfolgenden Puffern in der Kette verschoben werden, bis der aktuelle Puffer voll ist. Wenn ein nachfolgender Puffer in der Kette vollständig in den aktuellen Puffer verschoben wird, wird er aus der Kette entfernt und freigegeben. Die Methode verwendet keine Parameter, gibt keine Ergebnisse zurück und darf nicht fehlschlagen.

Lesen

PacketBuffer * Consume(
  uint16_t aConsumeLength
)

Daten in einer Pufferkette verarbeiten.

Daten in einer Kette von Puffern verarbeiten, beginnend mit dem aktuellen Puffer durch die verbleibenden Puffer in der Kette. Jeder vollständig verbrauchte Puffer wird freigegeben, und die Funktion gibt den ersten Puffer (falls vorhanden) mit den verbleibenden Daten zurück. Der aktuelle Zwischenspeicher muss der Anfang der Pufferkette sein.

Details
Parameter
[in] aConsumeLength
– Anzahl der Byte, die von der aktuellen Kette genutzt werden sollen.
Rückgabe
ersten Puffer aus der aktuellen Kette, der alle verbleibenden Daten enthält. Wenn keine Daten mehr vorhanden sind, wird NULL zurückgegeben.

ConsumeHead

void ConsumeHead(
  uint16_t aConsumeLength
)

Passen Sie den aktuellen Puffer an, um die Menge der verbrauchten Daten anzuzeigen.

Verschiebt die Datenstartposition im aktuellen Zwischenspeicher um die angegebene Menge in Byte bis zur Länge der Daten im Zwischenspeicher. Verringere die Länge und Gesamtlänge um die aufgenommene Menge.

Details
Parameter
[in] aConsumeLen
– Anzahl der Byte, die aus dem aktuellen Puffer genutzt werden sollen.

DataLength

uint16_t DataLength(
  void
) const

Ruft die Länge der Daten im Paketpuffer in Byte ab.

Details
Rückgabe
in Byte (aktuelle Nutzlastlänge).

DetachTail

PacketBuffer * DetachTail(
  void
)

Den aktuellen Puffer von seiner Kette trennen und einen Zeiger an die verbleibenden Puffer zurückgeben.

Der aktuelle Zwischenspeicher muss der Anfang der Kette sein.

Details
Rückgabe
das Ende der aktuellen Pufferkette oder NULL, wenn der aktuelle Puffer der einzige Puffer in der Kette ist.

EnsureReservedSize

bool EnsureReservedSize(
  uint16_t aReservedSize
)

Achten Sie darauf, dass der Zwischenspeicher mindestens die angegebene Menge an reserviertem Speicherplatz enthält.

Stellen Sie sicher, dass der Puffer mindestens über die angegebene Menge an reserviertem Speicherplatz verfügt, um die Daten im Puffer weiter nach vorne zu bewegen, um gegebenenfalls Platz zu schaffen.

Details
Parameter
[in] aReservedSize
– Anzahl der für die Header gewünschten Bytes.
Rückgabe
true, wenn die angeforderte reservierte Größe verfügbar ist, und false, wenn im Puffer nicht genügend Platz ist.

MaxDataLength

uint16_t MaxDataLength(
  void
) const

Ruft die maximale Datenmenge in Byte ab, die unter Berücksichtigung der aktuellen Startposition und der Puffergröße in den Puffer passen.

Details
Rückgabe
Anzahl Byte, die unter Berücksichtigung der aktuellen Startposition in den Puffer passen.

Weiter

PacketBuffer * Next(
  void
) const

Ruft den Zeiger zum nächsten Zwischenspeicher in der Kette ab.

Details
Rückgabe
einen Zeiger auf den nächsten Puffer in der Kette. NULL wird zurückgegeben, wenn in der Kette keine Puffer vorhanden sind.

ReservedSize

uint16_t ReservedSize(
  void
) const

Ruft die Anzahl der Byte im aktuellen Puffer zwischen dem Start des Puffers und der aktuellen Datenstartposition ab.

Details
Rückgabe
Die Größe des Speicherplatzes in Byte zwischen dem Anfang des Puffers und der aktuellen Daten-Startposition.

SetDataLength

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

Legen Sie die Länge der Daten im Puffer in Byte fest und passen Sie die Gesamtlänge entsprechend an.

Die Funktion legt die Länge der Daten im Puffer in Byte fest und passt die Gesamtlänge entsprechend an. Wenn der Puffer nicht der Anfang der Pufferkette ist (häufiger Fall: Der Aufrufer fügt dem letzten Puffer in der PacketBuffer-Kette Daten hinzu, bevor höhere Ebenen aufgerufen werden), muss aChainHead übergeben werden, um die Gesamtlänge der einzelnen Puffer korrekt vor dem aktuellen Puffer anzupassen.

Details
Parameter
[in] aNewLen
– Neue Länge dieses Puffers in Byte.
[in,out] aChainHead
– Kopf der Pufferkette, zu der der aktuelle Puffer gehört Kann NULL sein, wenn der aktuelle Zwischenspeicher am Anfang der Pufferkette steht.

SetStart

void SetStart(
  uint8_t *aNewStart
)

Legen Sie die Startdaten im Puffer fest und passen Sie Länge und Gesamtlänge entsprechend an.

Details
Parameter
[in] aNewStart
– Ein Zeiger, wo die neue Nutzlast beginnen soll. „newStart“ wird intern so angepasst, dass es in die Grenzen des ersten Puffers in der PacketBuffer-Kette fällt.

Starten

uint8_t * Start(
  void
) const

Ruft den Zeiger zum Anfang der Daten im Puffer ab.

Details
Rückgabe
Zeiger auf den Anfang der Daten.

TotalLength

uint16_t TotalLength(
  void
) const

Ruft die Gesamtlänge der Paketdaten in der Zwischenspeicherkette ab.

Details
Rückgabe
Gesamtlänge in Oktetten.

Öffentliche statische Funktionen

Kostenlos

void Free(
  PacketBuffer *aPacket
)

Geben Sie alle Paketpuffer in einer Kette kostenlos.

Verringern Sie die Anzahl der Verweise auf alle Puffer in der aktuellen Kette. Wenn die Referenzzahl 0 erreicht, werden die entsprechenden Puffer freigegeben oder nach Bedarf an Zuweisungspools zurückgegeben. In der Regel sollten Nutzer diese Methode als Äquivalent der free()-Funktion behandeln und das Argument nach dem Aufruf nicht verwenden.

Details
Parameter
[in] aPacket
– Der Paketzwischenspeicher, der freigegeben werden soll.

FreeHead

PacketBuffer * FreeHead(
  PacketBuffer *aPacket
)

Geben Sie den ersten Puffer in einer Kette kostenlos und geben Sie einen Zeiger zu den verbleibenden Puffern zurück.

* @note When the buffer chain is referenced by multiple callers,FreeHead()` löst den Kopf ab, die Aufhebung der Zuweisung des Head-Zwischenspeichers wird jedoch nicht erzwungen.

Details
Parameter
[in] aPacket
– Pufferkette.
Rückgabe
Paketpufferkette, die aus dem Ende des Eingabepuffers besteht (kann NULL sein).

Neu

PacketBuffer * New(
  void
)

Weist einen einzelnen PacketBuffer mit der maximalen Standardgröße (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) mit der standardmäßig reservierten Größe (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) in der Nutzlast zu.

Die reservierte Größe (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) ist groß genug, um Transportschicht-Header sowie Header aufzunehmen, die für WeaveMessageLayer und WeaveExchangeLayer erforderlich sind.

Neu

PacketBuffer * New(
  uint16_t aReservedSize
)

Weist einen einzelnen PacketBuffer der maximalen Gesamtgröße mit einer bestimmten Header-Reservegröße zu.

Der übergebene Parameter ist die vor der Nutzlast reservierte Größe, um Paketheader aus verschiedenen Stackebenen zu berücksichtigen, und nicht die Gesamtgröße des zuzuweisenden Zwischenspeichers. Die im Aufruf angegebene Größe des Puffers WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX.

  • PacketBuffer::New(0) : Bei einem solchen Aufruf wird der Puffer ohne reservierten Header zurückgegeben. Folglich kann die gesamte Nutzlast vom Aufrufer verwendet werden. Dieses Muster ist besonders nützlich auf den unteren Ebenen von Netzwerkstacks, in Fällen, in denen der Nutzer weiß, dass die Nutzlast mit entsprechenden Header-Reserven in die endgültige Nachricht kopiert wird, oder beim Erstellen von PacketBuffer, der über PacketBuffer::AddToEnd() an eine Kette von PacketBuffer angehängt wird. Parameter
    [in] aReservedSize
    zu reservieren.
    Rückgabe
    Bei Erfolg ein Verweis auf PacketBuffer, bei Fehler NULL.

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

Weist einen PacketBuffer mit standardmäßig reservierter Größe (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) in der Nutzlast für Header und mindestens aAllocSize Byte Speicherplatz für zusätzliche Daten nach dem ersten Cursorzeiger zu.

Dies ist am besten geeignet, wenn ein PacketBuffer für eine Nachricht auf Anwendungsebene zugeordnet wird.

Details
Parameter
[in] aAvailableSize
Anzahl der Oktette, die nach dem Cursor zugewiesen werden sollen.
Rückgabe
Bei Erfolg ein Verweis auf den PacketBuffer im zugewiesenen Block. Bei Fehler NULL. *

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

Weist ein PacketBuffer-Objekt mit mindestens aReservedSize Byte in der Nutzlast für Header und mindestens aAllocSize Byte Speicherplatz für zusätzliche Daten nach dem ersten Cursorzeiger zu.

Details
Parameter
[in] aReservedSize
Anzahl der Oktette, die hinter dem Cursor reserviert werden sollen.
[in] aAvailableSize
Anzahl der Oktette, die nach dem Cursor zugewiesen werden sollen.
Rückgabe
Bei Erfolg ein Verweis auf den PacketBuffer im zugewiesenen Block. Bei Fehler NULL.

RightSize

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

Kopieren Sie den angegebenen Puffer in einen Puffer der richtigen Größe (falls zutreffend).

Diese Funktion ist ein No-Op für Sockets.

Details
Parameter
[in] aPacket
– Puffer- oder Pufferkette.
Rückgabe
Neuer Paketpuffer oder ursprünglicher Zwischenspeicher