nl::Weave::System::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

Die Paketpufferklasse ist die Kernstruktur, die zur Manipulation von Paketen mit Oktett-serialisierten Daten verwendet wird, normalerweise 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. Fehlt LwIP, bietet Weave entweder eine Malloc-basierte Implementierung oder eine Pool-basierte Implementierung an, mit der sich die Speicherherausforderungen tief eingebetteter Geräte nahezu vollständig bewältigen lassen.

Die Klasse PacketBuffer bietet wie viele ähnliche Strukturen, die in mehrschichtigen Netzwerkstacks verwendet werden, einen Mechanismus, um auf jeder Schicht eines konfigurierbaren Kommunikationsstacks Platz für Protokollheader zu reservieren. Weitere Informationen finden Sie in der Dokumentation zu PacketBuffer::New() und LwIP.

PacketBuffer-Objekte werden durch Referenzen gezählt und der überwiegende Verwendungsmodus in Weave ist „Fire-and-Forget“. Da das Paket und sein zugrunde liegendes PacketBuffer-Objekt über verschiedene Protokollebenen weitergeleitet werden, impliziert der erfolgreiche Up- oder Downcall zwischen den Ebenen eine Übertragung der Inhaberschaft. Der Aufgerufene ist dafür verantwortlich, den Zwischenspeicher freizugeben. Wenn ein schichtübergreifender Aufruf fehlschlägt, liegt die Verantwortung für das Freigeben des Zwischenspeichers 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 Heap der Standard-C-Bibliothek und aus einem internen Zwischenspeicherpool. Im einfachen Fall beträgt die Größe des Datenpuffers WEAVE_SYSTEM_PACKETBUFFER_SIZE. Ein Composer wird bereitgestellt, der die Verwendung von Datenpuffern anderer Größen ermöglicht.

PacketBuffer-Objekte können für größere Nutzlasten verkettet werden. Die Verkettung ist jedoch nicht transparent und die Nutzer der Klasse müssen sich explizit dafür entscheiden, Verkettungen zu unterstützen. Beispiele für Klassen mit Unterstützung für Verkettungen sind: 

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

Übernahme

Übernimmt von : pbuf

Öffentliche Funktionen
AddRef(void)
void
Erhöht den Referenzwert des aktuellen Zwischenspeichers.
AddToEnd(PacketBuffer *aPacket)
void
Fügen Sie den angegebenen Paketzwischenspeicher am Ende der Pufferkette hinzu und passen Sie die Gesamtlänge jedes Zwischenspeichers in der Kette entsprechend an.
AlignPayload(uint16_t aAlignBytes)
bool
Richtet die Zwischenspeichernutzlast an der angegebenen Bytegrenze aus.
AllocSize(void) const
size_t
Gibt die Größe der Zuweisung zurück, einschließlich der reservierten und Nutzlast-Datenbereiche, aber ohne den für die PacketBuffer-Struktur zugewiesenen Speicherplatz.
AvailableDataLength(void) const
uint16_t
Ruft die Anzahl von Datenbyte ab, die dem aktuellen Zwischenspeicher 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 Zwischenspeicher, bis sie voll sind.
Consume(uint16_t aConsumeLength)
Daten in einer Kette von Puffern verarbeiten.
ConsumeHead(uint16_t aConsumeLength)
void
Passen Sie den aktuellen Zwischenspeicher an, um die verbrauchte Datenmenge anzugeben.
DataLength(void) const
uint16_t
Ruft die Länge der Daten im Paketzwischenspeicher in Byte ab.
DetachTail(void)
Trennen Sie den aktuellen Zwischenspeicher von seiner Kette und geben Sie einen Zeiger an die verbleibenden Zwischenspeicher zurück.
EnsureReservedSize(uint16_t aReservedSize)
bool
Achten Sie darauf, dass der Puffer mindestens den angegebenen reservierten Speicherplatz hat.
MaxDataLength(void) const
uint16_t
Ruft die maximale Menge von Daten in Byte ab, die unter Berücksichtigung der aktuellen Startposition und Puffergröße in den Zwischenspeicher passen.
Next(void) const
Zeiger zum nächsten Zwischenspeicher in der Kette abrufen.
ReservedSize(void) const
uint16_t
Ruft die Anzahl der Byte im aktuellen Zwischenspeicher zwischen dem Start des Zwischenspeichers und der aktuellen Datenstartposition ab.
SetDataLength(uint16_t aNewLen, PacketBuffer *aChainHead)
void
Legt die Länge der Daten im Zwischenspeicher in Byte fest und passt die Gesamtlänge entsprechend an.
SetStart(uint8_t *aNewStart)
void
Legen Sie die Startdaten als Puffer fest und passen Sie Länge und Gesamtlänge entsprechend an.
Start(void) const
uint8_t *
Zeiger zum Anfang der Daten im Zwischenspeicher abrufen.
TotalLength(void) const
uint16_t
Gesamtlänge der Paketdaten in der Zwischenspeicherkette abrufen.

Öffentliche statische Funktionen
Free(PacketBuffer *aPacket)
void
Alle Paketzwischenspeicher in einer Kette freigeben.
FreeHead(PacketBuffer *aPacket)
Geben Sie den ersten Zwischenspeicher in einer Kette kostenlos und geben Sie einen Zeiger zu den verbleibenden Zwischenspeichern zurück.
New(void)
Weist einen einzelnen PacketBuffer der standardmäßigen maximalen Größe (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) mit standardmäßig reservierter 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 Headern einen PacketBuffer mit standardmäßig reservierter Größe (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) und nach dem anfänglichen Cursorzeiger mindestens aAllocSize Byte Speicherplatz für zusätzliche Daten 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 anfänglichen Cursorzeiger zu.
RightSize(PacketBuffer *aPacket)
Kopieren Sie den angegebenen Zwischenspeicher gegebenenfalls in einen Zwischenspeicher der richtigen Größe.

Öffentliche Funktionen

AddRef

void AddRef(
  void
)

Erhöht den Referenzwert des aktuellen Zwischenspeichers.

AddToEnd

void AddToEnd(
  PacketBuffer *aPacket
)

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

Details
Parameter
[in] aPacket
– Paketzwischenspeicher, der an das Ende der aktuellen Kette hinzugefügt werden soll

AlignPayload

bool AlignPayload(
  uint16_t aAlignBytes
)

Richtet die Zwischenspeichernutzlast an der angegebenen Bytegrenze aus.

Die Nutzlast im Zwischenspeicher wird bei Bedarf vorwärts bewegt.

Details
Parameter
[in] aAlignBytes
gibt die Ausrichtung der Byte für den Nutzlaststartzeiger an.
Rückgabe
true bei erfolgreicher Ausrichtung, 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 und Nutzlast-Datenbereiche, aber ohne den für die PacketBuffer-Struktur zugewiesenen Speicherplatz.

Details
Rückgabe
Umfang der Zuweisung

AvailableDataLength

uint16_t AvailableDataLength(
  void
) const

Ruft die Anzahl von Datenbyte ab, die dem aktuellen Zwischenspeicher 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 Zwischenspeicher passen.

CompactHead

void CompactHead(
  void
)

Verschieben Sie Daten aus nachfolgenden Puffern in der Kette in den aktuellen Zwischenspeicher, bis sie voll sind.

Nur der aktuelle Zwischenspeicher wird verdichtet: Die Daten im aktuellen Zwischenspeicher werden an den Anfang des Zwischenspeichers verschoben, um reservierten Platz zu entfernen. Der verbleibende verfügbare Speicherplatz wird mit Daten gefüllt, die aus nachfolgenden Zwischenspeichern in der Kette verschoben werden, bis der aktuelle Zwischenspeicher voll ist. Wenn ein nachfolgender Zwischenspeicher in der Kette vollständig in den aktuellen Zwischenspeicher verschoben wird, wird er aus der Kette entfernt und freigegeben. Die Methode akzeptiert keine Parameter, gibt keine Ergebnisse zurück und kann nicht fehlschlagen.

Lesen

PacketBuffer * Consume(
  uint16_t aConsumeLength
)

Daten in einer Kette von Puffern verarbeiten.

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

Details
Parameter
[in] aConsumeLength
– Anzahl der Byte, die von der aktuellen Kette verbraucht werden sollen.
Rückgabe
ersten Zwischenspeicher 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 Zwischenspeicher an, um die verbrauchte Datenmenge anzugeben.

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 die Gesamtlänge um die verbrauchte Menge.

Details
Parameter
[in] aConsumeLen
– Anzahl der Byte, die vom aktuellen Zwischenspeicher genutzt werden sollen.

DataLength

uint16_t DataLength(
  void
) const

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

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

DetachTail

PacketBuffer * DetachTail(
  void
)

Trennen Sie den aktuellen Zwischenspeicher von seiner Kette und geben Sie einen Zeiger an die verbleibenden Zwischenspeicher zurück.

Der aktuelle Zwischenspeicher muss der Anfang der Kette sein.

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

EnsureReservedSize

bool EnsureReservedSize(
  uint16_t aReservedSize
)

Achten Sie darauf, dass der Puffer mindestens den angegebenen reservierten Speicherplatz hat.

Stellen Sie sicher, dass der Puffer mindestens über den angegebenen reservierten Platz verfügt, um die Daten im Puffer nach vorne zu verschieben, um bei Bedarf Platz zu schaffen.

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

MaxDataLength

uint16_t MaxDataLength(
  void
) const

Ruft die maximale Menge von Daten in Byte ab, die unter Berücksichtigung der aktuellen Startposition und Puffergröße in den Zwischenspeicher passen.

Details
Rückgabe
Anzahl von Byte, die in den Zwischenspeicher passen, wenn die aktuelle Startposition angegeben ist.

Weiter

PacketBuffer * Next(
  void
) const

Zeiger zum nächsten Zwischenspeicher in der Kette abrufen.

Details
Rückgabe
zum nächsten Puffer in der Kette. NULL wird zurückgegeben, wenn die Kette keine Zwischenspeicher hat.

ReservedSize

uint16_t ReservedSize(
  void
) const

Ruft die Anzahl der Byte im aktuellen Zwischenspeicher zwischen dem Start des Zwischenspeichers und der aktuellen Datenstartposition ab.

Details
Rückgabe
Der Abstand zwischen dem Start des Zwischenspeichers und der aktuellen Datenstartposition in Byte.

SetDataLength

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

Legt die Länge der Daten im Zwischenspeicher in Byte fest und passt die Gesamtlänge entsprechend an.

Die Funktion legt die Länge der Daten im Zwischenspeicher in Byte fest und passt die Gesamtlänge entsprechend an. Wenn der Zwischenspeicher nicht der Anfang der Zwischenspeicherkette ist (häufiger Fall, dass der Aufrufer dem letzten Zwischenspeicher in der PacketBuffer-Kette Daten vor dem Aufrufen höherer Layers hinzufügt), muss der aChainHead übergeben werden, um die Gesamtlänge jedes Zwischenspeichers vor dem aktuellen Zwischenspeicher richtig anzupassen.

Details
Parameter
[in] aNewLen
- neue Länge dieses Zwischenspeichers in Byte.
[in,out] aChainHead
– Head der Pufferkette, zu dem der aktuelle Puffer gehört. Kann NULL sein, wenn der aktuelle Zwischenspeicher der Kopf der Pufferkette ist.

SetStart

void SetStart(
  uint8_t *aNewStart
)

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

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

Start

uint8_t * Start(
  void
) const

Zeiger zum Anfang der Daten im Zwischenspeicher abrufen.

Details
Rückgabe
Zeiger zum Anfang der Daten.

TotalLength

uint16_t TotalLength(
  void
) const

Gesamtlänge der Paketdaten in der Zwischenspeicherkette abrufen.

Details
Rückgabe
Gesamtlänge in Oktetten.

Öffentliche statische Funktionen

Kostenlos

void Free(
  PacketBuffer *aPacket
)

Alle Paketzwischenspeicher in einer Kette freigeben.

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

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

FreeHead

PacketBuffer * FreeHead(
  PacketBuffer *aPacket
)

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

* @note When the buffer chain is referenced by multiple callers,FreeHead()` trennt den Kopf, hebt jedoch die Zuweisung des Kopfzwischenspeichers nicht auf.

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

Neu

PacketBuffer * New(
  void
)

Weist einen einzelnen PacketBuffer der standardmäßigen maximalen Größe (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) mit standardmäßig reservierter 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 Header der Transportschicht sowie Header, die von WeaveMessageLayer und WeaveExchangeLayer benötigt werden, aufzunehmen.

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 Größe, die vor der Nutzlast reserviert wurde, um Paketheader aus verschiedenen Stackebenen aufzunehmen, und nicht die Gesamtgröße des zuzuweisenden Zwischenspeichers. Die im Aufruf angegebene Größe des Zwischenspeichers WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX.

  • PacketBuffer::New(0) : Bei diesem Aufruf wird der Zwischenspeicher ohne reservierte Header zurückgegeben. Folglich kann die gesamte Nutzlast vom Aufrufer verwendet werden. Dieses Muster ist besonders auf den unteren Ebenen von Netzwerkstacks nützlich, wenn der Nutzer weiß, dass die Nutzlast mit entsprechenden Headerreserven in die endgültige Nachricht kopiert wird, oder beim Erstellen von PacketBuffer, die über PacketBuffer::AddToEnd() an eine Kette von PacketBuffer angehängt werden. Parameter
    [in] aReservedSize
    viel Platz für den Header, der reserviert werden soll.
    Rückgabe
    Bei Erfolg ein Zeiger auf den PacketBuffer, bei Fehler NULL.

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

Weist Headern einen PacketBuffer mit standardmäßig reservierter Größe (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) und nach dem anfänglichen Cursorzeiger mindestens aAllocSize Byte Speicherplatz für zusätzliche Daten zu.

Diese Verwendung eignet sich am besten zum Zuweisen eines PacketBuffer zu einer Nachricht auf Anwendungsebene.

Details
Parameter
[in] aAvailableSize
Anzahl der Oktette, die nach dem Cursor zugewiesen werden sollen.
Rückgabe
Bei Erfolg ein Zeiger 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 anfänglichen 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 Zeiger auf den PacketBuffer im zugewiesenen Block. Bei Fehler: NULL.

RightSize

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

Kopieren Sie den angegebenen Zwischenspeicher gegebenenfalls in einen Zwischenspeicher der richtigen Größe.

Diese Funktion ist ein Leerbefehl für Sockets.

Details
Parameter
[in] aPacket
– Pufferkette oder Pufferkette.
Rückgabe
neuen Paketzwischenspeicher oder ursprünglichen Zwischenspeicher