nl::Menenun::Sistem::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

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

Ringkasan

Di lingkungan berbasis LwIP, class ini dibuat berdasarkan struktur pbuf yang ditentukan dalam library tersebut. Dengan tidak adanya LwIP, Weave menyediakan implementasi berbasis malloc, atau implementasi berbasis kumpulan yang mendekati perkiraan tantangan memori dari perangkat yang disematkan secara mendalam.

Class PacketBuffer, seperti banyak struktur serupa yang digunakan dalam stack jaringan berlapis, menyediakan mekanisme untuk menyediakan 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 "fire-and-forget". Karena paket (dan objek PacketBuffer yang mendasarinya) dikirim melalui berbagai lapisan protokol, upcall atau downcall yang berhasil di antara lapisan menyiratkan transfer kepemilikan, dan tujuan panggilan bertanggung jawab untuk mengosongkan buffer. Jika panggilan lintas lapisan tidak berhasil, tanggung jawab untuk melepaskan buffer ada di tangan pemanggil.

Objek baru class PacketBuffer diinisialisasi di awal alokasi memori yang diperoleh dari lingkungan pokok, 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 buffer 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

Warisan

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 panjang total setiap buffer dalam rantai sebagaimana mestinya.
AlignPayload(uint16_t aAlignBytes)
bool
Menyelaraskan payload buffer pada batas byte yang ditentukan.
AllocSize(void) const
size_t
Menampilkan ukuran alokasi termasuk ruang data payload dan payload, tetapi tidak termasuk ruang yang dialokasikan untuk struktur PacketBuffer.
AvailableDataLength(void) const
uint16_t
Mendapatkan jumlah byte data yang dapat ditambahkan ke buffer saat ini mengingat posisi awal dan panjang data saat ini.
CompactHead(void)
void
Memindahkan data dari buffer berikutnya dalam rantai ke buffer saat ini hingga penuh.
Consume(uint16_t aConsumeLength)
Memakai data dalam rantai buffer.
ConsumeHead(uint16_t aConsumeLength)
void
Sesuaikan buffer saat ini untuk menunjukkan jumlah data yang digunakan.
DataLength(void) const
uint16_t
Mendapatkan panjang data dalam buffering paket dalam byte.
DetachTail(void)
Melepaskan buffer saat ini dari rantainya dan menampilkan pointer ke buffer yang tersisa.
EnsureReservedSize(uint16_t aReservedSize)
bool
Memastikan buffer setidaknya memiliki jumlah ruang yang direservasi yang ditentukan.
MaxDataLength(void) const
uint16_t
Mendapatkan jumlah maksimum, dalam byte, data yang akan pas dalam buffer mengingat posisi awal dan ukuran buffer saat ini.
Next(void) const
Mendapatkan pointer ke buffer berikutnya dalam rantai.
ReservedSize(void) const
uint16_t
Mendapatkan jumlah byte dalam buffer saat ini antara awal buffer dan posisi awal data saat ini.
SetDataLength(uint16_t aNewLen, PacketBuffer *aChainHead)
void
Menyetel panjang data dalam buffer dalam byte, yang menyesuaikan panjang total.
SetStart(uint8_t *aNewStart)
void
Setel data awal dalam buffer, yang menyesuaikan panjang dan total panjang sebagaimana mestinya.
Start(void) const
uint8_t *
Mendapatkan pointer ke awal data dalam buffer.
TotalLength(void) const
uint16_t
Mendapatkan total panjang data paket dalam rantai buffer.

Fungsi statis publik

Free(PacketBuffer *aPacket)
void
Kosongkan semua buffer paket dalam satu rantai.
FreeHead(PacketBuffer *aPacket)
Melepas buffer pertama dalam rantai, menampilkan pointer ke buffer yang tersisa.
New(void)
Alokasikan satu PacketBuffer dengan ukuran maksimum default (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) dengan ukuran yang dicadangkan secara default (WEAVE_SYSTEM_CONFIG_POINT_RESERVE_SIZE) dalam payload.
New(uint16_t aReservedSize)
Alokasikan satu PacketBuffer dari ukuran total maksimum dengan ukuran cadangan header tertentu.
NewWithAvailableSize(size_t aAvailableSize)
Alokasikan 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)
Alokasikan 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)
Menyalin buffer yang diberikan ke buffer berukuran kanan jika berlaku.

Fungsi publik

Referensi

void AddRef(
  void
)

Menambahkan jumlah referensi buffer saat ini.

TambahkanToEnd

void AddToEnd(
  PacketBuffer *aPacket
)

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

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

MenyelaraskanPayload

bool AlignPayload(
  uint16_t aAlignBytes
)

Menyelaraskan payload buffer pada batas byte yang ditentukan.

Memindahkan payload dalam buffer ke depan jika perlu.

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

Ukuran Alloc

size_t AllocSize(
  void
) const 

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

Detail
Menampilkan
ukuran alokasi

PanjangData yang Tersedia

uint16_t AvailableDataLength(
  void
) const 

Mendapatkan jumlah byte data yang dapat ditambahkan ke buffer saat ini mengingat posisi awal dan panjang data saat ini.

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

Kepala Compact

void CompactHead(
  void
)

Memindahkan data dari buffer 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 menghilangkan ruang yang dicadangkan. Sisa ruang yang tersedia diisi dengan data yang dipindahkan dari buffering berikutnya dalam rantai, hingga buffer saat ini penuh. Jika buffer berikutnya dalam rantai dipindahkan ke buffer saat ini secara keseluruhan, buffer akan dihapus dari rantai dan dibebaskan. Metode ini tidak menggunakan parameter, tidak menampilkan hasil, dan tidak dapat gagal.

Konsumsi

PacketBuffer * Consume(
  uint16_t aConsumeLength
)

Memakai data dalam rantai buffer.

Gunakan data dalam rantai buffer yang dimulai dengan buffer saat ini dan berlanjut melalui buffer yang tersisa dalam rantai. Setiap buffer yang sepenuhnya digunakan akan dibebaskan dan fungsi tersebut menampilkan buffer pertama (jika ada) yang berisi data yang tersisa. Buffer saat ini harus berupa kepala rantai buffer.

Detail
Parameter
[in] aConsumeLength
- jumlah byte yang akan dipakai dari rantai saat ini.
Menampilkan
buffering pertama dari rantai saat ini yang berisi data yang tersisa. Jika tidak ada data yang tersisa, NULL akan ditampilkan.

Konsumsi

void ConsumeHead(
  uint16_t aConsumeLength
)

Sesuaikan buffer saat ini untuk menunjukkan jumlah data yang digunakan.

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

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

PanjangData

uint16_t DataLength(
  void
) const 

Mendapatkan panjang data dalam buffering paket dalam byte.

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

Lepaskan Ujung

PacketBuffer * DetachTail(
  void
)

Melepaskan buffer saat ini dari rantainya dan menampilkan pointer ke buffer yang tersisa.

Buffer saat ini harus berupa kepala rantai.

Detail
Menampilkan
ujung rantai buffer saat ini atau NULL jika buffer saat ini adalah satu-satunya buffer dalam rantai.

PastikanUkuranDipesan

bool EnsureReservedSize(
  uint16_t aReservedSize
)

Memastikan buffer setidaknya memiliki jumlah ruang yang direservasi yang ditentukan.

Memastikan buffer memiliki setidaknya jumlah ruang yang telah ditentukan yang memindahkan data dalam buffer ke depan untuk memberikan ruang jika diperlukan.

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

PanjangData Maksimal

uint16_t MaxDataLength(
  void
) const 

Mendapatkan jumlah maksimum, dalam byte, data yang akan pas dalam buffer mengingat posisi awal dan ukuran buffer saat ini.

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

Berikutnya

PacketBuffer * Next(
  void
) const 

Mendapatkan pointer ke buffer berikutnya dalam rantai.

Detail
Menampilkan
pointer ke buffer berikutnya dalam rantai. NULL ditampilkan saat tidak ada buffer dalam rantai.

Ukuran yang Direservasi

uint16_t ReservedSize(
  void
) const 

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

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

SetDataLength

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

Menyetel panjang data dalam buffer dalam byte, yang menyesuaikan panjang total.

Fungsi ini menetapkan panjang, dalam byte, data dalam buffer, untuk menyesuaikan panjang total dengan tepat. Jika buffer bukanlah 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 panjang total setiap buffer dengan tepat sebelum buffer saat ini.

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

SetMulai

void SetStart(
  uint8_t *aNewStart
)

Setel data awal dalam buffer, yang menyesuaikan panjang dan total panjang sebagaimana mestinya.

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

Mulai

uint8_t * Start(
  void
) const 

Mendapatkan pointer ke awal data dalam buffer.

Detail
Menampilkan
pointer ke awal data.

PanjangTotal

uint16_t TotalLength(
  void
) const 

Mendapatkan total panjang data paket dalam rantai buffer.

Detail
Menampilkan
panjang total, dalam oktet.

Fungsi statis publik

Gratis

void Free(
  PacketBuffer *aPacket
)

Kosongkan semua buffer paket dalam satu rantai.

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

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

FreeHead

PacketBuffer * FreeHead(
  PacketBuffer *aPacket
)

Melepas buffer pertama dalam rantai, menampilkan pointer ke buffer yang tersisa.

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

Detail
Parameter
[in] aPacket
- rantai buffer.
Menampilkan
rantai buffer paket yang terdiri dari ujung buffer input (mungkin NULL).

Baru

PacketBuffer * New(
  void
)

Alokasikan satu PacketBuffer dengan ukuran maksimum default (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) dengan ukuran yang dicadangkan secara default (WEAVE_SYSTEM_CONFIG_POINT_RESERVE_SIZE) dalam payload.

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

Baru

PacketBuffer * New(
  uint16_t aReservedSize
)

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

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

  • PacketBuffer::New(0) : bila 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 membuat PacketBuffer yang ditambahkan ke rantai PacketBuffer melalui PacketBuffer::AddToEnd(). Parameter
    [in] aReservedSize
    jumlah ruang header yang akan dipesan.
    Menampilkan
    Jika berhasil, pointer ke PacketBuffer, pada kegagalan NULL.

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

Alokasikan 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 sesuai saat mengalokasikan PacketBuffer untuk pesan lapisan aplikasi.

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

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

Alokasikan 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.
Menampilkan
Jika berhasil, pointer ke PacketBuffer dalam blok yang dialokasikan. Jika gagal, NULL.

Ukuran Kanan

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

Menyalin buffer yang diberikan ke buffer berukuran kanan jika berlaku.

Fungsi ini adalah tanpa pengoperasian untuk soket.

Detail
Parameter
[in] aPacket
- buffering atau rantai buffer.
Menampilkan
buffer paket baru atau buffer asli