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 dibangun di atas struktur pbuf yang ditentukan dalam library tersebut. Dengan tidak adanya LwIP, Weave menyediakan implementasi berbasis malloc, atau implementasi berbasis kumpulan yang sangat memperkirakan tantangan memori untuk perangkat yang tersemat dalam jumlah mendalam.

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 dengan 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 antar-lapisan menyiratkan transfer kepemilikan, dan tujuan panggilan bertanggung jawab untuk membebaskan buffer. Jika panggilan lintas-lapisan gagal, tanggung jawab untuk membebaskan buffer berada di tangan pemanggil.

Objek baru dari class PacketBuffer diinisialisasi pada awal alokasi memori yang diperoleh dari lingkungan dasarnya, misalnya dari kumpulan target LwIP pbuf, dari heap library C standar, dari kumpulan buffer internal. Dalam kasus sederhana, ukuran buffer data adalah WEAVE_SYSTEM_PACKETBUFFER_SIZE. Tersedia komposer yang mengizinkan penggunaan {i>buffer <i}data dengan ukuran lain.

Objek PacketBuffer dapat dirantai untuk mengakomodasi payload yang lebih besar. Namun, pembuatan rantai 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
Menambah jumlah referensi buffer saat ini.
AddToEnd(PacketBuffer *aPacket)
void
Tambahkan buffer paket yang diberikan ke akhir rantai buffer, dengan menyesuaikan panjang total 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 payload dan ruang data 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 berdasarkan posisi awal dan panjang data saat ini.
CompactHead(void)
void
Pindahkan data dari buffer berikutnya dalam rantai ke dalam buffer saat ini hingga buffer tersebut penuh.
Consume(uint16_t aConsumeLength)
Menggunakan data dalam rantai buffer.
ConsumeHead(uint16_t aConsumeLength)
void
Sesuaikan buffer saat ini untuk menunjukkan jumlah data yang dikonsumsi.
DataLength(void) const
uint16_t
Mendapatkan panjang data, dalam byte, di buffer paket.
DetachTail(void)
Lepaskan buffer saat ini dari rantainya dan kembalikan pointer ke buffer yang tersisa.
EnsureReservedSize(uint16_t aReservedSize)
bool
Pastikan buffer memiliki setidaknya jumlah ruang cadangan yang ditentukan.
MaxDataLength(void) const
uint16_t
Dapatkan jumlah maksimum, dalam byte, data yang akan muat dalam buffer dengan mempertimbangkan 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
Setel panjang data dalam byte, dalam byte, sehingga menyesuaikan panjang total.
SetStart(uint8_t *aNewStart)
void
Tetapkan data awal dalam buffer, sesuaikan panjang dan total panjangnya.
Start(void) const
uint8_t *
Mendapatkan pointer untuk memulai data dalam buffer.
TotalLength(void) const
uint16_t
Mendapatkan total panjang data paket dalam rantai buffer.

Fungsi statis publik
Free(PacketBuffer *aPacket)
void
Membebaskan semua buffer paket dalam satu rantai.
FreeHead(PacketBuffer *aPacket)
Membebaskan buffer pertama dalam sebuah rantai, yang menampilkan pointer ke buffer yang tersisa.
New(void)
Mengalokasikan satu PacketBuffer dari ukuran maksimum default (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) dengan ukuran yang dicadangkan default (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 minimal 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
)

Menambah jumlah referensi buffer saat ini.

AddToEnd

void AddToEnd(
  PacketBuffer *aPacket
)

Tambahkan buffer paket yang diberikan ke akhir rantai buffer, dengan menyesuaikan panjang total 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 dalam buffer jika perlu.

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

AllocSize

size_t AllocSize(
  void
) const

Menampilkan ukuran alokasi, termasuk ruang data payload dan ruang data 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 buffer saat ini berdasarkan posisi awal dan panjang data saat ini.

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

CompactHead

void CompactHead(
  void
)

Pindahkan data dari buffer berikutnya dalam rantai ke dalam buffer saat ini hingga buffer tersebut penuh.

Hanya buffer saat ini yang dipadatkan: data dalam buffer saat ini akan dipindahkan ke bagian depan buffer, sehingga menghilangkan semua ruang yang dicadangkan. Sisa ruang yang tersedia diisi dengan data yang dipindahkan dari buffer berikutnya dalam rantai, sampai buffer saat ini penuh. Jika buffer berikutnya dalam rantai dipindahkan ke buffer saat ini secara keseluruhan, buffer tersebut akan dihapus dari rantai dan dibebaskan. Metode ini tidak menggunakan parameter, tidak menampilkan hasil, dan tidak bisa gagal.

Pemakaian

PacketBuffer * Consume(
  uint16_t aConsumeLength
)

Menggunakan data dalam rantai buffer.

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

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

ConsumeHead

void ConsumeHead(
  uint16_t aConsumeLength
)

Sesuaikan buffer saat ini untuk menunjukkan jumlah data yang dikonsumsi.

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

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

DataLength

uint16_t DataLength(
  void
) const

Mendapatkan panjang data, dalam byte, di buffer paket.

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

DetachTail

PacketBuffer * DetachTail(
  void
)

Lepaskan buffer saat ini dari rantainya dan kembalikan pointer ke buffer yang tersisa.

Buffer saat ini harus berupa head rantai.

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

EnsureReservedSize

bool EnsureReservedSize(
  uint16_t aReservedSize
)

Pastikan buffer memiliki setidaknya jumlah ruang cadangan yang ditentukan.

Pastikan buffer memiliki setidaknya jumlah ruang cadangan yang ditentukan untuk memindahkan data dalam buffer ke depan untuk memberikan 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

Dapatkan jumlah maksimum, dalam byte, data yang akan muat dalam buffer dengan mempertimbangkan posisi awal dan ukuran buffer saat ini.

Detail
Hasil
jumlah byte yang sesuai dengan {i>buffer<i} berdasarkan posisi awal saat ini.

Berikutnya

PacketBuffer * Next(
  void
) const

Mendapatkan pointer ke buffer berikutnya dalam rantai.

Detail
Hasil
sebuah 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 buffer 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 satuan byte.

SetDataLength

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

Setel panjang data dalam byte, dalam byte, sehingga menyesuaikan panjang total.

Fungsi ini menyetel panjang data dalam buffer, dalam byte, dan menyesuaikan panjang total dengan tepat. Jika buffer bukan merupakan head 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, dari buffer ini.
[in,out] aChainHead
- kepala rantai buffer yang mencakup buffer saat ini. Mungkin NULL jika buffer saat ini adalah head dari rantai buffer.

SetStart

void SetStart(
  uint8_t *aNewStart
)

Tetapkan data awal dalam buffer, sesuaikan panjang dan total panjangnya.

Detail
Parameter
[in] aNewStart
- Pointer 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 untuk memulai data dalam buffer.

Detail
Hasil
menunjukkan awal data.

TotalLength

uint16_t TotalLength(
  void
) const

Mendapatkan total panjang data paket dalam rantai buffer.

Detail
Hasil
panjang total, dalam oktet.

Fungsi statis publik

Gratis

void Free(
  PacketBuffer *aPacket
)

Membebaskan semua buffer paket dalam satu rantai.

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

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

FreeHead

PacketBuffer * FreeHead(
  PacketBuffer *aPacket
)

Membebaskan buffer pertama dalam sebuah rantai, yang menampilkan pointer ke buffer yang tersisa.

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

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

Baru

PacketBuffer * New(
  void
)

Mengalokasikan satu PacketBuffer dari ukuran maksimum default (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) dengan ukuran yang dicadangkan default (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 stack jaringan yang lebih rendah, jika pengguna mengetahui bahwa payload akan disalin ke dalam pesan akhir dengan cadangan header yang sesuai atau dalam membuat PacketBuffer yang ditambahkan ke rantai PacketBuffer melalui PacketBuffer::AddToEnd(). Parameter
    [in] aReservedSize
    jumlah ruang {i>header<i} yang akan dicadangkan.
    Pengembalian
    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 minimal 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 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 tidak menjalankan soket.

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