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 (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 emberAppendPgmToLinkedBuffers ( EmberMessageBuffer buffer, PGM_P contents, uint8_t length)
Appends length bytes from contents , a pointer into program space (flash) to buffer.
EmberStatus emberAppendPgmStringToLinkedBuffers ( EmberMessageBuffer buffer, PGM_P 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
buffer A 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
buffer The buffer whose link is to be set.
newLink The 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
buffer The 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
count The 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,
PGM_P suffix
)

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

Parameters
buffer The buffer to append data to.
suffix The string in program space to append.
Returns
EMBER_SUCCESS if sufficient buffers are available, and EMBER_NO_BUFFERS if not.
EmberStatus emberAppendPgmToLinkedBuffers ( EmberMessageBuffer buffer,
PGM_P contents,
uint8_t length
)

Appends length bytes from contents , a pointer into program space (flash) to buffer.

Parameters
buffer The buffer to append data to.
contents The data to append.
length The number of bytes of data 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
buffer The buffer to append data to.
contents A pointer to data to append.
length The 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
to The buffer to copy data into.
toIndex The position in the destination buffer at which copying should start.
from The buffer to copy data from.
fromIndex The position in the source buffer at which copying should start.
count The 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
buffer The buffer to copy data from.
startIndex The buffer index at which copying should start.
contents A pointer to data to copy from the buffer.
length The number of bytes of data to copy.
EmberMessageBuffer emberCopyLinkedBuffers ( EmberMessageBuffer buffer )

Copies a chain of linked buffers.

Parameters
buffer The first buffer in the chain to copy.
Returns
A newly created copy of the buffer chain.
void emberCopyToLinkedBuffers ( 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
contents A pointer to data to copy into the buffer.
buffer The buffer to copy data into.
startIndex The buffer index at which copying should start.
length The 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
contents A pointer to data to place in the allocated buffers.
length The 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
count The 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
buffer The buffer that the requested byte must come from.
index The 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
buffer The buffer containing the 2-byte value.
index The 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
buffer The buffer containing the 4-byte value.
index The 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
buffer The buffer that the requested byte must come from.
index The 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
buffer A 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
buffer The buffer to copy.
isShared A 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
buffer The 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
contents A pointer to data to place in the allocated buffers.
length The 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
buffer A buffer.
void emberSetLinkedBuffersByte ( EmberMessageBuffer buffer,
uint8_t index,
uint8_t byte
)

Sets the indexed byte in a linked list of buffers.

Parameters
buffer The buffer holding the byte to be set.
index The index of the byte to set.
byte The 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
buffer The buffer whose length is to be set.
length The 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
buffer The buffer to set the 2-byte value in.
index The index of the low byte.
value The 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
buffer The buffer to set the 2-byte value in.
index The index of the low byte.
value The 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
buffer A buffer
newLength The length to set the buffer to.