nl::Weave::System::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

Klasa bufora pakietów to podstawowa struktura używana do manipulowania pakietami danych zserializowanych w oktecie, zwykle w kontekście sieci komunikacyjnej, takiej jak Bluetooth lub protokół internetowy.

Podsumowanie

W środowiskach opartych na LwIP ta klasa jest tworzona na podstawie struktury pbuf zdefiniowanej w tej bibliotece. W przypadku braku LwIP Weave udostępnia implementację opartą na assetoc lub pulach, która ściśle odzwierciedla problemy z pamięcią w przypadku urządzeń głęboko osadzonych.

Klasa PacketBuffer, podobnie jak wiele podobnych struktur używanych w warstwowych stosach sieciowych, zapewnia mechanizm rezerwowania miejsca na nagłówki protokołów w każdej warstwie konfigurowalnego stosu komunikacji. Więcej informacji znajdziesz na stronie PacketBuffer::New() oraz w dokumentacji LwIP.

Obiekty PacketBuffer są liczone jako obiekty referencyjne, a najważniejszy tryb użytkowania w Weave to „wypal i zapomnij”. Pakiet (i jego bazowy obiekt PacketBuffer) jest wysyłany przez różne warstwy protokołów, więc pomyślne wywołanie wywołania w górę lub w dół między warstwami oznacza przeniesienie własności, a osoba wywołująca odpowiada za zwolnienie bufora. W przypadku błędu wywołania międzywarstwowego odpowiedzialność za zwolnienie bufora spoczywa na elemencie wywołującym.

Nowe obiekty klasy PacketBuffer są inicjowane na początku przydziału pamięci uzyskanej ze środowiska bazowego, np. z pul docelowych LwIP pbuf, ze standardowej sterty biblioteki C, z wewnętrznej puli bufora. W najprostszym przypadku rozmiar bufora danych wynosi WEAVE_SYSTEM_PACKETBUFFER_SIZE. Dostępny jest kompozytor, który pozwala na używanie buforów danych o innych rozmiarach.

Obiekty PacketBuffer mogą być łączone w łańcuchy, aby obsłużyć większe ładunki. Łańcuchy nie są jednak przejrzyste, a użytkownicy klasy muszą wyraźnie zdecydować się na obsługę łańcuchów. Przykłady klas utworzonych z obsługą łańcuszków: 

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

Dziedziczenie

Dziedziczy z: pbuf

Funkcje publiczne
AddRef(void)
void
Zwiększ liczbę odwołań bieżącego bufora.
AddToEnd(PacketBuffer *aPacket)
void
Dodaj dany bufor pakietów na końcu łańcucha bufora, aby odpowiednio dopasować całkowitą długość każdego bufora w łańcuchu.
AlignPayload(uint16_t aAlignBytes)
bool
Wyrównaj ładunek bufora na określonej granicy bajtów.
AllocSize(void) const
size_t
Zwraca rozmiar alokacji, w tym zarezerwowane przestrzenie danych i przestrzenie danych ładunku, ale bez miejsca przydzielonego na potrzeby struktury PacketBuffer.
AvailableDataLength(void) const
uint16_t
Pobierz liczbę bajtów danych, które można dodać do bieżącego bufora przy bieżącej pozycji początkowej i długości danych.
CompactHead(void)
void
Przenoś dane z kolejnych buforów w łańcuchu do bieżącego bufora, aż będzie zapełniony.
Consume(uint16_t aConsumeLength)
Wykorzystuj dane w łańcuchu buforów.
ConsumeHead(uint16_t aConsumeLength)
void
Dostosuj bieżący bufor, aby wskazać ilość wykorzystywanych danych.
DataLength(void) const
uint16_t
Pobranie długości danych w buforze pakietów (w bajtach).
DetachTail(void)
Odłącz bieżący bufor od łańcucha i zwróć wskaźnik do pozostałych buforów.
EnsureReservedSize(uint16_t aReservedSize)
bool
Sprawdź, czy bufor ma co najmniej określoną ilość zarezerwowanego miejsca.
MaxDataLength(void) const
uint16_t
Uzyskaj maksymalną ilość danych (w bajtach), która zmieści się w buforze przy bieżącej pozycji początkowej i rozmiarze bufora.
Next(void) const
Wskaźnik do następnego bufora w łańcuchu.
ReservedSize(void) const
uint16_t
Pobierz liczbę bajtów w bieżącym buforze między początkiem bufora a bieżącą pozycją początkową danych.
SetDataLength(uint16_t aNewLen, PacketBuffer *aChainHead)
void
Ustaw długość danych w buforze (w bajtach) i odpowiednio dostosujesz jej łączną długość.
SetStart(uint8_t *aNewStart)
void
Ustaw dane początkowe w buforze, odpowiednio dostosowując długość i całkowitą długość.
Start(void) const
uint8_t *
Pobierz wskaźnik początkowy danych w buforze.
TotalLength(void) const
uint16_t
Uzyskaj łączną długość danych pakietów w łańcuchu bufora.

Publiczne funkcje statyczne
Free(PacketBuffer *aPacket)
void
Zwolnij wszystkie bufory pakietów w łańcuchu.
FreeHead(PacketBuffer *aPacket)
Zwolnij pierwszy bufor w łańcuchu, zwracając wskaźnik do pozostałych buforów.
New(void)
Przypisuje pojedynczy element PacketBuffer o domyślnym maksymalnym rozmiarze (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) z domyślnym zarezerwowanym rozmiarem (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) w ładunku.
New(uint16_t aReservedSize)
Przypisuje pojedynczy element PacketBuffer o maksymalnym rozmiarze całkowitym z określonym rozmiarem rezerwy nagłówka.
NewWithAvailableSize(size_t aAvailableSize)
Przypisuje element PacketBuffer o domyślnym zarezerwowanym rozmiarze (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) w ładunku na potrzeby nagłówków i na potrzeby co najmniej aAllocSize B miejsca na dodatkowe dane po początkowym wskaźniku kursora.
NewWithAvailableSize(uint16_t aReservedSize, size_t aAvailableSize)
Przypisuje obiekt PacketBuffer z co najmniej aReservedSize bajtami zarezerwowanych w ładunku na potrzeby nagłówków oraz co najmniej aAllocSize bajtami miejsca na dodatkowe dane po początkowym wskaźniku kursora.
RightSize(PacketBuffer *aPacket)
W razie potrzeby skopiuj podany bufor do bufora o odpowiednim rozmiarze.

Funkcje publiczne

AddRef

void AddRef(
  void
)

Zwiększ liczbę odwołań bieżącego bufora.

AddToEnd

void AddToEnd(
  PacketBuffer *aPacket
)

Dodaj dany bufor pakietów na końcu łańcucha bufora, aby odpowiednio dopasować całkowitą długość każdego bufora w łańcuchu.

Szczegóły
Parametry
[in] aPacket
– bufor pakietów, który ma zostać dodany na końcu bieżącego łańcucha.

AlignPayload

bool AlignPayload(
  uint16_t aAlignBytes
)

Wyrównaj ładunek bufora na określonej granicy bajtów.

W razie potrzeby przeniesienie ładunku w buforze do przodu.

Szczegóły
Parametry
[in] aAlignBytes
– określa wyrównanie liczby bajtów dla wskaźnika początkowego ładunku.
Zwroty
true, jeśli wyrównanie się powiedzie, false, jeśli w buforie jest za mało miejsca.

AllocSize

size_t AllocSize(
  void
) const

Zwraca rozmiar alokacji, w tym zarezerwowane przestrzenie danych i przestrzenie danych ładunku, ale bez miejsca przydzielonego na potrzeby struktury PacketBuffer.

Szczegóły
Zwroty
rozmiar przydziału

AvailableDataLength

uint16_t AvailableDataLength(
  void
) const

Pobierz liczbę bajtów danych, które można dodać do bieżącego bufora przy bieżącej pozycji początkowej i długości danych.

Szczegóły
Zwroty
długość danych (w bajtach), które zmieści się w bieżącym buforze przy bieżącej pozycji początkowej i długości danych.

CompactHead

void CompactHead(
  void
)

Przenoś dane z kolejnych buforów w łańcuchu do bieżącego bufora, aż będzie zapełniony.

Kompresowany jest tylko bieżący bufor: dane z bieżącego bufora są przenoszone na jego początek, eliminując zarezerwowaną przestrzeń. Pozostała przestrzeń jest wypełniana danymi przeniesionymi z kolejnych buforów w łańcuchu do momentu zapełnienia bieżącego bufora. Jeśli kolejny bufor w łańcuchu zostanie przeniesiony w całości do bieżącego bufora, zostanie usunięty z łańcucha i zwolniony. Metoda nie przyjmuje żadnych parametrów, nie zwraca żadnych wyników i nie może zakończyć się niepowodzeniem.

Konsumpcja

PacketBuffer * Consume(
  uint16_t aConsumeLength
)

Wykorzystuj dane w łańcuchu buforów.

Wykorzystuj dane w łańcuchu buforów, zaczynając od bieżącego bufora i przechodząc przez pozostałe bufory w łańcuchu. Każdy całkowicie wykorzystany bufor jest uwalniany, a funkcja zwraca pierwszy bufor (jeśli jest dostępny) zawierający pozostałe dane. Bieżący bufor musi być nagłówkiem łańcucha bufora.

Szczegóły
Parametry
[in] aConsumeLength
– liczba bajtów do wykorzystania w bieżącym łańcuchu.
Zwroty
pierwszy bufor bieżącego łańcucha, który zawiera pozostałe dane. Jeśli nie ma pozostałych danych, zwracana jest wartość NULL.

ConsumeHead

void ConsumeHead(
  uint16_t aConsumeLength
)

Dostosuj bieżący bufor, aby wskazać ilość wykorzystywanych danych.

Przesuń pozycję początkową danych w bieżącym buforze o określoną ilość (w bajtach) aż do długości danych w buforze. Zmniejsz długość i całkowitą długość o konsumpcję.

Szczegóły
Parametry
[in] aConsumeLen
– liczba bajtów do wykorzystania z bieżącego bufora.

DataLength

uint16_t DataLength(
  void
) const

Pobranie długości danych w buforze pakietów (w bajtach).

Szczegóły
Zwroty
długość w bajtach (bieżąca długość ładunku).

DetachTail

PacketBuffer * DetachTail(
  void
)

Odłącz bieżący bufor od łańcucha i zwróć wskaźnik do pozostałych buforów.

Bieżący bufor musi być nagłówkiem łańcucha.

Szczegóły
Zwroty
koniec bieżącego łańcucha bufora lub wartość NULL, jeśli bieżący bufor jest jedynym buforem w łańcuchu.

EnsureReservedSize

bool EnsureReservedSize(
  uint16_t aReservedSize
)

Sprawdź, czy bufor ma co najmniej określoną ilość zarezerwowanego miejsca.

Upewnij się, że w buforze znajduje się co najmniej określona ilość zarezerwowanego miejsca na dane, które jest przenoszone do przodu (w razie potrzeby).

Szczegóły
Parametry
[in] aReservedSize
– liczba bajtów dla nagłówków.
Zwroty
true, jeśli żądany zarezerwowany rozmiar jest dostępny, lub false, jeśli w buforie nie ma wystarczającej ilości miejsca.

MaxDataLength

uint16_t MaxDataLength(
  void
) const

Uzyskaj maksymalną ilość danych (w bajtach), która zmieści się w buforze przy bieżącej pozycji początkowej i rozmiarze bufora.

Szczegóły
Zwroty
liczba bajtów, które mieszczą się w buforze przy bieżącej pozycji początkowej.

Dalej

PacketBuffer * Next(
  void
) const

Wskaźnik do następnego bufora w łańcuchu.

Szczegóły
Zwroty
wskaźnik do następnego bufora w łańcuchu. Zwracana jest wartość NULL, gdy w łańcuchu nie ma buforów.

ReservedSize

uint16_t ReservedSize(
  void
) const

Pobierz liczbę bajtów w bieżącym buforze między początkiem bufora a bieżącą pozycją początkową danych.

Szczegóły
Zwroty
ilość (w bajtach) odstępu między początkiem bufora a bieżącą pozycją początkową danych.

SetDataLength

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

Ustaw długość danych w buforze (w bajtach) i odpowiednio dostosujesz jej łączną długość.

Ta funkcja ustawia długość danych w buforze (w bajtach), odpowiednio dostosowując całkowitą długość. Gdy bufor nie jest początkiem łańcucha bufora (typowy przypadek: element wywołujący dodaje dane do ostatniego bufora w łańcuchu PacketBuffer przed wywołaniem wyższych warstw), musi zostać przekazany element aChainHead, aby prawidłowo dostosować całkowitą długość każdego bufora przed bieżącym buforem.

Szczegóły
Parametry
[in] aNewLen
– nowa długość tego bufora (w bajtach).
[in,out] aChainHead
– nagłówek łańcucha bufora, do którego należy bieżący bufor. Może mieć wartość NULL, jeśli bieżący bufor jest nagłówkiem łańcucha buforów.

SetStart

void SetStart(
  uint8_t *aNewStart
)

Ustaw dane początkowe w buforze, odpowiednio dostosowując długość i całkowitą długość.

Szczegóły
Parametry
[in] aNewStart
– wskaźnik miejsca, w którym powinien rozpoczynać się nowy ładunek. Parametr newStart zostanie wewnętrznie dostosowany w taki sposób, aby mieścił się w granicach pierwszego bufora w łańcuchu PacketBuffer.

Początek

uint8_t * Start(
  void
) const

Pobierz wskaźnik początkowy danych w buforze.

Szczegóły
Zwroty
wskaźnik na początku danych.

TotalLength

uint16_t TotalLength(
  void
) const

Uzyskaj łączną długość danych pakietów w łańcuchu bufora.

Szczegóły
Zwroty
długość całkowita podana w oktetach.

Publiczne funkcje statyczne

bezpłatnie

void Free(
  PacketBuffer *aPacket
)

Zwolnij wszystkie bufory pakietów w łańcuchu.

Zmniejsz liczbę odwołań do wszystkich buforów w bieżącym łańcuchu. Jeśli liczba plików referencyjnych osiągnie wartość 0, odpowiednie bufory są odpowiednio zwalniane lub zwracane do pul alokacji. Użytkownicy powinni traktować tę metodę jako odpowiednik funkcji free() i nie używać argumentu po wywołaniu.

Szczegóły
Parametry
[in] aPacket
– bufor pakietów do zwolnienia.

FreeHead

PacketBuffer * FreeHead(
  PacketBuffer *aPacket
)

Zwolnij pierwszy bufor w łańcuchu, zwracając wskaźnik do pozostałych buforów.

* @note When the buffer chain is referenced by multiple callers,FreeHead()` odłączy głowę, ale nie spowoduje wymuszania cofania bufora nagłówka.

Szczegóły
Parametry
[in] aPacket
– łańcuch bufora.
Zwroty
łańcuch bufora pakietów składający się z ogona bufora wejściowego (może to być NULL).

Nowi

PacketBuffer * New(
  void
)

Przypisuje pojedynczy element PacketBuffer o domyślnym maksymalnym rozmiarze (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) z domyślnym zarezerwowanym rozmiarem (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) w ładunku.

Zarezerwowany rozmiar (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) jest wystarczająco duży, aby pomieścić nagłówki warstwy transportowej oraz nagłówki wymagane przez WeaveMessageLayer i WeaveExchangeLayer.

Nowi

PacketBuffer * New(
  uint16_t aReservedSize
)

Przypisuje pojedynczy element PacketBuffer o maksymalnym rozmiarze całkowitym z określonym rozmiarem rezerwy nagłówka.

Przekazywany parametr ma rozmiar zarezerwowany przed ładunkiem w celu dostosowania nagłówków pakietów z różnych warstw stosu, a nie ogólnego rozmiaru bufora do przydzielenia. Rozmiar bufora WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX, a nie, określony w wywołaniu.

  • PacketBuffer::New(0) : wywołanie tej metody powoduje, że bufor zostanie zwrócony bez zarezerwowanego nagłówka. W rezultacie element wywołujący może używać całego ładunku. Ten wzorzec jest szczególnie przydatny w niższych warstwach stosów sieciowych, gdy użytkownik wie, że ładunek zostanie skopiowany do ostatecznej wiadomości z odpowiednimi rezerwami nagłówka lub podczas tworzenia obiektu PacketBuffer, które są dołączane do łańcucha PacketBuffer przez PacketBuffer::AddToEnd(). Parametry
    [in] aReservedSize
    ilość miejsca na nagłówek do zarezerwowania.
    Zwroty
    W przypadku powodzenia wskaźnik do PacketBuffer w przypadku błędu NULL.

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

Przypisuje element PacketBuffer o domyślnym zarezerwowanym rozmiarze (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) w ładunku na potrzeby nagłówków i na potrzeby co najmniej aAllocSize B miejsca na dodatkowe dane po początkowym wskaźniku kursora.

Takie użycie jest najbardziej odpowiednie podczas przydzielania obiektu PacketBuffer na potrzeby wiadomości w warstwie aplikacji.

Szczegóły
Parametry
[in] aAvailableSize
Liczba oktetów, które mają zostać przydzielone za kursorem.
Zwroty
Jeśli operacja się uda, wskaźnik PacketBuffer w przydzielonym bloku. W przypadku niepowodzenia, NULL. *

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

Przypisuje obiekt PacketBuffer z co najmniej aReservedSize bajtami zarezerwowanych w ładunku na potrzeby nagłówków oraz co najmniej aAllocSize bajtami miejsca na dodatkowe dane po początkowym wskaźniku kursora.

Szczegóły
Parametry
[in] aReservedSize
Liczba oktetów do zarezerwowania za kursorem.
[in] aAvailableSize
Liczba oktetów, które mają zostać przydzielone za kursorem.
Zwroty
Jeśli operacja się uda, wskaźnik PacketBuffer w przydzielonym bloku. W przypadku niepowodzenia, NULL.

RightSize

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

W razie potrzeby skopiuj podany bufor do bufora o odpowiednim rozmiarze.

Ta funkcja nie jest przeznaczona do obsługi gniazd.

Szczegóły
Parametry
[in] aPacket
– łańcuch buforowania.
Zwroty
nowy bufor pakietów lub oryginalny bufor