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 |
|
AlignPayload
bool AlignPayload( uint16_t aAlignBytes )
Menyelaraskan payload buffer pada batas byte yang ditentukan.
Memindahkan payload di buffer jika perlu.
Detail | |||
---|---|---|---|
Parameter |
|
||
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 |
|
||
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 |
|
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 |
|
||
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 |
|
SetStart
void SetStart( uint8_t *aNewStart )
Setel data awal dalam buffer, sesuaikan panjang total dan panjang totalnya.
Detail | |||
---|---|---|---|
Parameter |
|
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 |
|
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 |
|
||
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 melaluiPacketBuffer::AddToEnd()
. Parameter[in] aReservedSize
jumlah ruang {i>header<i} yang harus direservasi.Jika berhasil, pointer ke PacketBuffer jika gagalNULL
.
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 |
|
||
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 |
|
||||
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 |
|
||
Hasil |
{i>buffer<i} paket baru atau {i>buffer<i} asli
|