nl::Weave::System::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

Klasa bufora pakietów to podstawowa struktura używana do manipulowania pakietami danych w postaci oktetów, zwykle w kontekście sieci komunikacji danych, takiej jak Bluetooth czy 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 zapewnia implementację opartą na Malloc lub na pulę, która w dużym stopniu przybliża problemy związane z pamięcią umieszczane na urządzeniach umieszczonych w głębokich witrynach.

Klasa PacketBuffer, podobnie jak wiele podobnych struktur używanych w warstwowych stosach sieciowych, zapewnia mechanizm rezerwowania przestrzeni dla nagłówków protokołów w każdej warstwie konfigurowalnego stosu komunikacyjnego. Szczegółowe informacje znajdziesz na stronie PacketBuffer::New() oraz w dokumentacji LwIP.

Obiekty PacketBuffer są liczone jako odwołania, a tryb użytkowania Weave to „fire-and-get”. Ponieważ pakiet (i jego bazowy obiekt PacketBuffer) jest wysyłany przez różne warstwy protokołu, udane wywołanie funkcji „wywołanie” lub „pobieranie” między warstwami oznacza przeniesienie własności, a odbiorca odpowiada za zwolnienie bufora. W przypadku niepowodzenia połączenia międzywarstwowym odpowiedzialność za zwolnienie bufora spoczywa na użytkowniku wywołującym.

Nowe obiekty klasy PacketBuffer są inicjowane na początku alokacji pamięci uzyskanej ze środowiska bazowego, np. z pul docelowych LwIP ze standardowej biblioteki C, z wewnętrznej puli buforów. W prostym przypadku rozmiar bufora danych to WEAVE_SYSTEM_PACKETBUFFER_SIZE. Udostępniono narzędzie kompozycyjne, które pozwala na używanie buforów danych o innych rozmiarach.

Obiekty PacketBuffer można połączyć w łańcuch, aby obsługiwać większe ładunki. Łańcuchy nie są jednak przejrzyste, a użytkownicy klasy muszą wyraźnie zdecydować, czy będą obsługiwać łańcuchy. Przykłady klas napisanych z obsługą łańcuchów: 

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

Dziedziczenie

Dziedziczy z: pbuf

Funkcje publiczne
AddRef(void)
void
Zwiększ liczbę odwołań w bieżącym buforze.
AddToEnd(PacketBuffer *aPacket)
void
Dodaj dany bufor pakietów na końcu łańcucha buforów, odpowiednio dostosowując całkowitą długość każdego bufora w łańcuchu.
AlignPayload(uint16_t aAlignBytes)
bool
Wyrównaj ładunek bufora do określonej granicy bajtów.
AllocSize(void) const
size_t
Zwraca rozmiar alokacji, w tym zarezerwowane przestrzenie danych i ładunek, ale nie uwzględnia miejsca przydzielonego dla struktury PacketBuffer.
AvailableDataLength(void) const
uint16_t
Uzyskaj liczbę bajtów danych, które można dodać do bieżącego bufora przy danej 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ż się zapełni.
Consume(uint16_t aConsumeLength)
Przetwarzanie danych w łańcuchu buforów.
ConsumeHead(uint16_t aConsumeLength)
void
Dostosuj bieżący bufor, aby wskazać ilość wykorzystanych danych.
DataLength(void) const
uint16_t
Uzyskaj długość danych w buforze pakietów (w bajtach).
DetachTail(void)
Odłącz bieżący bufor od jego łańcucha i zwróć wskaźnik do pozostałych.
EnsureReservedSize(uint16_t aReservedSize)
bool
Upewnij się, że bufor zawiera co najmniej określoną ilość zarezerwowanego miejsca.
MaxDataLength(void) const
uint16_t
Uzyskaj maksymalną ilość danych (w bajtach), które mieszczą się w buforze przy danej pozycji początkowej i rozmiarze bufora.
Next(void) const
Pobierz wskaźnik do następnego bufora w łańcuchu.
ReservedSize(void) const
uint16_t
Uzyskaj liczbę bajtów w bieżącym buforze między jego początkiem a bieżącą pozycją danych.
SetDataLength(uint16_t aNewLen, PacketBuffer *aChainHead)
void
Ustaw długość danych w buforze (w bajtach) i odpowiednio dostosuj jej łączną długość.
SetStart(uint8_t *aNewStart)
void
Umieść dane początkowe w buforze, odpowiednio dostosowując długość i całkowitą długość.
Start(void) const
uint8_t *
Pobierz wskaźnik do początku danych w buforze.
TotalLength(void) const
uint16_t
Uzyskaj całkowitą długość pakietu danych w łańcuchu bufora.

Publiczne funkcje statyczne
Free(PacketBuffer *aPacket)
void
Uwolnij wszystkie bufory pakietów w łańcuchu.
FreeHead(PacketBuffer *aPacket)
Zwolnij pierwszy bufor w łańcuchu, zwracając wskaźnik do pozostałych.
New(void)
Przydziela 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)
Przydziela pojedynczy element PacketBuffer o maksymalnym łącznym rozmiarze z określonym rozmiarem rezerwacji nagłówka.
NewWithAvailableSize(size_t aAvailableSize)
Przydziela obiekt PacketBuffer z domyślnym zarezerwowanym rozmiarem (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) w ładunku na nagłówki i co najmniej aAllocSize bajtów miejsca na dodatkowe dane po początkowym wskaźniku kursora.
NewWithAvailableSize(uint16_t aReservedSize, size_t aAvailableSize)
Przydziela obiekt PacketBuffer, którego ładunek zawiera co najmniej aReservedSize B w ładunku dla nagłówków i co najmniej aAllocSize B miejsca na dodatkowe dane po początkowym wskaźniku kursora.
RightSize(PacketBuffer *aPacket)
Skopiuj podany bufor do bufora o odpowiednim rozmiarze, jeśli jest to konieczne.

Funkcje publiczne

AddRef

void AddRef(
  void
)

Zwiększ liczbę odwołań w bieżącym buforze.

AddToEnd

void AddToEnd(
  PacketBuffer *aPacket
)

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

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

AlignPayload

bool AlignPayload(
  uint16_t aAlignBytes
)

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

W razie potrzeby przenieść ładunek w buforze do przodu.

Szczegóły
Parametry
[in] aAlignBytes
– określa liczbę wyrównanych bajtów we wskaźniku początkowym ładunku.
Zwroty
true, jeśli udało się wyrównać, false, jeśli w buforze jest za mało miejsca.

AllocSize

size_t AllocSize(
  void
) const

Zwraca rozmiar alokacji, w tym zarezerwowane przestrzenie danych i ładunek, ale nie uwzględnia miejsca przydzielonego dla struktury PacketBuffer.

Szczegóły
Zwroty
wielkość alokacji

AvailableDataLength

uint16_t AvailableDataLength(
  void
) const

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

Szczegóły
Zwroty
długość (w bajtach) danych, które zmieszczą się w bieżącym buforze przy danej 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ż się zapełni.

Kompaktowanie obejmuje tylko bieżący bufor: dane w bieżącym buforze są przenoszone na początek, eliminując zarezerwowane miejsce. Pozostałe dostępne miejsce jest wypełniane danymi przeniesionymi z kolejnych buforów w łańcuchu aż do zapełnienia bieżącego bufora. Jeśli kolejny bufor w łańcuchu zostanie w całości przeniesiony do bieżącego bufora, zostanie usunięty z łańcucha i uwolniony. Ta 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
)

Przetwarzanie danych w łańcuchu buforów.

Przetwarzanie danych 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 zajęty bufor jest zwalniany, a funkcja zwraca pierwszy bufor (jeśli istnieje) zawierający pozostałe dane. Bieżący bufor musi być na początku łańcucha buforów.

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

ConsumeHead

void ConsumeHead(
  uint16_t aConsumeLength
)

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

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

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

DataLength

uint16_t DataLength(
  void
) const

Uzyskaj długość 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 jego łańcucha i zwróć wskaźnik do pozostałych.

Bieżący bufor musi być na początku łańcucha.

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

EnsureReservedSize

bool EnsureReservedSize(
  uint16_t aReservedSize
)

Upewnij się, że bufor zawiera co najmniej określoną ilość zarezerwowanego miejsca.

Upewnij się, że bufor ma co najmniej określoną ilość zarezerwowanej przestrzeni, która służy do przenoszenia danych w buforze do przodu, aby w razie potrzeby zrobić miejsce.

Szczegóły
Parametry
[in] aReservedSize
– liczba bajtów wymagana dla nagłówków.
Zwroty
true, jeśli żądany zarezerwowany rozmiar jest dostępny, false, jeśli w buforze jest za mało miejsca.

MaxDataLength

uint16_t MaxDataLength(
  void
) const

Uzyskaj maksymalną ilość danych (w bajtach), które mieszczą się w buforze przy danej pozycji początkowej i rozmiarze bufora.

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

Dalej

PacketBuffer * Next(
  void
) const

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

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

ReservedSize

uint16_t ReservedSize(
  void
) const

Uzyskaj liczbę bajtów w bieżącym buforze między jego początkiem a bieżącą pozycją danych.

Szczegóły
Zwroty
ilość (w bajtach) miejsca 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 dostosuj jej łączną długość.

Funkcja ta określa długość danych w buforze (w bajtach) i odpowiednio dostosowuje łączną długość. Gdy bufor nie jest na początku łańcucha bufora (typowy przypadek: element wywołujący dodaje dane do ostatniego bufora w PacketBuffer łańcuchu przed wywołaniem wyższych warstw), należywłaściwie dostosować całkowitą długość każdego bieżącego bufora za pomocą obiektu aChainHead.

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

SetStart

void SetStart(
  uint8_t *aNewStart
)

Umieść 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 rozpocząć się nowy ładunek. Wartość newStart zostanie dostosowana wewnętrznie tak, aby mieściła się w granicach pierwszego bufora w łańcuchu PacketBuffer.

Rozpocznij

uint8_t * Start(
  void
) const

Pobierz wskaźnik do początku danych w buforze.

Szczegóły
Zwroty
na początek danych.

TotalLength

uint16_t TotalLength(
  void
) const

Uzyskaj całkowitą długość pakietu danych w łańcuchu bufora.

Szczegóły
Zwroty
całkowitej długości w oktetach.

Publiczne funkcje statyczne

Bezpłatnie

void Free(
  PacketBuffer *aPacket
)

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

Zmniejsz liczbę odwołań do wszystkich buforów w bieżącym łańcuchu. Jeśli liczba referencyjna osiągnie 0, odpowiednie bufory zostaną zwolnione lub zwrócone do pul alokacji. Użytkownicy powinni traktować tę metodę jako odpowiednik funkcji free() i nie używać tego 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.

* @note When the buffer chain is referenced by multiple callers,Funkcja FreeHead()” odłącza nagłówek, ale nie wymusza jego ulokowania.

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

Nowość

PacketBuffer * New(
  void
)

Przydziela 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 transportu oraz nagłówki wymagane przez zasady WeaveMessageLayer i WeaveExchangeLayer.

Nowość

PacketBuffer * New(
  uint16_t aReservedSize
)

Przydziela pojedynczy element PacketBuffer o maksymalnym łącznym rozmiarze z określonym rozmiarem rezerwacji nagłówka.

Przekazany parametr to rozmiar zarezerwowany przed ładunkiem na potrzeby nagłówków pakietów z różnych warstw stosu, a nie ogólny rozmiar przydzielonego bufora. Rozmiar bufora WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX i nieokreślony w wywołaniu.

  • PacketBuffer::New(0) : po wywołaniu w ten sposób bufor jest zwracany bez zarezerwowanego nagłówka, co oznacza, że wywołujący może korzystać z całego ładunku. Ten wzorzec jest szczególnie przydatny na niższych warstwach stosu sieciowych, gdy użytkownik wie, że ładunek zostanie skopiowany do końcowej wiadomości z odpowiednimi rezerwami nagłówka lub podczas tworzenia elementu PacketBuffer, które są dołączone 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
)

Przydziela obiekt PacketBuffer z domyślnym zarezerwowanym rozmiarem (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) w ładunku na nagłówki i co najmniej aAllocSize bajtów miejsca na dodatkowe dane po początkowym wskaźniku kursora.

To użycie jest najbardziej odpowiednie, gdy przydzielasz obiekt PacketBuffer na potrzeby wiadomości w warstwie aplikacji.

Szczegóły
Parametry
[in] aAvailableSize
Liczba oktetów do przydzielenia za kursorem.
Zwroty
Jeśli operacja się uda, wskaźnik do PacketBuffer w przydzielonym bloku. W przypadku niepowodzenia: NULL. *

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

Przydziela obiekt PacketBuffer, w którym w ładunku jest co najmniej aReservedSize bajtów zarezerwowanych na nagłówki i co najmniej aAllocSize B 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 do przydzielenia za kursorem.
Zwroty
Jeśli operacja się uda, wskaźnik do PacketBuffer w przydzielonym bloku. W przypadku niepowodzenia: NULL.

RightSize

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

Skopiuj podany bufor do bufora o odpowiednim rozmiarze, jeśli jest to konieczne.

Ta funkcja nie jest obsługiwana w przypadku gniazd.

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