nl::Weave::System::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

The packet buffer class is the core structure used for manipulating packets of octet-serialized data, usually in the context of a data communications network, like Bluetooth or the Internet protocol.

Summary

In LwIP-based environments, this class is built on top of the pbuf structure defined in that library. In the absence of LwIP, Weave provides either a malloc-based implementation, or a pool-based implementation that closely approximates the memory challenges of deeply embedded devices.

The PacketBuffer class, like many similar structures used in layered network stacks, provide a mechanism to reserve space for protocol headers at each layer of a configurable communication stack. For details, see PacketBuffer::New() as well as LwIP documentation.

PacketBuffer objects are reference-counted, and the prevailing usage mode within Weave is "fire-and-forget". As the packet (and its underlying PacketBuffer object) is dispatched through various protocol layers, the successful upcall or downcall between layers implies ownership transfer, and the callee is responsible for freeing the buffer. On failure of a cross-layer call, the responsibilty for freeing the buffer rests with the caller.

New objects of PacketBuffer class are initialized at the beginning of an allocation of memory obtained from the underlying environment, e.g. from LwIP pbuf target pools, from the standard C library heap, from an internal buffer pool. In the simple case, the size of the data buffer is WEAVE_SYSTEM_PACKETBUFFER_SIZE. A composer is provided that permits usage of data buffers of other sizes.

PacketBuffer objects may be chained to accomodate larger payloads. Chaining, however, is not transparent, and users of the class must explicitly decide to support chaining. Examples of classes written with chaining support are as follows:

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

Inheritance

Inherits from: pbuf

Public functions
`AddRef(void)`	`void` Increment the reference count of the current buffer.
`AddToEnd(PacketBuffer *aPacket)`	`void` Add the given packet buffer to the end of the buffer chain, adjusting the total length of each buffer in the chain accordingly.
`AlignPayload(uint16_t aAlignBytes)`	`bool` Align the buffer payload on the specified bytes boundary.
`AllocSize(void) const`	`size_t` Return the size of the allocation including the reserved and payload data spaces but not including space allocated for the PacketBuffer structure.
`AvailableDataLength(void) const`	`uint16_t` Get the number of bytes of data that can be added to the current buffer given the current start position and data length.
`CompactHead(void)`	`void` Move data from subsequent buffers in the chain into the current buffer until it is full.
`Consume(uint16_t aConsumeLength)`	`PacketBuffer *` Consume data in a chain of buffers.
`ConsumeHead(uint16_t aConsumeLength)`	`void` Adjust the current buffer to indicate the amount of data consumed.
`DataLength(void) const`	`uint16_t` Get length, in bytes, of data in packet buffer.
`DetachTail(void)`	`PacketBuffer *` Detach the current buffer from its chain and return a pointer to the remaining buffers.
`EnsureReservedSize(uint16_t aReservedSize)`	`bool` Ensure the buffer has at least the specified amount of reserved space.
`MaxDataLength(void) const`	`uint16_t` Get the maximum amount, in bytes, of data that will fit in the buffer given the current start position and buffer size.
`Next(void) const`	`PacketBuffer *` Get pointer to next buffer in chain.
`ReservedSize(void) const`	`uint16_t` Get the number of bytes within the current buffer between the start of the buffer and the current data start position.
`SetDataLength(uint16_t aNewLen, PacketBuffer *aChainHead)`	`void` Set length, in bytes, of data in buffer, adjusting total length accordingly.
`SetStart(uint8_t *aNewStart)`	`void` Set the start data in buffer, adjusting length and total length accordingly.
`Start(void) const`	`uint8_t *` Get pointer to start of data in buffer.
`TotalLength(void) const`	`uint16_t` Get total length of packet data in the buffer chain.

Public static functions
`Free(PacketBuffer *aPacket)`	`void` Free all packet buffers in a chain.
`FreeHead(PacketBuffer *aPacket)`	`PacketBuffer *` Free the first buffer in a chain, returning a pointer to the remaining buffers.
`New(void)`	`PacketBuffer *` Allocates a single PacketBuffer of default max size (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) with default reserved size (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) in the payload.
`New(uint16_t aReservedSize)`	`PacketBuffer *` Allocates a single PacketBuffer of maximum total size with a specific header reserve size.
`NewWithAvailableSize(size_t aAvailableSize)`	`PacketBuffer *` Allocates a PacketBuffer with default reserved size (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) in the payload for headers, and at least `aAllocSize` bytes of space for additional data after the initial cursor pointer.
`NewWithAvailableSize(uint16_t aReservedSize, size_t aAvailableSize)`	`PacketBuffer *` Allocates a PacketBuffer object with at least `aReservedSize` bytes reserved in the payload for headers, and at least `aAllocSize` bytes of space for additional data after the initial cursor pointer.
`RightSize(PacketBuffer *aPacket)`	`PacketBuffer *` Copy the given buffer to a right-sized buffer if applicable.

Public functions

AddRef

void AddRef(
  void
)

Increment the reference count of the current buffer.

AddToEnd

void AddToEnd(
  PacketBuffer *aPacket
)

Add the given packet buffer to the end of the buffer chain, adjusting the total length of each buffer in the chain accordingly.

Details

Parameters

[in] aPacket

- the packet buffer to be added to the end of the current chain.

AlignPayload

bool AlignPayload(
  uint16_t aAlignBytes
)

Align the buffer payload on the specified bytes boundary.

Moving the payload in the buffer forward if necessary.

Details

Parameters

[in] aAlignBytes

- specifies number of bytes alignment for the payload start pointer.

Returns

true if alignment is successful, false if there's not enough room in the buffer.

AllocSize

size_t AllocSize(
  void
) const

Return the size of the allocation including the reserved and payload data spaces but not including space allocated for the PacketBuffer structure.

Note: The allocation size is equal or greater than aAllocSize paramater to Create method).

Details
Returns	size of the allocation

AvailableDataLength

uint16_t AvailableDataLength(
  void
) const

Get the number of bytes of data that can be added to the current buffer given the current start position and data length.

Details
Returns	the length, in bytes, of data that will fit in the current buffer given the current start position and data length.

CompactHead

void CompactHead(
  void
)

Move data from subsequent buffers in the chain into the current buffer until it is full.

Only the current buffer is compacted: the data within the current buffer is moved to the front of the buffer, eliminating any reserved space. The remaining available space is filled with data moved from subsequent buffers in the chain, until the current buffer is full. If a subsequent buffer in the chain is moved into the current buffer in its entirety, it is removed from the chain and freed. The method takes no parameters, returns no results and cannot fail.

Consume

PacketBuffer * Consume(
  uint16_t aConsumeLength
)

Consume data in a chain of buffers.

Consume data in a chain of buffers starting with the current buffer and proceeding through the remaining buffers in the chain. Each buffer that is completely consumed is freed and the function returns the first buffer (if any) containing the remaining data. The current buffer must be the head of the buffer chain.

Details

Parameters

[in] aConsumeLength

- number of bytes to consume from the current chain.

Returns

the first buffer from the current chain that contains any remaining data. If no data remains, a NULL is returned.

ConsumeHead

void ConsumeHead(
  uint16_t aConsumeLength
)

Adjust the current buffer to indicate the amount of data consumed.

Advance the data start position in the current buffer by the specified amount, in bytes, up to the length of data in the buffer. Decrease the length and total length by the amount consumed.

Details

Parameters

[in] aConsumeLen

- number of bytes to consume from the current buffer.

DataLength

uint16_t DataLength(
  void
) const

Get length, in bytes, of data in packet buffer.

Details
Returns	length, in bytes (current payload length).

DetachTail

PacketBuffer * DetachTail(
  void
)

Detach the current buffer from its chain and return a pointer to the remaining buffers.

The current buffer must be the head of the chain.

Details
Returns	the tail of the current buffer chain or NULL if the current buffer is the only buffer in the chain.

EnsureReservedSize

bool EnsureReservedSize(
  uint16_t aReservedSize
)

Ensure the buffer has at least the specified amount of reserved space.

Ensure the buffer has at least the specified amount of reserved space moving the data in the buffer forward to make room if necessary.

Details

Parameters

[in] aReservedSize

- number of bytes desired for the headers.

Returns

true if the requested reserved size is available, false if there's not enough room in the buffer.

MaxDataLength

uint16_t MaxDataLength(
  void
) const

Get the maximum amount, in bytes, of data that will fit in the buffer given the current start position and buffer size.

Details
Returns	number of bytes that fits in the buffer given the current start position.

PacketBuffer * Next(
  void
) const

Get pointer to next buffer in chain.

Details
Returns	a pointer to the next buffer in the chain. `NULL` is returned when there is no buffers in the chain.

ReservedSize

uint16_t ReservedSize(
  void
) const

Get the number of bytes within the current buffer between the start of the buffer and the current data start position.

Details
Returns	the amount, in bytes, of space between the start of the buffer and the current data start position.

SetDataLength

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

Set length, in bytes, of data in buffer, adjusting total length accordingly.

The function sets the length, in bytes, of the data in the buffer, adjusting the total length appropriately. When the buffer is not the head of the buffer chain (common case: the caller adds data to the last buffer in the PacketBuffer chain prior to calling higher layers), the aChainHead must be passed in to properly adjust the total lengths of each buffer ahead of the current buffer.

Details

Parameters

`[in] aNewLen`	- new length, in bytes, of this buffer.
`[in,out] aChainHead`	- the head of the buffer chain the current buffer belongs to. May be NULL if the current buffer is the head of the buffer chain.

SetStart

void SetStart(
  uint8_t *aNewStart
)

Set the start data in buffer, adjusting length and total length accordingly.

Details

Parameters

[in] aNewStart

- A pointer to where the new payload should start. newStart will be adjusted internally to fall within the boundaries of the first buffer in the PacketBuffer chain.

Start

uint8_t * Start(
  void
) const

Get pointer to start of data in buffer.

Details
Returns	pointer to the start of data.

TotalLength

uint16_t TotalLength(
  void
) const

Get total length of packet data in the buffer chain.

Details
Returns	total length, in octets.

Public static functions

Free

void Free(
  PacketBuffer *aPacket
)

Free all packet buffers in a chain.

Decrement the reference count to all the buffers in the current chain. If the reference count reaches 0, the respective buffers are freed or returned to allocation pools as appropriate. As a rule, users should treat this method as an equivalent of free() function and not use the argument after the call.

Details

Parameters

[in] aPacket

- packet buffer to be freed.

FreeHead

PacketBuffer * FreeHead(
  PacketBuffer *aPacket
)

Free the first buffer in a chain, returning a pointer to the remaining buffers.

* @note When the buffer chain is referenced by multiple callers,FreeHead()` will detach the head, but will not forcibly deallocate the head buffer.

Details

Parameters

[in] aPacket

- buffer chain.

Returns

packet buffer chain consisting of the tail of the input buffer (may be NULL).

New

PacketBuffer * New(
  void
)

Allocates a single PacketBuffer of default max size (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) with default reserved size (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) in the payload.

The reserved size (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) is large enough to hold transport layer headers as well as headers required by WeaveMessageLayer and WeaveExchangeLayer.

New

PacketBuffer * New(
  uint16_t aReservedSize
)

Allocates a single PacketBuffer of maximum total size with a specific header reserve size.

The parameter passed in is the size reserved prior to the payload to accomodate packet headers from different stack layers, not the overall size of the buffer to allocate. The size of the buffer WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX and not, specified in the call.

PacketBuffer::New(0) : when called in this fashion, the buffer will be returned without any header reserved, consequently the entire payload is usable by the caller. This pattern is particularly useful at the lower layers of networking stacks, in cases where the user knows the payload will be copied out into the final message with appropriate header reserves or in creating PacketBuffer that are appended to a chain of PacketBuffer via PacketBuffer::AddToEnd(). Parameters

[in] aReservedSize

amount of header space to reserve.

Returns

On success, a pointer to the PacketBuffer, on failure NULL.

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

Allocates a PacketBuffer with default reserved size (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) in the payload for headers, and at least aAllocSize bytes of space for additional data after the initial cursor pointer.

This usage is most appropriate when allocating a PacketBuffer for an application-layer message.

Details

Parameters

[in] aAvailableSize

Number of octets to allocate after the cursor.

Returns

On success, a pointer to the PacketBuffer in the allocated block. On fail, NULL. *

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

Allocates a PacketBuffer object with at least aReservedSize bytes reserved in the payload for headers, and at least aAllocSize bytes of space for additional data after the initial cursor pointer.

Details

Parameters

`[in] aReservedSize`	Number of octets to reserve behind the cursor.
`[in] aAvailableSize`	Number of octets to allocate after the cursor.

Returns

On success, a pointer to the PacketBuffer in the allocated block. On fail, NULL.

RightSize

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

Copy the given buffer to a right-sized buffer if applicable.

This function is a no-op for sockets.

Details

Parameters

[in] aPacket

- buffer or buffer chain.

Returns

new packet buffer or the original buffer