nl::Weave::System::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

Lớp vùng đệm gói là cấu trúc cốt lõi dùng để thao tác với các gói dữ liệu chuyển đổi tuần tự octet, thường trong ngữ cảnh mạng truyền thông dữ liệu, chẳng hạn như Bluetooth hoặc giao thức Internet.

Tóm tắt

Trong các môi trường dựa trên LwIP, lớp này được xây dựng dựa trên cấu trúc pbuf được xác định trong thư viện đó. Khi không có LwIP, Weave cung cấp phương thức triển khai dựa trên Malloc hoặc phương thức triển khai dựa trên nhóm, gần đúng với những thách thức về bộ nhớ của các thiết bị được nhúng sâu.

Lớp PacketBuffer giống như nhiều cấu trúc tương tự dùng trong ngăn xếp mạng phân lớp, cung cấp cơ chế dành riêng không gian cho tiêu đề giao thức ở mỗi lớp của ngăn xếp giao tiếp có thể định cấu hình. Để biết thông tin chi tiết, hãy xem PacketBuffer::New() cũng như tài liệu về LwIP.

Các đối tượng PacketBuffer được tính tham chiếu và chế độ sử dụng phổ biến trong Weave là "fire-and-forget". Khi gói (và đối tượng PacketBuffer cơ bản của gói này) được gửi đi qua nhiều lớp giao thức, lệnh gọi lên hoặc giảm gọi thành công giữa các lớp ngụ ý việc chuyển quyền sở hữu và hàm được gọi chịu trách nhiệm giải phóng vùng đệm. Khi lệnh gọi nhiều lớp không thành công, trách nhiệm giải phóng vùng đệm sẽ thuộc về phương thức gọi.

Các đối tượng mới của lớp PacketBuffer được khởi tạo khi bắt đầu quá trình phân bổ bộ nhớ lấy từ môi trường cơ bản, chẳng hạn như từ nhóm mục tiêu LwIP pbuf, từ vùng nhớ khối xếp thư viện C tiêu chuẩn, từ một nhóm vùng đệm nội bộ. Trong trường hợp đơn giản, kích thước của vùng đệm dữ liệu là WEAVE_SYSTEM_PACKETBUFFER_SIZE. Một trình kết hợp được cung cấp cho phép sử dụng vùng đệm dữ liệu có kích thước khác.

Các đối tượng PacketBuffer có thể được xâu chuỗi để chứa những tải trọng lớn hơn. Tuy nhiên, việc tạo chuỗi không rõ ràng và người dùng của lớp này phải quyết định rõ ràng việc hỗ trợ tạo chuỗi. Sau đây là ví dụ về các lớp được viết bằng tính năng hỗ trợ tạo chuỗi: 

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

Tính kế thừa

Kế thừa từ: pbuf

Hàm công khai
AddRef(void)
void
Tăng số lượng tham chiếu của vùng đệm hiện tại.
AddToEnd(PacketBuffer *aPacket)
void
Thêm vùng đệm gói đã cho vào cuối chuỗi vùng đệm, điều chỉnh tổng độ dài của từng vùng đệm trong chuỗi cho phù hợp.
AlignPayload(uint16_t aAlignBytes)
bool
Căn chỉnh tải trọng vùng đệm trên ranh giới byte đã chỉ định.
AllocSize(void) const
size_t
Trả về kích thước của hoạt động phân bổ, bao gồm không gian dữ liệu dành riêng và không gian dữ liệu tải trọng, nhưng không bao gồm không gian được phân bổ cho cấu trúc PacketBuffer.
AvailableDataLength(void) const
uint16_t
Lấy số byte dữ liệu có thể thêm vào vùng đệm hiện tại, dựa trên vị trí bắt đầu hiện tại và độ dài dữ liệu.
CompactHead(void)
void
Di chuyển dữ liệu từ các vùng đệm tiếp theo trong chuỗi vào vùng đệm hiện tại cho đến khi đầy.
Consume(uint16_t aConsumeLength)
Sử dụng dữ liệu trong một chuỗi vùng đệm.
ConsumeHead(uint16_t aConsumeLength)
void
Điều chỉnh vùng đệm hiện tại để cho biết lượng dữ liệu được sử dụng.
DataLength(void) const
uint16_t
Lấy độ dài, tính bằng byte, của dữ liệu trong vùng đệm gói.
DetachTail(void)
Tách vùng đệm hiện tại khỏi chuỗi rồi trả về một con trỏ về các vùng đệm còn lại.
EnsureReservedSize(uint16_t aReservedSize)
bool
Đảm bảo vùng đệm có ít nhất lượng dung lượng dự trữ đã chỉ định.
MaxDataLength(void) const
uint16_t
Nhận lượng dữ liệu tối đa (tính bằng byte) sẽ vừa với vùng đệm dựa trên vị trí bắt đầu hiện tại và dung lượng vùng đệm.
Next(void) const
Lấy con trỏ đến vùng đệm tiếp theo trong chuỗi.
ReservedSize(void) const
uint16_t
Lấy số byte trong vùng đệm hiện tại từ thời điểm bắt đầu vùng đệm đến vị trí bắt đầu dữ liệu hiện tại.
SetDataLength(uint16_t aNewLen, PacketBuffer *aChainHead)
void
Thiết lập độ dài (tính bằng byte) của dữ liệu trong vùng đệm, sau đó điều chỉnh tổng độ dài tương ứng.
SetStart(uint8_t *aNewStart)
void
Thiết lập dữ liệu bắt đầu trong vùng đệm, điều chỉnh độ dài và tổng độ dài tương ứng.
Start(void) const
uint8_t *
Lấy con trỏ đến điểm bắt đầu của dữ liệu trong vùng đệm.
TotalLength(void) const
uint16_t
Nhận tổng độ dài của dữ liệu gói trong chuỗi vùng đệm.

Hàm tĩnh công khai
Free(PacketBuffer *aPacket)
void
Giải phóng tất cả vùng đệm gói trong một chuỗi.
FreeHead(PacketBuffer *aPacket)
Giải phóng vùng đệm đầu tiên trong một chuỗi, trả về một con trỏ vào các vùng đệm còn lại.
New(void)
Phân bổ một PacketBuffer có kích thước tối đa mặc định (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) với kích thước đặt trước mặc định (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) trong tải trọng.
New(uint16_t aReservedSize)
Phân bổ một PacketBuffer có tổng kích thước tối đa với kích thước đặt trước tiêu đề cụ thể.
NewWithAvailableSize(size_t aAvailableSize)
Phân bổ một PacketBuffer có kích thước đặt trước mặc định (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) trong tải trọng cho tiêu đề và ít nhất aAllocSize byte dung lượng cho dữ liệu bổ sung sau con trỏ con trỏ ban đầu.
NewWithAvailableSize(uint16_t aReservedSize, size_t aAvailableSize)
Phân bổ một đối tượng PacketBuffer có ít nhất aReservedSize byte dành riêng trong tải trọng cho tiêu đề và ít nhất aAllocSize byte dung lượng cho dữ liệu bổ sung sau con trỏ con trỏ ban đầu.
RightSize(PacketBuffer *aPacket)
Sao chép vùng đệm nhất định vào một vùng đệm có kích thước phù hợp nếu có.

Hàm công khai

AddRef

void AddRef(
  void
)

Tăng số lượng tham chiếu của vùng đệm hiện tại.

AddToEnd

void AddToEnd(
  PacketBuffer *aPacket
)

Thêm vùng đệm gói đã cho vào cuối chuỗi vùng đệm, điều chỉnh tổng độ dài của từng vùng đệm trong chuỗi cho phù hợp.

Thông tin chi tiết
Các tham số
[in] aPacket
– vùng đệm gói cần được thêm vào cuối chuỗi hiện tại.

AlignPayload

bool AlignPayload(
  uint16_t aAlignBytes
)

Căn chỉnh tải trọng vùng đệm trên ranh giới byte đã chỉ định.

Di chuyển tải trọng trong vùng đệm về phía trước nếu cần.

Thông tin chi tiết
Các tham số
[in] aAlignBytes
– chỉ định số byte căn chỉnh cho con trỏ bắt đầu tải trọng.
Trả về
true nếu căn chỉnh thành công, false nếu không có đủ dung lượng trong vùng đệm.

AllocSize

size_t AllocSize(
  void
) const

Trả về kích thước của hoạt động phân bổ, bao gồm không gian dữ liệu dành riêng và không gian dữ liệu tải trọng, nhưng không bao gồm không gian được phân bổ cho cấu trúc PacketBuffer.

Thông tin chi tiết
Trả về
quy mô phân bổ

AvailableDataLength

uint16_t AvailableDataLength(
  void
) const

Lấy số byte dữ liệu có thể thêm vào vùng đệm hiện tại, dựa trên vị trí bắt đầu hiện tại và độ dài dữ liệu.

Thông tin chi tiết
Trả về
độ dài, tính bằng byte, của dữ liệu sẽ khớp với vùng đệm hiện tại dựa vào vị trí bắt đầu hiện tại và độ dài dữ liệu.

CompactHead

void CompactHead(
  void
)

Di chuyển dữ liệu từ các vùng đệm tiếp theo trong chuỗi vào vùng đệm hiện tại cho đến khi đầy.

Chỉ vùng đệm hiện tại được nén: dữ liệu trong vùng đệm hiện tại được chuyển lên trước vùng đệm, loại bỏ mọi không gian dành riêng. Không gian trống còn lại sẽ chứa dữ liệu được di chuyển từ các vùng đệm tiếp theo trong chuỗi cho đến khi vùng đệm hiện tại đầy. Nếu toàn bộ vùng đệm tiếp theo trong chuỗi được di chuyển vào vùng đệm hiện tại thì vùng đệm đó sẽ bị xoá khỏi chuỗi và được giải phóng. Phương thức này không nhận tham số, không trả về kết quả và không thể bị lỗi.

Tiêu thụ

PacketBuffer * Consume(
  uint16_t aConsumeLength
)

Sử dụng dữ liệu trong một chuỗi vùng đệm.

Sử dụng dữ liệu trong một chuỗi vùng đệm bắt đầu từ vùng đệm hiện tại rồi tiếp tục đi qua các vùng đệm còn lại trong chuỗi. Mỗi vùng đệm được sử dụng hoàn toàn sẽ được giải phóng và hàm trả về vùng đệm đầu tiên (nếu có) chứa dữ liệu còn lại. Vùng đệm hiện tại phải là đầu của chuỗi vùng đệm.

Thông tin chi tiết
Các tham số
[in] aConsumeLength
– số byte cần sử dụng từ chuỗi hiện tại.
Trả về
vùng đệm đầu tiên của chuỗi hiện tại chứa mọi dữ liệu còn lại. Nếu không còn dữ liệu nào thì giá trị NULL sẽ được trả về.

ConsumeHead

void ConsumeHead(
  uint16_t aConsumeLength
)

Điều chỉnh vùng đệm hiện tại để cho biết lượng dữ liệu được sử dụng.

Chuyển vị trí bắt đầu dữ liệu trong vùng đệm hiện tại bằng dung lượng đã chỉ định (tính bằng byte) cho đến độ dài của dữ liệu trong vùng đệm. Giảm thời lượng và tổng thời lượng bằng lượng nội dung đã tiêu thụ.

Thông tin chi tiết
Các tham số
[in] aConsumeLen
– số byte cần sử dụng từ vùng đệm hiện tại.

DataLength

uint16_t DataLength(
  void
) const

Lấy độ dài, tính bằng byte, của dữ liệu trong vùng đệm gói.

Thông tin chi tiết
Trả về
chiều dài, tính bằng byte (chiều dài tải trọng hiện tại).

DetachTail

PacketBuffer * DetachTail(
  void
)

Tách vùng đệm hiện tại khỏi chuỗi rồi trả về một con trỏ về các vùng đệm còn lại.

Vùng đệm hiện tại phải là đầu chuỗi.

Thông tin chi tiết
Trả về
đuôi của chuỗi vùng đệm hiện tại hoặc NULL nếu vùng đệm hiện tại là vùng đệm duy nhất trong chuỗi.

EnsureReservedSize

bool EnsureReservedSize(
  uint16_t aReservedSize
)

Đảm bảo vùng đệm có ít nhất lượng dung lượng dự trữ đã chỉ định.

Đảm bảo vùng đệm có ít nhất lượng không gian dự trữ đã chỉ định để di chuyển dữ liệu trong vùng đệm về phía trước để tạo chỗ trống nếu cần.

Thông tin chi tiết
Các tham số
[in] aReservedSize
- số byte mong muốn cho tiêu đề.
Trả về
true nếu có sẵn kích thước đặt trước được yêu cầu, false nếu không có đủ dung lượng trong vùng đệm.

MaxDataLength

uint16_t MaxDataLength(
  void
) const

Nhận lượng dữ liệu tối đa (tính bằng byte) sẽ vừa với vùng đệm dựa trên vị trí bắt đầu hiện tại và dung lượng vùng đệm.

Thông tin chi tiết
Trả về
số byte vừa với vùng đệm dựa trên vị trí bắt đầu hiện tại.

Tiếp theo

PacketBuffer * Next(
  void
) const

Lấy con trỏ đến vùng đệm tiếp theo trong chuỗi.

Thông tin chi tiết
Trả về
một con trỏ đến vùng đệm tiếp theo trong chuỗi. NULL được trả về khi không có vùng đệm trong chuỗi.

ReservedSize

uint16_t ReservedSize(
  void
) const

Lấy số byte trong vùng đệm hiện tại từ thời điểm bắt đầu vùng đệm đến vị trí bắt đầu dữ liệu hiện tại.

Thông tin chi tiết
Trả về
dung lượng (tính bằng byte) giữa điểm bắt đầu vùng đệm và vị trí bắt đầu dữ liệu hiện tại.

SetDataLength

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

Thiết lập độ dài (tính bằng byte) của dữ liệu trong vùng đệm, sau đó điều chỉnh tổng độ dài tương ứng.

Hàm này đặt độ dài của dữ liệu trong vùng đệm, tính bằng byte và điều chỉnh tổng độ dài một cách thích hợp. Khi vùng đệm không phải là phần đầu của chuỗi vùng đệm (trường hợp phổ biến: phương thức gọi thêm dữ liệu vào vùng đệm cuối cùng trong chuỗi PacketBuffer trước khi gọi các lớp cao hơn), aChainHead phải được truyền vào để điều chỉnh đúng tổng độ dài của từng vùng đệm trước vùng đệm hiện tại.

Thông tin chi tiết
Các tham số
[in] aNewLen
– độ dài mới, tính bằng byte, của vùng đệm này.
[in,out] aChainHead
– đầu của chuỗi vùng đệm chứa vùng đệm hiện tại. Có thể là NULL nếu vùng đệm hiện tại là đầu chuỗi vùng đệm.

SetStart

void SetStart(
  uint8_t *aNewStart
)

Thiết lập dữ liệu bắt đầu trong vùng đệm, điều chỉnh độ dài và tổng độ dài tương ứng.

Thông tin chi tiết
Các tham số
[in] aNewStart
– Một con trỏ đến nơi tải trọng mới bắt đầu. newStart sẽ được điều chỉnh nội bộ để nằm trong ranh giới của vùng đệm đầu tiên trong chuỗi PacketBuffer.

Bắt đầu

uint8_t * Start(
  void
) const

Lấy con trỏ đến điểm bắt đầu của dữ liệu trong vùng đệm.

Thông tin chi tiết
Trả về
con trỏ đến điểm bắt đầu dữ liệu.

TotalLength

uint16_t TotalLength(
  void
) const

Nhận tổng độ dài của dữ liệu gói trong chuỗi vùng đệm.

Thông tin chi tiết
Trả về
tổng chiều dài, tính bằng octet.

Hàm tĩnh công khai

Miễn phí

void Free(
  PacketBuffer *aPacket
)

Giải phóng tất cả vùng đệm gói trong một chuỗi.

Giảm số lượng tham chiếu xuống tất cả các vùng đệm trong chuỗi hiện tại. Nếu số lượng tham chiếu đạt đến 0, các vùng đệm tương ứng sẽ được giải phóng hoặc trở về nhóm phân bổ khi phù hợp. Theo quy tắc, người dùng nên coi phương thức này tương đương với hàm free() và không sử dụng đối số sau lệnh gọi.

Thông tin chi tiết
Các tham số
[in] aPacket
– vùng đệm gói tin cần được giải phóng.

FreeHead

PacketBuffer * FreeHead(
  PacketBuffer *aPacket
)

Giải phóng vùng đệm đầu tiên trong một chuỗi, trả về một con trỏ vào các vùng đệm còn lại.

* @note When the buffer chain is referenced by multiple callers,FreeHead()` sẽ tách phần đầu, nhưng sẽ không buộc giải phóng vùng đệm đầu.

Thông tin chi tiết
Các tham số
[in] aPacket
- chuỗi vùng đệm.
Trả về
chuỗi vùng đệm gói bao gồm đuôi của vùng đệm đầu vào (có thể là NULL).

Mới

PacketBuffer * New(
  void
)

Phân bổ một PacketBuffer có kích thước tối đa mặc định (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) với kích thước đặt trước mặc định (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) trong tải trọng.

Kích thước đặt trước (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) đủ lớn để chứa tiêu đề lớp truyền tải cũng như tiêu đề theo yêu cầu của WeaveMessageLayer và WeaveExchangeLayer.

Mới

PacketBuffer * New(
  uint16_t aReservedSize
)

Phân bổ một PacketBuffer có tổng kích thước tối đa với kích thước đặt trước tiêu đề cụ thể.

Tham số được truyền vào là kích thước được đặt trước trước tải trọng để xử lý các tiêu đề gói từ các lớp ngăn xếp khác nhau, không phải là kích thước tổng thể của vùng đệm cần phân bổ. Kích thước của vùng đệm WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX nhưng chưa được chỉ định trong lệnh gọi.

  • PacketBuffer::New(0) : khi được gọi theo cách này, vùng đệm sẽ được trả về mà không có tiêu đề nào dành riêng, do đó phương thức gọi có thể sử dụng toàn bộ tải trọng. Mẫu này đặc biệt hữu ích ở các lớp thấp hơn của ngăn xếp mạng, trong trường hợp người dùng biết rằng tải trọng sẽ được sao chép vào thông báo cuối cùng có dự trữ tiêu đề thích hợp hoặc khi tạo PacketBuffer được thêm vào chuỗi PacketBuffer qua PacketBuffer::AddToEnd(). Các tham số
    [in] aReservedSize
    lượng không gian tiêu đề cần đặt trước.
    Trả về
    Khi thành công, con trỏ tới PacketBuffer trên lỗi NULL.

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

Phân bổ một PacketBuffer có kích thước đặt trước mặc định (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) trong tải trọng cho tiêu đề và ít nhất aAllocSize byte dung lượng cho dữ liệu bổ sung sau con trỏ con trỏ ban đầu.

Cách sử dụng này phù hợp nhất khi phân bổ PacketBuffer cho thông báo ở lớp ứng dụng.

Thông tin chi tiết
Các tham số
[in] aAvailableSize
Số octet cần phân bổ sau con trỏ.
Trả về
Khi thành công, một con trỏ đến PacketBuffer trong khối được phân bổ. Khi không đạt, NULL. *

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

Phân bổ một đối tượng PacketBuffer có ít nhất aReservedSize byte dành riêng trong tải trọng cho tiêu đề và ít nhất aAllocSize byte dung lượng cho dữ liệu bổ sung sau con trỏ con trỏ ban đầu.

Thông tin chi tiết
Các tham số
[in] aReservedSize
Số octet cần đặt trước sau con trỏ.
[in] aAvailableSize
Số octet cần phân bổ sau con trỏ.
Trả về
Khi thành công, một con trỏ đến PacketBuffer trong khối được phân bổ. Khi không đạt, NULL.

RightSize

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

Sao chép vùng đệm nhất định vào một vùng đệm có kích thước phù hợp nếu có.

Hàm này không hoạt động đối với ổ cắm.

Thông tin chi tiết
Các tham số
[in] aPacket
- vùng đệm hoặc chuỗi vùng đệm.
Trả về
vùng đệm gói mới hoặc vùng đệm gốc