нл:: Переплетение:: Система:: ПакетБуфер

#include <src/system/SystemPacketBuffer.h>

Класс буфера пакетов — это базовая структура, используемая для управления пакетами данных, сериализованных по октетам, обычно в контексте сети передачи данных, такой как Bluetooth или Интернет-протокол.

Краткое содержание

В средах на основе LwIP этот класс создается поверх структуры pbuf, определенной в этой библиотеке. В отсутствие LwIP Weave предоставляет либо реализацию на основе malloc, либо реализацию на основе пула, которая близко соответствует проблемам памяти глубоко встроенных устройств.

Класс PacketBuffer , как и многие подобные структуры, используемые в многоуровневых сетевых стеках, предоставляет механизм резервирования места для заголовков протоколов на каждом уровне настраиваемого коммуникационного стека. Подробности см. в PacketBuffer::New() а также в документации LwIP.

Объекты PacketBuffer подсчитываются по ссылкам, а преобладающий режим использования в Weave — «выстрелил и забыл». Поскольку пакет (и лежащий в его основе объект PacketBuffer ) отправляется через различные уровни протокола, успешный восходящий или нисходящий вызов между уровнями подразумевает передачу владения, и вызываемый объект несет ответственность за освобождение буфера. В случае сбоя межуровневого вызова ответственность за освобождение буфера лежит на вызывающей стороне.

Новые объекты класса PacketBuffer инициализируются в начале выделения памяти, полученной из базовой среды, например, из целевых пулов LwIP pbuf, из кучи стандартной библиотеки C, из внутреннего буферного пула. В простом случае размер буфера данных равен WEAVE_SYSTEM_PACKETBUFFER_SIZE . Предоставляется композитор, который позволяет использовать буферы данных других размеров.

Объекты PacketBuffer могут быть объединены в цепочку для размещения более крупных полезных данных. Однако цепочка не является прозрачной, и пользователи класса должны явно решить поддерживать цепочку. Ниже приведены примеры классов, написанных с поддержкой цепочек: 

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

Наследование

Наследуется от: pbuf

Общественные функции

AddRef (void)
void
Увеличивает счетчик ссылок текущего буфера.
AddToEnd ( PacketBuffer *aPacket)
void
Добавьте данный буфер пакета в конец цепочки буферов, соответствующим образом корректируя общую длину каждого буфера в цепочке.
AlignPayload (uint16_t aAlignBytes)
bool
Выровняйте полезную нагрузку буфера по указанной границе байтов.
AllocSize (void) const
size_t
Возвращает размер выделения, включая зарезервированные пространства и пространства полезных данных, но не включая пространство, выделенное для структуры PacketBuffer .
AvailableDataLength (void) const
uint16_t
Получите количество байтов данных, которые можно добавить в текущий буфер с учетом текущей начальной позиции и длины данных.
CompactHead (void)
void
Перемещайте данные из последующих буферов в цепочке в текущий буфер, пока он не заполнится.
Consume (uint16_t aConsumeLength)
Потребляйте данные в цепочке буферов.
ConsumeHead (uint16_t aConsumeLength)
void
Отрегулируйте текущий буфер, чтобы указать объем потребляемых данных.
DataLength (void) const
uint16_t
Получить длину в байтах данных в буфере пакетов.
DetachTail (void)
Отсоедините текущий буфер от его цепочки и верните указатель на оставшиеся буферы.
EnsureReservedSize (uint16_t aReservedSize)
bool
Убедитесь, что в буфере имеется хотя бы указанный объем зарезервированного пространства.
MaxDataLength (void) const
uint16_t
Получите максимальный объем данных в байтах, который поместится в буфер с учетом текущей начальной позиции и размера буфера.
Next (void) const
Получить указатель на следующий буфер в цепочке.
ReservedSize (void) const
uint16_t
Получите количество байтов в текущем буфере между началом буфера и текущей начальной позицией данных.
SetDataLength (uint16_t aNewLen, PacketBuffer *aChainHead)
void
Установите длину данных в буфере в байтах, соответствующим образом корректируя общую длину.
SetStart (uint8_t *aNewStart)
void
Установите начальные данные в буфер, соответствующим образом отрегулировав длину и общую длину.
Start (void) const
uint8_t *
Получить указатель на начало данных в буфере.
TotalLength (void) const
uint16_t
Получите общую длину пакетных данных в цепочке буферов.

Публичные статические функции

Free ( PacketBuffer *aPacket)
void
Освободите все буферы пакетов в цепочке.
FreeHead ( PacketBuffer *aPacket)
Освободите первый буфер в цепочке, вернув указатель на оставшиеся буферы.
New (void)
Выделяет один PacketBuffer максимального размера по умолчанию ( WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX ) с зарезервированным размером по умолчанию ( WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE ) в полезных данных.
New (uint16_t aReservedSize)
Выделяет один PacketBuffer максимального общего размера с определенным размером резерва заголовка.
NewWithAvailableSize (size_t aAvailableSize)
Выделяет PacketBuffer с зарезервированным размером по умолчанию ( WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE ) в полезных данных для заголовков и как минимум aAllocSize байтов пространства для дополнительных данных после указателя начального курсора.
NewWithAvailableSize (uint16_t aReservedSize, size_t aAvailableSize)
Выделяет для объекта PacketBuffer не менее байтов aReservedSize зарезервированных в полезных данных для заголовков, и не менее байтов aAllocSize пространства для дополнительных данных после исходного указателя курсора.
RightSize ( PacketBuffer *aPacket)
Скопируйте данный буфер в буфер подходящего размера, если это применимо.

Общественные функции

ДобавитьСсылку

void AddRef(
  void
)

Увеличивает счетчик ссылок текущего буфера.

ДобавитьToEnd

void AddToEnd(
  PacketBuffer *aPacket
)

Добавьте данный буфер пакета в конец цепочки буферов, соответствующим образом корректируя общую длину каждого буфера в цепочке.

Подробности
Параметры
[in] aPacket
- буфер пакетов, который будет добавлен в конец текущей цепочки.

Выровнять полезную нагрузку

bool AlignPayload(
  uint16_t aAlignBytes
)

Выровняйте полезную нагрузку буфера по указанной границе байтов.

Перемещение полезной нагрузки в буфере вперед, если необходимо.

Подробности
Параметры
[in] aAlignBytes
- указывает количество выравниваний байтов для указателя начала полезной нагрузки.
Возврат
true , если выравнивание прошло успешно, false , если в буфере недостаточно места.

Аллоксизе

size_t AllocSize(
  void
) const

Возвращает размер выделения, включая зарезервированные пространства и пространства полезных данных, но не включая пространство, выделенное для структуры PacketBuffer .

Подробности
Возврат
размер распределения

Доступная длина данных

uint16_t AvailableDataLength(
  void
) const

Получите количество байтов данных, которые можно добавить в текущий буфер с учетом текущей начальной позиции и длины данных.

Подробности
Возврат
длина в байтах данных, которые поместятся в текущий буфер с учетом текущей начальной позиции и длины данных.

КомпактГед

void CompactHead(
  void
)

Перемещайте данные из последующих буферов в цепочке в текущий буфер, пока он не заполнится.

Сжимается только текущий буфер: данные из текущего буфера перемещаются в начало буфера, устраняя любое зарезервированное пространство. Оставшееся доступное пространство заполняется данными, перемещенными из последующих буферов в цепочке, пока текущий буфер не заполнится. Если последующий буфер в цепочке полностью перемещается в текущий буфер, он удаляется из цепочки и освобождается. Этот метод не принимает параметров, не возвращает результатов и не может дать сбой.

Потреблять

PacketBuffer * Consume(
  uint16_t aConsumeLength
)

Потребляйте данные в цепочке буферов.

Потребляйте данные в цепочке буферов, начиная с текущего буфера и заканчивая остальными буферами в цепочке. Каждый полностью использованный буфер освобождается, и функция возвращает первый буфер (если есть), содержащий оставшиеся данные. Текущий буфер должен быть главой цепочки буферов.

Подробности
Параметры
[in] aConsumeLength
- количество байтов, которые необходимо использовать из текущей цепочки.
Возврат
первый буфер текущей цепочки, содержащий все оставшиеся данные. Если данных не осталось, возвращается NULL.

Поглотитьголову

void ConsumeHead(
  uint16_t aConsumeLength
)

Отрегулируйте текущий буфер, чтобы указать объем потребляемых данных.

Переместить начальную позицию данных в текущем буфере на указанную величину в байтах до длины данных в буфере. Уменьшите длину и общую длину на потребляемую сумму.

Подробности
Параметры
[in] aConsumeLen
- количество байтов, которые будут использованы из текущего буфера.

Длина данных

uint16_t DataLength(
  void
) const

Получить длину в байтах данных в буфере пакетов.

Подробности
Возврат
длина в байтах (текущая длина полезных данных).

Отсоединить хвост

PacketBuffer * DetachTail(
  void
)

Отсоедините текущий буфер от его цепочки и верните указатель на оставшиеся буферы.

Текущий буфер должен быть главой цепочки.

Подробности
Возврат
конец текущей цепочки буферов или NULL, если текущий буфер является единственным буфером в цепочке.

Обеспечьтерезерведсизе

bool EnsureReservedSize(
  uint16_t aReservedSize
)

Убедитесь, что в буфере имеется хотя бы указанный объем зарезервированного пространства.

Убедитесь, что в буфере имеется хотя бы указанный объем зарезервированного пространства, перемещая данные в буфере вперед, чтобы освободить место, если это необходимо.

Подробности
Параметры
[in] aReservedSize
- количество байтов, необходимое для заголовков.
Возврат
true , если запрошенный зарезервированный размер доступен, false , если в буфере недостаточно места.

Максдатадлина

uint16_t MaxDataLength(
  void
) const

Получите максимальный объем данных в байтах, который поместится в буфер с учетом текущей начальной позиции и размера буфера.

Подробности
Возврат
количество байтов, которое помещается в буфер с учетом текущей начальной позиции.

Следующий

PacketBuffer * Next(
  void
) const

Получить указатель на следующий буфер в цепочке.

Подробности
Возврат
указатель на следующий буфер в цепочке. NULL возвращается, когда в цепочке нет буферов.

Зарезервированный размер

uint16_t ReservedSize(
  void
) const

Получите количество байтов в текущем буфере между началом буфера и текущей начальной позицией данных.

Подробности
Возврат
объем пространства в байтах между началом буфера и текущей начальной позицией данных.

SetDataLength

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

Установите длину данных в буфере в байтах, соответствующим образом корректируя общую длину.

Функция устанавливает длину данных в буфере в байтах, соответствующим образом корректируя общую длину. Когда буфер не является главой цепочки буферов (обычный случай: вызывающая сторона добавляет данные в последний буфер в цепочке PacketBuffer перед вызовом более высоких уровней), необходимо передать aChainHead, чтобы правильно настроить общую длину каждого буфера впереди. текущего буфера.

Подробности
Параметры
[in] aNewLen
- новая длина этого буфера в байтах.
[in,out] aChainHead
- заголовок цепочки буферов, к которой принадлежит текущий буфер. Может быть NULL, если текущий буфер является главой цепочки буферов.

УстановитьСтарт

void SetStart(
  uint8_t *aNewStart
)

Установите начальные данные в буфер, соответствующим образом отрегулировав длину и общую длину.

Подробности
Параметры
[in] aNewStart
— Указатель того, где должна начинаться новая полезная нагрузка. newStart будет внутренне скорректирован так, чтобы он попадал в границы первого буфера в цепочке PacketBuffer .

Начинать

uint8_t * Start(
  void
) const

Получить указатель на начало данных в буфере.

Подробности
Возврат
указатель на начало данных.

Общая длина

uint16_t TotalLength(
  void
) const

Получите общую длину пакетных данных в цепочке буферов.

Подробности
Возврат
общая длина в октетах.

Публичные статические функции

Бесплатно

void Free(
  PacketBuffer *aPacket
)

Освободите все буферы пакетов в цепочке.

Уменьшите счетчик ссылок для всех буферов в текущей цепочке. Если счетчик ссылок достигает 0, соответствующие буферы освобождаются или возвращаются в пулы выделения в зависимости от ситуации. Как правило, пользователи должны рассматривать этот метод как эквивалент функции free() и не использовать аргумент после вызова.

Подробности
Параметры
[in] aPacket
- буфер пакетов, который необходимо освободить.

FreeHead

PacketBuffer * FreeHead(
  PacketBuffer *aPacket
)

Освободите первый буфер в цепочке, вернув указатель на оставшиеся буферы.

* @note When the buffer chain is referenced by multiple callers, FreeHead() ` отсоединит головной буфер, но не будет принудительно освобождать головной буфер.

Подробности
Параметры
[in] aPacket
- буферная цепь.
Возврат
цепочка буферов пакетов, состоящая из хвоста входного буфера (может быть NULL ).

Новый

PacketBuffer * New(
  void
)

Выделяет один PacketBuffer максимального размера по умолчанию ( WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX ) с зарезервированным размером по умолчанию ( WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE ) в полезных данных.

Зарезервированный размер ( WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE ) достаточно велик для хранения заголовков транспортного уровня, а также заголовков, необходимых WeaveMessageLayer и WeaveExchangeLayer .

Новый

PacketBuffer * New(
  uint16_t aReservedSize
)

Выделяет один PacketBuffer максимального общего размера с определенным размером резерва заголовка.

Передаваемый параметр — это размер, зарезервированный до полезной нагрузки для размещения заголовков пакетов из разных уровней стека, а не общий размер выделяемого буфера. Размер буфера WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX и не указан при вызове.

  • PacketBuffer::New(0) : при таком вызове буфер будет возвращен без зарезервированного заголовка, следовательно, вся полезная нагрузка может использоваться вызывающей стороной. Этот шаблон особенно полезен на нижних уровнях сетевых стеков, в тех случаях, когда пользователь знает, что полезная нагрузка будет скопирована в окончательное сообщение с соответствующими резервами заголовка, или при создании PacketBuffer , который добавляется к цепочке PacketBuffer через PacketBuffer::AddToEnd() . Параметры
    [in] aReservedSize
    объем пространства заголовка, который необходимо зарезервировать.
    Возврат
    В случае успеха — указатель на PacketBuffer , в случае неудачи NULL .

НовыйСДоступныйРазмер

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

Выделяет PacketBuffer с зарезервированным размером по умолчанию ( WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE ) в полезных данных для заголовков и как минимум aAllocSize байтов пространства для дополнительных данных после указателя начального курсора.

Такое использование наиболее целесообразно при выделении PacketBuffer для сообщения уровня приложения.

Подробности
Параметры
[in] aAvailableSize
Количество октетов, выделяемых после курсора.
Возврат
В случае успеха — указатель на PacketBuffer в выделенном блоке. В случае неудачи NULL . *

НовыйСДоступныйРазмер

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

Выделяет для объекта PacketBuffer не менее байтов aReservedSize зарезервированных в полезных данных для заголовков, и не менее байтов aAllocSize пространства для дополнительных данных после исходного указателя курсора.

Подробности
Параметры
[in] aReservedSize
Количество октетов, которые необходимо зарезервировать за курсором.
[in] aAvailableSize
Количество октетов, выделяемых после курсора.
Возврат
В случае успеха указатель на PacketBuffer в выделенном блоке. В случае неудачи NULL .

Правильный размер

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

Скопируйте данный буфер в буфер подходящего размера, если это применимо.

Эта функция неактивна для сокетов.

Подробности
Параметры
[in] aPacket
- буфер или буферная цепочка.
Возврат
новый буфер пакетов или исходный буфер