nl::Weave::System::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

Class buffer paket adalah struktur inti yang digunakan untuk memanipulasi paket data yang diserialisasi octet, biasanya dalam konteks jaringan komunikasi data, seperti Bluetooth atau protokol Internet.

Ringkasan

Di lingkungan berbasis LwIP, class ini di-build di atas struktur pbuf yang ditentukan dalam library tersebut. Dengan tidak adanya LwIP, Weave menyediakan implementasi berbasis malloc, atau implementasi berbasis kumpulan yang mendekati tantangan memori dari perangkat yang tersemat dalam.

Class PacketBuffer, seperti banyak struktur serupa yang digunakan dalam stack jaringan berlapis, menyediakan mekanisme untuk mencadangkan ruang bagi header protokol di setiap lapisan stack komunikasi yang dapat dikonfigurasi. Untuk mengetahui detailnya, lihat PacketBuffer::New() serta dokumentasi LwIP.

Objek PacketBuffer dihitung berdasarkan referensi, dan mode penggunaan yang berlaku dalam Weave adalah "api-dan-lupakan". Karena paket (dan objek PacketBuffer yang mendasarinya) dikirim melalui berbagai lapisan protokol, upcall atau downcall yang berhasil antarlapisan menyiratkan transfer kepemilikan, dan tujuan panggilan bertanggung jawab untuk membebaskan buffer. Jika gagal melakukan panggilan lintas-lapisan, tanggung jawab untuk membebaskan buffer berada di tangan pemanggil.

Objek baru class PacketBuffer diinisialisasi di awal alokasi memori yang diperoleh dari lingkungan dasar, misalnya dari kumpulan target pbuf LwIP, dari heap library C standar, dari kumpulan buffer internal. Dalam kasus sederhana, ukuran buffer data adalah WEAVE_SYSTEM_PACKETBUFFER_SIZE. Komposer disediakan yang mengizinkan penggunaan buffering data dengan ukuran lain.

Objek PacketBuffer dapat dirantai untuk mengakomodasi payload yang lebih besar. Namun, perantaian tidak transparan, dan pengguna class harus secara eksplisit memutuskan untuk mendukung perantaian. Contoh class yang ditulis dengan dukungan perantaian adalah sebagai berikut:

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

Inheritance

Mewarisi dari: pbuf

Fungsi publik

AddRef(void)
void
Menambahkan jumlah referensi buffer saat ini.
AddToEnd(PacketBuffer *aPacket)
void
Menambahkan buffer paket yang diberikan ke akhir rantai buffer, menyesuaikan total panjang setiap buffer dalam rantai.
AlignPayload(uint16_t aAlignBytes)
bool
Menyelaraskan payload buffer pada batas byte yang ditentukan.
AllocSize(void) const
size_t
Menampilkan ukuran alokasi termasuk ruang data yang dicadangkan dan payload, tetapi tidak termasuk ruang yang dialokasikan untuk struktur PacketBuffer.
AvailableDataLength(void) const
uint16_t
Mendapatkan jumlah byte data yang dapat ditambahkan ke buffering saat ini berdasarkan posisi awal dan panjang data saat ini.
CompactHead(void)
void
Memindahkan data dari buffering berikutnya dalam rantai ke buffer saat ini hingga penuh.
Consume(uint16_t aConsumeLength)
Memakai data dalam rantai buffer.
ConsumeHead(uint16_t aConsumeLength)
void
Sesuaikan buffering saat ini untuk menunjukkan jumlah data yang dikonsumsi.
DataLength(void) const
uint16_t
Mendapatkan data panjang, dalam byte, dalam buffer paket.
DetachTail(void)
Melepaskan buffer saat ini dari rantai dan mengembalikan pointer ke buffer yang tersisa.
EnsureReservedSize(uint16_t aReservedSize)
bool
Pastikan buffer memiliki ruang cadangan minimal sesuai jumlah yang ditentukan.
MaxDataLength(void) const
uint16_t
Mendapatkan jumlah maksimum data dalam byte yang akan muat dalam buffer berdasarkan posisi awal dan ukuran buffer saat ini.
Next(void) const
Mendapatkan pointer ke buffering berikutnya dalam rantai.
ReservedSize(void) const
uint16_t
Mendapatkan jumlah byte dalam buffering saat ini antara awal buffer dan posisi awal data saat ini.
SetDataLength(uint16_t aNewLen, PacketBuffer *aChainHead)
void
Menyetel panjang data dalam byte, dalam buffer, dan menyesuaikan panjang total sebagaimana mestinya.
SetStart(uint8_t *aNewStart)
void
Setel data awal dalam buffer, sesuaikan panjang total dan panjang totalnya.
Start(void) const
uint8_t *
Mendapatkan pointer ke awal data dalam buffer.
TotalLength(void) const
uint16_t
Mendapatkan total panjang paket data dalam rantai buffer.

Fungsi statis publik

Free(PacketBuffer *aPacket)
void
Membebaskan semua buffer paket dalam sebuah rantai.
FreeHead(PacketBuffer *aPacket)
Mengosongkan buffer pertama dalam rantai, mengembalikan pointer ke buffer yang tersisa.
New(void)
Mengalokasikan satu PacketBuffer ukuran maksimum default (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) dengan ukuran default yang dicadangkan (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) dalam payload.
New(uint16_t aReservedSize)
Mengalokasikan satu PacketBuffer dari ukuran total maksimum dengan ukuran cadangan header tertentu.
NewWithAvailableSize(size_t aAvailableSize)
Mengalokasikan PacketBuffer dengan ukuran default yang dicadangkan (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) dalam payload untuk header, dan setidaknya aAllocSize byte ruang untuk data tambahan setelah pointer kursor awal.
NewWithAvailableSize(uint16_t aReservedSize, size_t aAvailableSize)
Mengalokasikan objek PacketBuffer dengan minimal aReservedSize byte yang dicadangkan dalam payload untuk header, dan minimal aAllocSize byte ruang untuk data tambahan setelah pointer kursor awal.
RightSize(PacketBuffer *aPacket)
Salin buffer yang diberikan ke buffer berukuran tepat, jika berlaku.

Fungsi publik

AddRef

void AddRef(
  void
)

Menambahkan jumlah referensi buffer saat ini.

AddToEnd

void AddToEnd(
  PacketBuffer *aPacket
)

Menambahkan buffer paket yang diberikan ke akhir rantai buffer, menyesuaikan total panjang setiap buffer dalam rantai.

Detail
Parameter
[in] aPacket
- buffer paket yang akan ditambahkan ke akhir rantai saat ini.

AlignPayload

bool AlignPayload(
  uint16_t aAlignBytes
)

Menyelaraskan payload buffer pada batas byte yang ditentukan.

Memindahkan payload di buffer jika perlu.

Detail
Parameter
[in] aAlignBytes
- menentukan jumlah penyelarasan byte untuk pointer awal payload.
Hasil
true jika perataan berhasil, false jika tidak ada cukup ruang di buffer.

AllocSize

size_t AllocSize(
  void
) const 

Menampilkan ukuran alokasi termasuk ruang data yang dicadangkan dan payload, tetapi tidak termasuk ruang yang dialokasikan untuk struktur PacketBuffer.

Detail
Hasil
ukuran alokasi.

AvailableDataLength

uint16_t AvailableDataLength(
  void
) const 

Mendapatkan jumlah byte data yang dapat ditambahkan ke buffering saat ini berdasarkan posisi awal dan panjang data saat ini.

Detail
Hasil
panjang, dalam byte, data yang akan sesuai dengan buffer saat ini berdasarkan posisi awal dan panjang data saat ini.

CompactHead

void CompactHead(
  void
)

Memindahkan data dari buffering berikutnya dalam rantai ke buffer saat ini hingga penuh.

Hanya buffer saat ini yang dipadatkan: data dalam buffer saat ini dipindahkan ke depan buffer, sehingga menghapus ruang yang dicadangkan. Sisa ruang yang tersedia akan diisi dengan data yang dipindahkan dari buffering berikutnya dalam rantai, hingga buffering saat ini penuh. Jika buffer berikutnya dalam rantai dipindahkan ke buffer saat ini secara keseluruhan, buffer tersebut akan dikeluarkan dari rantai dan dibebaskan. Metode ini tidak menggunakan parameter, tidak menampilkan hasil, dan tidak boleh gagal.

Konsumsi

PacketBuffer * Consume(
  uint16_t aConsumeLength
)

Memakai data dalam rantai buffer.

Memakai data dalam rantai buffer yang dimulai dengan buffer saat ini dan berlanjut ke buffer yang tersisa dalam rantai. Setiap buffer yang terpakai seluruhnya akan dibebaskan dan fungsi akan menampilkan buffer pertama (jika ada) yang berisi data yang tersisa. Buffer saat ini harus menjadi kepala rantai buffer.

Detail
Parameter
[in] aConsumeLength
- jumlah byte yang akan digunakan dari rantai saat ini.
Hasil
{i>buffer<i} pertama dari rantai saat ini yang berisi data yang tersisa. Jika tidak ada data yang tersisa, maka NULL akan dikembalikan.

ConsumeHead

void ConsumeHead(
  uint16_t aConsumeLength
)

Sesuaikan buffering saat ini untuk menunjukkan jumlah data yang dikonsumsi.

Maju posisi awal data dalam buffer saat ini sebesar jumlah yang ditentukan, dalam byte, hingga panjang data dalam buffer. Kurangi panjang dan panjang total dengan jumlah yang dikonsumsi.

Detail
Parameter
[in] aConsumeLen
- jumlah byte yang akan digunakan dari buffer saat ini.

DataLength

uint16_t DataLength(
  void
) const 

Mendapatkan data panjang, dalam byte, dalam buffer paket.

Detail
Hasil
panjang, dalam byte (panjang payload saat ini).

DetachTail

PacketBuffer * DetachTail(
  void
)

Melepaskan buffer saat ini dari rantai dan mengembalikan pointer ke buffer yang tersisa.

Buffer saat ini harus menjadi kepala rantai.

Detail
Hasil
ekor dari rantai buffer saat ini atau NULL jika buffer saat ini adalah satu-satunya buffer dalam rantai tersebut.

EnsureReservedSize

bool EnsureReservedSize(
  uint16_t aReservedSize
)

Pastikan buffer memiliki ruang cadangan minimal sesuai jumlah yang ditentukan.

Pastikan buffer memiliki ruang cadangan minimal sesuai jumlah yang ditentukan, yang memindahkan data dalam buffer ke depan untuk memberi ruang jika diperlukan.

Detail
Parameter
[in] aReservedSize
- jumlah byte yang diinginkan untuk header.
Hasil
true jika ukuran yang dicadangkan yang diminta tersedia, false jika tidak ada cukup ruang di buffer.

MaxDataLength

uint16_t MaxDataLength(
  void
) const 

Mendapatkan jumlah maksimum data dalam byte yang akan muat dalam buffer berdasarkan posisi awal dan ukuran buffer saat ini.

Detail
Hasil
jumlah byte yang sesuai dengan buffer berdasarkan posisi awal saat ini.

Berikutnya

PacketBuffer * Next(
  void
) const 

Mendapatkan pointer ke buffering berikutnya dalam rantai.

Detail
Hasil
pointer ke {i>buffer<i} berikutnya dalam rantai tersebut. NULL ditampilkan saat tidak ada buffer dalam rantai.

ReservedSize

uint16_t ReservedSize(
  void
) const 

Mendapatkan jumlah byte dalam buffering saat ini antara awal buffer dan posisi awal data saat ini.

Detail
Hasil
jumlah ruang antara awal buffer dan posisi awal data saat ini dalam byte.

SetDataLength

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

Menyetel panjang data dalam byte, dalam buffer, dan menyesuaikan panjang total sebagaimana mestinya.

Fungsi menyetel panjang data dalam {i>byte<i}, dan menyesuaikan panjang total dengan tepat. Jika buffer bukan merupakan kepala rantai buffer (kasus umum: pemanggil menambahkan data ke buffer terakhir dalam rantai PacketBuffer sebelum memanggil lapisan yang lebih tinggi), aChainHead harus diteruskan untuk menyesuaikan dengan benar panjang total setiap buffer sebelum buffer saat ini.

Detail
Parameter
[in] aNewLen
- panjang baru, dalam byte, buffer ini.
[in,out] aChainHead
- kepala rantai buffer tempat buffer saat ini berada. Mungkin NULL jika buffer saat ini adalah kepala rantai buffer.

SetStart

void SetStart(
  uint8_t *aNewStart
)

Setel data awal dalam buffer, sesuaikan panjang total dan panjang totalnya.

Detail
Parameter
[in] aNewStart
- Pointer ke tempat payload baru harus dimulai. newStart akan disesuaikan secara internal agar berada dalam batas buffer pertama di rantai PacketBuffer.

Mulai

uint8_t * Start(
  void
) const 

Mendapatkan pointer ke awal data dalam buffer.

Detail
Hasil
pointer ke awal data.

TotalLength

uint16_t TotalLength(
  void
) const 

Mendapatkan total panjang paket data dalam rantai buffer.

Detail
Hasil
panjang total, dalam oktet.

Fungsi statis publik

Gratis

void Free(
  PacketBuffer *aPacket
)

Membebaskan semua buffer paket dalam sebuah rantai.

Mengurangi jumlah referensi ke semua buffering dalam rantai saat ini. Jika jumlah referensi mencapai 0, masing-masing buffering akan dibebaskan atau dikembalikan ke kumpulan alokasi sesuai kebutuhan. Sebagai aturan, pengguna harus memperlakukan metode ini sebagai padanan fungsi free() dan tidak menggunakan argumen setelah panggilan.

Detail
Parameter
[in] aPacket
- buffer paket yang akan dibebaskan.

FreeHead

PacketBuffer * FreeHead(
  PacketBuffer *aPacket
)

Mengosongkan buffer pertama dalam rantai, mengembalikan pointer ke buffer yang tersisa.

* @note When the buffer chain is referenced by multiple callers,FreeHead()` akan melepaskan head, tetapi tidak akan secara paksa membatalkan alokasi buffer head.

Detail
Parameter
[in] aPacket
- rantai buffer.
Hasil
rantai buffering paket yang terdiri dari ekor buffer input (mungkin NULL).

Baru

PacketBuffer * New(
  void
)

Mengalokasikan satu PacketBuffer ukuran maksimum default (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) dengan ukuran default yang dicadangkan (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) dalam payload.

Ukuran yang dicadangkan (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) cukup besar untuk menampung header lapisan transpor serta header yang diperlukan oleh WeaveMessageLayer dan WeaveExchangeLayer.

Baru

PacketBuffer * New(
  uint16_t aReservedSize
)

Mengalokasikan satu PacketBuffer dari ukuran total maksimum dengan ukuran cadangan header tertentu.

Parameter yang diteruskan adalah ukuran yang dicadangkan sebelum payload untuk mengakomodasi header paket dari lapisan stack yang berbeda, bukan ukuran keseluruhan buffer yang akan dialokasikan. Ukuran buffer WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX dan tidak, yang ditentukan dalam panggilan.

  • PacketBuffer::New(0) : jika dipanggil dengan cara ini, buffer akan ditampilkan tanpa header yang dicadangkan, sehingga seluruh payload dapat digunakan oleh pemanggil. Pola ini sangat berguna pada lapisan bawah stack jaringan, jika pengguna mengetahui bahwa payload akan disalin ke pesan akhir dengan cadangan header yang sesuai atau saat membuat PacketBuffer yang ditambahkan ke rantai PacketBuffer melalui PacketBuffer::AddToEnd(). Parameter
    [in] aReservedSize
    jumlah ruang {i>header<i} yang harus direservasi.
    Hasil
    Jika berhasil, pointer ke PacketBuffer jika gagal NULL.

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

Mengalokasikan PacketBuffer dengan ukuran default yang dicadangkan (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) dalam payload untuk header, dan setidaknya aAllocSize byte ruang untuk data tambahan setelah pointer kursor awal.

Penggunaan ini paling tepat saat mengalokasikan PacketBuffer untuk pesan lapisan aplikasi.

Detail
Parameter
[in] aAvailableSize
Jumlah oktet yang akan dialokasikan setelah kursor.
Hasil
Jika berhasil, pointer ke PacketBuffer di blok yang dialokasikan. Jika gagal, NULL. *

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

Mengalokasikan objek PacketBuffer dengan minimal aReservedSize byte yang dicadangkan dalam payload untuk header, dan minimal aAllocSize byte ruang untuk data tambahan setelah pointer kursor awal.

Detail
Parameter
[in] aReservedSize
Jumlah oktet yang akan dicadangkan di belakang kursor.
[in] aAvailableSize
Jumlah oktet yang akan dialokasikan setelah kursor.
Hasil
Jika berhasil, pointer ke PacketBuffer di blok yang dialokasikan. Jika gagal, NULL.

RightSize

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

Salin buffer yang diberikan ke buffer berukuran tepat, jika berlaku.

Fungsi ini merupakan tanpa pengoperasian untuk soket.

Detail
Parameter
[in] aPacket
- rantai buffer atau buffer.
Hasil
{i>buffer<i} paket baru atau {i>buffer<i} asli