Packet Buffers
EmberZNet Stack API Reference

Macros

#define LOG_PACKET_BUFFER_SIZE   5
 Buffers hold 32 bytes. Defined as the log to ensure it is a power of 2.
 
#define PACKET_BUFFER_SIZE   (1 << LOG_PACKET_BUFFER_SIZE)
 Buffers hold 32 bytes.
 
#define EMBER_NULL_MESSAGE_BUFFER   0xFF
 Provides the message buffer equivalent of NULL.
 
#define emberMessageBufferLength(buffer)   (emMessageBufferLengths[buffer])
 Returns the length of a buffer. Implemented as a macro for improved efficiency.

Functions

uint8_t * emberMessageBufferContents (EmberMessageBuffer buffer)
 Gets a pointer to a buffer's contents. This pointer can be used to access only the first PACKET_BUFFER_SIZE bytes in the buffer. To read a message composed of multiple buffers, use emberCopyFromLinkedBuffers().
 
void emberSetMessageBufferLength (EmberMessageBuffer buffer, uint8_t newLength)
 Sets the length of a buffer.
 
void emberHoldMessageBuffer (EmberMessageBuffer buffer)
 Holds a message buffer by incrementing its reference count. Implemented as a macro for improved efficiency.
 
void emberReleaseMessageBuffer (EmberMessageBuffer buffer)
 Releases a message buffer by decrementing its reference count. Implemented as a macro for improved efficiency.
 
uint8_t emberPacketBufferFreeCount (void)
 Retrieves the current number of free packet buffers.

Buffer Functions

EmberMessageBuffer emberAllocateLinkedBuffers (uint8_t count)
 Allocates one or more linked buffers.
 
EmberMessageBuffer emberFillStackBuffer (unsigned int count,...)
 Allocates a stack buffer and fills the buffer with data passed in the function call.
 
#define emberStackBufferLink(buffer)   (emPacketBufferLinks[(buffer)])
 Returns the buffer that follows this one in the message. EMBER_NULL_MESSAGE_BUFFER is returned if there is no following buffer.
 
#define emberSetStackBufferLink(buffer, newLink)   (emPacketBufferLinks[(buffer)] = (newLink))
 Sets the buffer following this one in the message. The final buffer in the message has EMBER_NULL_MESSAGE_BUFFER as its link.
 
#define emberAllocateStackBuffer()   (emberAllocateLinkedBuffers(1))
 Allocates a stack buffer.

Linked Buffer Utilities

The plural "buffers" in the names of these procedures is a reminder that they deal with linked chains of buffers.

EmberMessageBuffer emberFillLinkedBuffers (uint8_t *contents, uint8_t length)
 Allocates a chain of stack buffers sufficient to hold length bytes of data and fills the buffers with the data in contents. If the value of contents is NULL, the buffers are allocated but not filled.
 
void emberCopyToLinkedBuffers (const uint8_t *contents, EmberMessageBuffer buffer, uint8_t startIndex, uint8_t length)
 Copies a specified number of bytes of data into a buffer, starting at a specified index in the buffer array. Buffer links are followed as required. No buffers are allocated or released.
 
void emberCopyFromLinkedBuffers (EmberMessageBuffer buffer, uint8_t startIndex, uint8_t *contents, uint8_t length)
 Copies length bytes of data from a buffer to contents, starting at a specified index in the buffer array. Buffer links are followed as required.
 
void emberCopyBufferBytes (EmberMessageBuffer to, uint16_t toIndex, EmberMessageBuffer from, uint16_t fromIndex, uint16_t count)
 Copies a specified number of bytes of data from one buffer into another. Buffer links are followed as required. No buffers are allocated or released.
 
void emberMoveBufferBytes (EmberMessageBuffer to, uint16_t toIndex, EmberMessageBuffer from, uint16_t fromIndex, uint16_t count)
 Allocates a chain of stack buffers sufficient to hold length bytes of data and fills the buffers with the data in contents. If the value of contents is NULL, the buffers are allocated but not filled.
 
EmberStatus emberAppendToLinkedBuffers (EmberMessageBuffer buffer, uint8_t *contents, uint8_t length)
 Appends length bytes from contents onto a buffer. Combines the functionality of ::setPacketBuffersLength() and ::copyToPacketBuffers().
 
EmberStatus emberAppendPgmStringToLinkedBuffers (EmberMessageBuffer buffer, const char *suffix)
 Appends a string from program space (flash) to a buffer.
 
EmberStatus emberSetLinkedBuffersLength (EmberMessageBuffer buffer, uint8_t length)
 Sets the length of a chain of buffers, adding or removing trailing buffers as needed.
 
uint8_t * emberGetLinkedBuffersPointer (EmberMessageBuffer buffer, uint8_t index)
 Gets a pointer to a specified byte in a linked list of buffers.
 
uint8_t emberGetLinkedBuffersByte (EmberMessageBuffer buffer, uint8_t index)
 Gets a specified byte in a linked list of buffers.
 
void emberSetLinkedBuffersByte (EmberMessageBuffer buffer, uint8_t index, uint8_t byte)
 Sets the indexed byte in a linked list of buffers.
 
uint16_t emberGetLinkedBuffersLowHighInt16u (EmberMessageBuffer buffer, uint8_t index)
 Gets a little-endian 2-byte value from a linked list of buffers.
 
void emberSetLinkedBuffersLowHighInt16u (EmberMessageBuffer buffer, uint8_t index, uint16_t value)
 Sets a little-endian 2-byte value in a linked list of buffers.
 
uint32_t emberGetLinkedBuffersLowHighInt32u (EmberMessageBuffer buffer, uint8_t index)
 Gets a little-endian 4-byte value from a linked list of buffers.
 
void emberSetLinkedBuffersLowHighInt32u (EmberMessageBuffer buffer, uint8_t index, uint32_t value)
 Sets a little-endian 4-byte value in a linked list of buffers.
 
EmberMessageBuffer emberCopyLinkedBuffers (EmberMessageBuffer buffer)
 Copies a chain of linked buffers.
 
EmberMessageBuffer emberMakeUnsharedLinkedBuffer (EmberMessageBuffer buffer, bool isShared)
 Creates a new, unshared copy of a specified buffer, if that buffer is shared. If it isn't shared, increments the reference count by 1 so that the user of the returned buffer can release it in either case.

Detailed Description

These functions implement a fixed-block-size memory management scheme to store and manipulate EmberZNet packets. Buffers are identified to clients with a 1-byte ID.

Buffers can be linked together to create longer packets. The utility procedures allow you to treat a linked chain of buffers as a single buffer.

Freeing a buffer automatically decrements the reference count of any following buffer, possibly freeing the following buffer as well.

Packet buffers may be allocated, held, and released.

See packet-buffer.h for source code.

Macro Definition Documentation

#define EMBER_NULL_MESSAGE_BUFFER   0xFF

Provides the message buffer equivalent of NULL.

#define emberAllocateStackBuffer ( )    (emberAllocateLinkedBuffers(1))

Allocates a stack buffer.

Returns
A newly allocated buffer, or EMBER_NULL_MESSAGE_BUFFER if no buffer is available.
#define emberMessageBufferLength (   buffer)    (emMessageBufferLengths[buffer])

Returns the length of a buffer. Implemented as a macro for improved efficiency.

Parameters
bufferA buffer.
Returns
The buffer length.
#define emberSetStackBufferLink (   buffer,
  newLink 
)    (emPacketBufferLinks[(buffer)] = (newLink))

Sets the buffer following this one in the message. The final buffer in the message has EMBER_NULL_MESSAGE_BUFFER as its link.

Parameters
bufferThe buffer whose link is to be set.
newLinkThe buffer that is to follow buffer.
#define emberStackBufferLink (   buffer)    (emPacketBufferLinks[(buffer)])

Returns the buffer that follows this one in the message. EMBER_NULL_MESSAGE_BUFFER is returned if there is no following buffer.

Parameters
bufferThe buffer whose following buffer is desired.
Returns
Returns the buffer that follows buffer in the message. EMBER_NULL_MESSAGE_BUFFER is returned if there is no following buffer.
#define LOG_PACKET_BUFFER_SIZE   5

Buffers hold 32 bytes. Defined as the log to ensure it is a power of 2.

#define PACKET_BUFFER_SIZE   (1 << LOG_PACKET_BUFFER_SIZE)

Buffers hold 32 bytes.

Function Documentation

EmberMessageBuffer emberAllocateLinkedBuffers ( uint8_t  count)

Allocates one or more linked buffers.

Parameters
countThe number of buffers to allocate.
Returns
The first buffer in the newly allocated chain of buffers, or EMBER_NULL_MESSAGE_BUFFER if insufficient buffers are available.
EmberStatus emberAppendPgmStringToLinkedBuffers ( EmberMessageBuffer  buffer,
const char *  suffix 
)

Appends a string from program space (flash) to a buffer.

Parameters
bufferThe buffer to append data to.
suffixThe string in program space to append.
Returns
EMBER_SUCCESS if sufficient buffers are available, and EMBER_NO_BUFFERS if not.
EmberStatus emberAppendToLinkedBuffers ( EmberMessageBuffer  buffer,
uint8_t *  contents,
uint8_t  length 
)

Appends length bytes from contents onto a buffer. Combines the functionality of ::setPacketBuffersLength() and ::copyToPacketBuffers().

Parameters
bufferThe buffer to append data to.
contentsA pointer to data to append.
lengthThe number of bytes of data to append.
Returns
EMBER_SUCCESS if sufficient buffers are available, and EMBER_NO_BUFFERS if not.
void emberCopyBufferBytes ( EmberMessageBuffer  to,
uint16_t  toIndex,
EmberMessageBuffer  from,
uint16_t  fromIndex,
uint16_t  count 
)

Copies a specified number of bytes of data from one buffer into another. Buffer links are followed as required. No buffers are allocated or released.

Parameters
toThe buffer to copy data into.
toIndexThe position in the destination buffer at which copying should start.
fromThe buffer to copy data from.
fromIndexThe position in the source buffer at which copying should start.
countThe number of bytes of data to copy.
void emberCopyFromLinkedBuffers ( EmberMessageBuffer  buffer,
uint8_t  startIndex,
uint8_t *  contents,
uint8_t  length 
)

Copies length bytes of data from a buffer to contents, starting at a specified index in the buffer array. Buffer links are followed as required.

Parameters
bufferThe buffer to copy data from.
startIndexThe buffer index at which copying should start.
contentsA pointer to data to copy from the buffer.
lengthThe number of bytes of data to copy.
EmberMessageBuffer emberCopyLinkedBuffers ( EmberMessageBuffer  buffer)

Copies a chain of linked buffers.

Parameters
bufferThe first buffer in the chain to copy.
Returns
A newly created copy of the buffer chain.
void emberCopyToLinkedBuffers ( const uint8_t *  contents,
EmberMessageBuffer  buffer,
uint8_t  startIndex,
uint8_t  length 
)

Copies a specified number of bytes of data into a buffer, starting at a specified index in the buffer array. Buffer links are followed as required. No buffers are allocated or released.

Parameters
contentsA pointer to data to copy into the buffer.
bufferThe buffer to copy data into.
startIndexThe buffer index at which copying should start.
lengthThe number of bytes of data to copy.
EmberMessageBuffer emberFillLinkedBuffers ( uint8_t *  contents,
uint8_t  length 
)

Allocates a chain of stack buffers sufficient to hold length bytes of data and fills the buffers with the data in contents. If the value of contents is NULL, the buffers are allocated but not filled.

Parameters
contentsA pointer to data to place in the allocated buffers.
lengthThe buffer length.
Returns
The first buffer in a series of linked stack buffers, or EMBER_NULL_MESSAGE_BUFFER if insufficient buffers are available.
EmberMessageBuffer emberFillStackBuffer ( unsigned int  count,
  ... 
)

Allocates a stack buffer and fills the buffer with data passed in the function call.

Parameters
countThe buffer length.
...count bytes, which will be placed in the buffer.
Returns
A newly allocated buffer, or EMBER_NULL_MESSAGE_BUFFER if no buffer is available.
uint8_t emberGetLinkedBuffersByte ( EmberMessageBuffer  buffer,
uint8_t  index 
)

Gets a specified byte in a linked list of buffers.

Parameters
bufferThe buffer that the requested byte must come from.
indexThe index of the requested byte.
Returns
A byte.
uint16_t emberGetLinkedBuffersLowHighInt16u ( EmberMessageBuffer  buffer,
uint8_t  index 
)

Gets a little-endian 2-byte value from a linked list of buffers.

Parameters
bufferThe buffer containing the 2-byte value.
indexThe index of the low byte.
Returns
The 2-byte value.
uint32_t emberGetLinkedBuffersLowHighInt32u ( EmberMessageBuffer  buffer,
uint8_t  index 
)

Gets a little-endian 4-byte value from a linked list of buffers.

Parameters
bufferThe buffer containing the 4-byte value.
indexThe index of the low byte.
Returns
The 4-byte value.
uint8_t* emberGetLinkedBuffersPointer ( EmberMessageBuffer  buffer,
uint8_t  index 
)

Gets a pointer to a specified byte in a linked list of buffers.

Parameters
bufferThe buffer that the requested byte must come from.
indexThe index of the requested byte.
Returns
A pointer to the requested byte.
void emberHoldMessageBuffer ( EmberMessageBuffer  buffer)

Holds a message buffer by incrementing its reference count. Implemented as a macro for improved efficiency.

Parameters
bufferA buffer.
EmberMessageBuffer emberMakeUnsharedLinkedBuffer ( EmberMessageBuffer  buffer,
bool  isShared 
)

Creates a new, unshared copy of a specified buffer, if that buffer is shared. If it isn't shared, increments the reference count by 1 so that the user of the returned buffer can release it in either case.

Parameters
bufferThe buffer to copy.
isSharedA flag indicating whether the buffer is shared.
Returns
A fresh copy of buffer if isShared is true, and buffer if isShared is not true.
uint8_t* emberMessageBufferContents ( EmberMessageBuffer  buffer)

Gets a pointer to a buffer's contents. This pointer can be used to access only the first PACKET_BUFFER_SIZE bytes in the buffer. To read a message composed of multiple buffers, use emberCopyFromLinkedBuffers().

Parameters
bufferThe buffer whose contents are desired.
Returns
Returns a pointer to the contents of buffer.
void emberMoveBufferBytes ( EmberMessageBuffer  to,
uint16_t  toIndex,
EmberMessageBuffer  from,
uint16_t  fromIndex,
uint16_t  count 
)

Allocates a chain of stack buffers sufficient to hold length bytes of data and fills the buffers with the data in contents. If the value of contents is NULL, the buffers are allocated but not filled.

Parameters
contentsA pointer to data to place in the allocated buffers.
lengthThe buffer length.
Returns
The first buffer in a series of linked stack buffers, or EMBER_NULL_MESSAGE_BUFFER if insufficient buffers are available.
uint8_t emberPacketBufferFreeCount ( void  )

Retrieves the current number of free packet buffers.

Returns
The number of free packet buffers.
void emberReleaseMessageBuffer ( EmberMessageBuffer  buffer)

Releases a message buffer by decrementing its reference count. Implemented as a macro for improved efficiency.

Parameters
bufferA buffer.
void emberSetLinkedBuffersByte ( EmberMessageBuffer  buffer,
uint8_t  index,
uint8_t  byte 
)

Sets the indexed byte in a linked list of buffers.

Parameters
bufferThe buffer holding the byte to be set.
indexThe index of the byte to set.
byteThe value to set the byte to.
EmberStatus emberSetLinkedBuffersLength ( EmberMessageBuffer  buffer,
uint8_t  length 
)

Sets the length of a chain of buffers, adding or removing trailing buffers as needed.

Parameters
bufferThe buffer whose length is to be set.
lengthThe length to set.
Returns
EMBER_SUCCESS if changing buffer's length by length bytes does not require additional buffers or if sufficient buffers are available, and EMBER_NO_BUFFERS if not.
void emberSetLinkedBuffersLowHighInt16u ( EmberMessageBuffer  buffer,
uint8_t  index,
uint16_t  value 
)

Sets a little-endian 2-byte value in a linked list of buffers.

Parameters
bufferThe buffer to set the 2-byte value in.
indexThe index of the low byte.
valueThe 2-byte value to set.
void emberSetLinkedBuffersLowHighInt32u ( EmberMessageBuffer  buffer,
uint8_t  index,
uint32_t  value 
)

Sets a little-endian 4-byte value in a linked list of buffers.

Parameters
bufferThe buffer to set the 2-byte value in.
indexThe index of the low byte.
valueThe 4-byte value to set.
void emberSetMessageBufferLength ( EmberMessageBuffer  buffer,
uint8_t  newLength 
)

Sets the length of a buffer.

When asserts are enabled, attempting to set a length greater than the size of the buffer triggers an assert.

Parameters
bufferA buffer
newLengthThe length to set the buffer to.