nl::Weave::Hệ thống::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

Lớp bộ đệm gói là cấu trúc cốt lõi được dùng để thao tác các gói dữ liệu nối tiếp octet, thường dùng trong bối cảnh của mạng giao tiếp dữ liệu, chẳng hạn như Bluetooth hoặc giao thức Internet.

Tóm tắt

Trong 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 pháp triển khai dựa trên trung tâm mua sắm hoặc triển khai dựa trên nhóm gần giống với thử thách 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 theo lớp) cung cấp một cơ chế để đặt trước không gian cho tiêu đề giao thức ở mỗi lớp của một 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 gửi qua nhiều lớp giao thức, lệnh gọi lên hoặc lệnh gọi xuống thành công giữa các lớp ngụ ý rằng quá trình chuyển quyền sở hữu sẽ được thực hiện và lệnh gọi sẽ chịu trách nhiệm giải phóng bộ đệm. Khi không có lệnh gọi nhiều lớp, trách nhiệm giải phóng bộ đệm sẽ được thực hiện với người gọi.

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

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

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

Hàm tĩnh công khai

Free(PacketBuffer *aPacket)
void
Giải phóng tất cả bộ đệm gói trong một chuỗi.
FreeHead(PacketBuffer *aPacket)
Giải phóng bộ đệm đầu tiên trong một chuỗi, trả con trỏ về các bộ đệ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_FRAME_CONFIG_PACKETBUFFER_Capacity_MAX) với kích thước đặt trước mặc định (WEAVE_FRAME_CONFIG_HEADER_RESERVE_SIZE) trong phần tải trọng.
New(uint16_t aReservedSize)
Phân bổ một PacketBuffer (tổng kích thước tối đa) với một kích thước đặt trước tiêu đề cụ thể.
NewWithAvailableSize(size_t aAvailableSize)
Phân bổ PacketBuffer với kích thước đặt trước mặc định (WEAVE_SETTINGS_CONFIG_HEADER_RESERVE_SIZE) trong phần dữ liệu thực tế cho các 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ổ đối tượng PacketBuffer với ít nhất aReservedSize byte được đặt trước 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 bộ đệm đã chọn vào bộ đệm có kích thước bên phải nếu có.

Hàm công khai

Thêm tham chiếu

void AddRef(
  void
)

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

Thêm

void AddToEnd(
  PacketBuffer *aPacket
)

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

Chi tiết
Các thông số
[in] aPacket
– bộ đệm gói cần thêm vào cuối chuỗi hiện tại.

PayPayload

bool AlignPayload(
  uint16_t aAlignBytes
)

Căn chỉnh tải trọng của bộ đệm vào ranh giới byte đã chỉ định.

Di chuyển phần tải dữ liệu trong bộ đệm về phía trước nếu cần.

Chi tiết
Các thông số
[in] aAlignBytes
– chỉ định số lượng căn chỉnh byte 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 bộ đệm.

Kích thước phân bổ

size_t AllocSize(
  void
) const 

Trả về kích thước phân bổ, bao gồm cả không gian dữ liệu đặt trước và không tải, nhưng không bao gồm dung lượng được phân bổ cho cấu trúc PacketBuffer.

Chi tiết
Trả về
quy mô phân bổ

Độ dài dữ liệu có sẵn

uint16_t AvailableDataLength(
  void
) const 

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

Chi tiết
Trả về
độ dài, tính bằng byte, của dữ liệu sẽ vừa với bộ đệm hiện tại với vị trí bắt đầu hiện tại và độ dài dữ liệu.

Đầu thu gọn

void CompactHead(
  void
)

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

Chỉ có bộ đệm hiện tại được nén lại: dữ liệu trong bộ đệm hiện tại được di chuyển sang phía trước bộ đệm, loại bỏ mọi không gian đặt trước. Không gian còn trống còn lại sẽ được lấp đầy dữ liệu từ các bộ đệm tiếp theo trong chuỗi cho đến khi bộ đệm hiện tại đầy. Nếu một bộ đệm tiếp theo trong chuỗi được chuyển toàn bộ vào bộ đệm hiện tại, thì bộ đệm đó sẽ bị xóa 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ả nào và không thể xử lý được.

Tiêu thụ

PacketBuffer * Consume(
  uint16_t aConsumeLength
)

Tiêu thụ dữ liệu trong một chuỗi bộ đệm.

Tiêu thụ dữ liệu trong một chuỗi bộ đệm bắt đầu bằng bộ đệm hiện tại và tiếp tục thông qua các bộ đệm còn lại trong chuỗi. Mỗi bộ đệm được sử dụng hoàn toàn sẽ được giải phóng và hàm sẽ trả về bộ đệ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à phần đầu của chuỗi đệm.

Chi tiết
Các thông số
[in] aConsumeLength
– số lượng byte cần dùng trong chuỗi hiện tại.
Trả về
bộ đệm đầu tiên trong chuỗi hiện tại chứa bất kỳ dữ liệu nào còn lại. Nếu không còn dữ liệu nào, giá trị NULL sẽ được trả về.

Đầu tiêu thụ

void ConsumeHead(
  uint16_t aConsumeLength
)

Điều chỉnh bộ đệm hiện tại để cho biết lượng dữ liệu tiêu thụ.

Tăng trước vị trí bắt đầu dữ liệu trong bộ đệm hiện tại theo số lượng đã chỉ định, tính bằng byte, lên đến độ dài của dữ liệu trong bộ đệm. Giảm thời lượng và tổng thời lượng theo số tiền đã chi tiêu.

Chi tiết
Các thông số
[in] aConsumeLen
— số byte cần sử dụng từ bộ đệm hiện tại.

Độ dài dữ liệu

uint16_t DataLength(
  void
) const 

Nhận độ dài, tính bằng byte, của dữ liệu trong bộ đệm gói.

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

Dây đuôi áo

PacketBuffer * DetachTail(
  void
)

Tách bộ đệm hiện tại khỏi chuỗi và trả lại con trỏ đến các bộ đệm còn lại.

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

Chi tiết
Trả về
đuôi của chuỗi bộ đệm hiện tại hoặc NULL nếu bộ đệm hiện tại là bộ đệm duy nhất trong chuỗi.

Đảm bảo kích thước đặt trước

bool EnsureReservedSize(
  uint16_t aReservedSize
)

Đảm bảo bộ đệm có ít nhất khoảng không gian đặt trước được chỉ định.

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

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

Độ dài dữ liệu tối đa

uint16_t MaxDataLength(
  void
) const 

Lấy lượng dữ liệu tối đa, tính bằng byte, sẽ phù hợp với bộ đệm dựa trên vị trí bắt đầu hiện tại và kích thước bộ đệm.

Chi tiết
Trả về
số byte phù hợp với bộ đệm dựa vào vị trí bắt đầu hiện tại.

Tiếp

PacketBuffer * Next(
  void
) const 

Lấy con trỏ đến bộ đệm tiếp theo trong chuỗi.

Chi tiết
Trả về
một con trỏ đến bộ đệm tiếp theo trong chuỗi. NULL được trả về khi không có bộ đệm nào trong chuỗi.

Kích thước Đặt trước

uint16_t ReservedSize(
  void
) const 

Lấy số byte trong bộ đệm hiện tại giữa thời gian bắt đầu của bộ đệm và vị trí bắt đầu dữ liệu hiện tại.

Chi tiết
Trả về
số lượng, tính bằng byte, không gian giữa điểm bắt đầu của bộ đệm và vị trí bắt đầu dữ liệu hiện tại.

Đặt thời lượng dữ liệu

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

Đặt độ dài, tính bằng byte, của dữ liệu trong bộ đệm, điều chỉnh tổng độ dài cho phù hợp.

Hàm này đặt độ dài, tính bằng byte, của dữ liệu trong bộ đệm, đ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 bộ đệm (trường hợp phổ biến: người gọi thêm dữ liệu vào bộ đệm cuối cùng trong chuỗi PacketBuffer trước khi gọi các lớp cao hơn), hệ thống phải chuyển ChaChainhead để điều chỉnh đúng tổng độ dài của mỗi bộ đệm trước khung đệm hiện tại.

Chi tiết
Các thông số
[in] aNewLen
– độ dài mới (tính bằng byte) của bộ đệm này.
[in,out] aChainHead
- đầu của chuỗi bộ đệm hiện có bộ đệm. Có thể là NULL nếu bộ đệm hiện tại là phần đầu của chuỗi bộ đệm.

Bắt đầu đặt

void SetStart(
  uint8_t *aNewStart
)

Đặt dữ liệu bắt đầu trong bộ đệm, điều chỉnh thời lượng và tổng thời lượng cho phù hợp.

Chi tiết
Các thông số
[in] aNewStart
– Một con trỏ đến nơi tải trọng mới sẽ bắt đầu. newStart sẽ được điều chỉnh nội bộ để nằm trong phạm vi của bộ đệm đầu tiên trong chuỗi PacketBuffer.

Bắt đầu

uint8_t * Start(
  void
) const 

Lấy con trỏ để bắt đầu dữ liệu trong bộ đệm.

Chi tiết
Trả về
con trỏ đến đầu dữ liệu.

Tổng chiều dài

uint16_t TotalLength(
  void
) const 

Lấy tổng độ dài của dữ liệu gói trong chuỗi đệm.

Chi tiết
Trả về
tổng chiều dài, trong hệ bát phân.

Hàm tĩnh công khai

Miễn phí

void Free(
  PacketBuffer *aPacket
)

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

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

Chi tiết
Các thông số
[in] aPacket
- bộ đệm gói cần giải phóng.

Đầu tự do

PacketBuffer * FreeHead(
  PacketBuffer *aPacket
)

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

* @note When the buffer chain is referenced by multiple callers,FreeHEAD()` sẽ tháo đầu ra nhưng không buộc buộc bộ đệm đầu.

Chi tiết
Các thông số
[in] aPacket
- chuỗi bộ đệm.
Trả về
chuỗi bộ đệm gói bao gồm đuôi của bộ đệ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_FRAME_CONFIG_PACKETBUFFER_Capacity_MAX) với kích thước đặt trước mặc định (WEAVE_FRAME_CONFIG_HEADER_RESERVE_SIZE) trong phần tải trọng.

Kích thước đặt trước (WEAVE_FRAME_CONFIG_HEADER_RESERVE_SIZE) đủ lớn để chứa các tiêu đề lớp truyền tải cũng như các tiêu đề mà WeaveMessageLayerWeaveExchangeLayer yêu cầu.

Mới

PacketBuffer * New(
  uint16_t aReservedSize
)

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

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

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

NewWithCóSizeKích thước

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

Phân bổ PacketBuffer với kích thước đặt trước mặc định (WEAVE_SETTINGS_CONFIG_HEADER_RESERVE_SIZE) trong phần dữ liệu thực tế cho các 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.

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

NewWithCóSizeKích thước

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

Phân bổ đối tượng PacketBuffer với ít nhất aReservedSize byte được đặt trước 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.

Chi tiết
Các thông số
[in] aReservedSize
Số lượng giá trị bát phân để đặt trước phía sau con trỏ.
[in] aAvailableSize
Số lượng bát phân cần phân bổ sau con trỏ.
Trả về
Khi thành công, một con trỏ đến PacketBuffer trong khối đã phân bổ. Khi không thành công, NULL.

Kích thước bên phải

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

Sao chép bộ đệm đã chọn vào bộ đệm có kích thước bên phải nếu có.

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

Chi tiết
Các thông số
[in] aPacket
– bộ đệm hoặc chuỗi đệm.
Trả về
bộ đệm gói mới hoặc bộ đệm ban đầu