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 PacketBuffer structure and its payload data space.
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)
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)
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
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)
Free the first buffer in a chain, returning a pointer to the remaining buffers.
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.
New(uint16_t aReservedSize)
Allocates a single PacketBuffer of maximum total size with a specific header reserve size.
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.
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.
RightSize(PacketBuffer *aPacket)
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 PacketBuffer structure and its payload data space.

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.

Next

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