Ring Buffer#

API and Callbacks for the Ring Buffer Component.

This component manages a ring buffer of binary entries. Each entry has a 1- or 2-byte length field that is recorded to manage the buffer. This ring buffer can be used by multiple entities as the buffer space for the ring buffer is allocated by the caller.

Modules#

EmberRingBuffer

API#

EmberStatus
emberAfPluginRingBufferInitStruct(EmberRingBuffer *ringBufferStruct, bool wideLengthField, EmberAfPluginRingBufferDeleteFunction *deleteCallback, uint8_t *dataPtr)

Initialize the ring buffer struct based on data passed. widLengthField determines whether the ring buffer uses 1 or 2 byte length fields for entry. wideLengthField = false uses 1 byte length, wideLengthField = true uses 2 byte lengths. All entries in the same ring buffer utilze the same size length field. Different ring buffers may use differnt sizes.

EmberStatus
emberAfPluginRingBufferAddEntry(EmberRingBuffer *ring, uint8_t *dataToAdd, uint16_t dataToAddSize)

Add an entry in the ring buffer.

EmberStatus
emberAfPluginRingBufferGetEntryByEntryNumber(EmberRingBuffer *ring, uint16_t entryNumber, uint16_t dataIndexInEntry, uint16_t *returnEntryTotalSize, uint16_t maxReturnSize, uint16_t *returnDataSize, uint8_t *returnData)

Retrieve data from the specified entry. Returns the entry's total size in value pointed to by returnEntryTotalSize. The amount of data returned is written to the pointer returnDataSize. This allows for the caller to get the entry's total size at the same time they are able to grab a chunk of the entry up to some limit.

EmberStatus
emberAfPluginRingBufferGetLastEntry(EmberRingBuffer *ring, uint16_t dataIndexInEntry, uint16_t *returnEntryTotalSize, uint16_t maxReturnSize, uint16_t *returnDataSize, uint8_t *returnData)

Get the last entry of the ring buffer.

EmberStatus

Initialize the iterator to the first entry in the ring buffer. You may immediately call emberAfPluginRingBufferGetEntryByIterator() after this function is called.

EmberStatus

Iterate to next entry in ring buffer.

EmberStatus
emberAfPluginRingBufferGetEntryByIterator(EmberRingBuffer *ring, uint16_t dataIndexInEntry, uint16_t *returnEntryTotalSize, uint16_t maxReturnSize, uint16_t *returnDataSize, uint8_t *returnData)
EmberStatus
emberAfPluginRingBufferUpdateEntryByIterator(EmberRingBuffer *ring, uint16_t dataIndexInEntry, uint8_t *updatedData, uint16_t updatedDataLength)

Update a ring buffer entry by passing in the iterator.

EmberStatus
emberAfPluginRingBufferAppendLastEntry(EmberRingBuffer *ring, uint8_t *dataToAdd, uint16_t dataToAddSize)

Append an entry to end of the ring buffer.

Typedefs#

typedef void()
EmberAfPluginRingBufferDeleteFunction(uint16_t entryNumber, uint16_t entrySize)

API Documentation#

emberAfPluginRingBufferInitStruct#

EmberStatus emberAfPluginRingBufferInitStruct (EmberRingBuffer * ringBufferStruct, bool wideLengthField, EmberAfPluginRingBufferDeleteFunction * deleteCallback, uint8_t * dataPtr)

Initialize the ring buffer struct based on data passed. widLengthField determines whether the ring buffer uses 1 or 2 byte length fields for entry. wideLengthField = false uses 1 byte length, wideLengthField = true uses 2 byte lengths. All entries in the same ring buffer utilze the same size length field. Different ring buffers may use differnt sizes.

Parameters
N/AringBufferStruct

Ver.: always

N/AwideLengthField

Ver.: always

N/AdeleteCallback

Ver.: always

N/AdataPtr

Ver.: always

Returns

  • EmberStatus status code


Definition at line 82 of file app/framework/plugin/ring-buffer/ring-buffer.h

emberAfPluginRingBufferAddEntry#

EmberStatus emberAfPluginRingBufferAddEntry (EmberRingBuffer * ring, uint8_t * dataToAdd, uint16_t dataToAddSize)

Add an entry in the ring buffer.

Parameters
N/Aring

Ver.: always

N/AdataToAdd

Ver.: always

N/AdataToAddSize

Ver.: always

Returns

  • EmberStatus status code


Definition at line 96 of file app/framework/plugin/ring-buffer/ring-buffer.h

emberAfPluginRingBufferGetEntryByEntryNumber#

EmberStatus emberAfPluginRingBufferGetEntryByEntryNumber (EmberRingBuffer * ring, uint16_t entryNumber, uint16_t dataIndexInEntry, uint16_t * returnEntryTotalSize, uint16_t maxReturnSize, uint16_t * returnDataSize, uint8_t * returnData)

Retrieve data from the specified entry. Returns the entry's total size in value pointed to by returnEntryTotalSize. The amount of data returned is written to the pointer returnDataSize. This allows for the caller to get the entry's total size at the same time they are able to grab a chunk of the entry up to some limit.

Parameters
N/Aring

numbering starts from 0

N/AentryNumber

may be set to NULL, in which case no return data is written.

N/AdataIndexInEntry

does not include the entry's length overhead, which the caller shouldn't care about anyway.

N/AreturnEntryTotalSize
N/AmaxReturnSize
N/AreturnDataSize
N/AreturnData

Returns

  • EmberStatus status code


Definition at line 115 of file app/framework/plugin/ring-buffer/ring-buffer.h

emberAfPluginRingBufferGetLastEntry#

EmberStatus emberAfPluginRingBufferGetLastEntry (EmberRingBuffer * ring, uint16_t dataIndexInEntry, uint16_t * returnEntryTotalSize, uint16_t maxReturnSize, uint16_t * returnDataSize, uint8_t * returnData)

Get the last entry of the ring buffer.

Parameters
N/Aring

Ver.: always

N/AdataIndexInEntry

Ver.: always

N/AreturnEntryTotalSize

Ver.: always

N/AmaxReturnSize

Ver.: always

N/AreturnDataSize

Ver.: always

N/AreturnData

Ver.: always

Returns

  • EmberStatus status code


Definition at line 134 of file app/framework/plugin/ring-buffer/ring-buffer.h

emberAfPluginRingBufferInitIterator#

EmberStatus emberAfPluginRingBufferInitIterator (EmberRingBuffer * ring)

Initialize the iterator to the first entry in the ring buffer. You may immediately call emberAfPluginRingBufferGetEntryByIterator() after this function is called.

Parameters
N/Aring

Ver.: always

Returns

  • EmberStatus status code


Definition at line 150 of file app/framework/plugin/ring-buffer/ring-buffer.h

emberAfPluginRingBufferIteratorNextEntry#

EmberStatus emberAfPluginRingBufferIteratorNextEntry (EmberRingBuffer * ring)

Iterate to next entry in ring buffer.

Parameters
N/Aring

Ver.: always

Returns

  • EmberStatus status code

Note

  • Return EMBER_OPERATION_IN_PROGRESS if there are more items left to iterate through. Returns EMBER_SUCCESS on reaching the last item, and the iterator is marked invalid (needs to be initialized again). Returns EMBER_INVALID_CALL if the iterator has not been initialized. An iterator can also be marked invalid if the ring buffer has deleted the entry that the iterator was currently on.


Definition at line 166 of file app/framework/plugin/ring-buffer/ring-buffer.h

emberAfPluginRingBufferGetEntryByIterator#

EmberStatus emberAfPluginRingBufferGetEntryByIterator (EmberRingBuffer * ring, uint16_t dataIndexInEntry, uint16_t * returnEntryTotalSize, uint16_t maxReturnSize, uint16_t * returnDataSize, uint8_t * returnData)

Similar to emberAfPluginRingBufferGetEntryByEntryNumber().

Parameters
N/Aring

Ver.: always

N/AdataIndexInEntry

Ver.: always

N/AreturnEntryTotalSize

Ver.: always

N/AmaxReturnSize

Ver.: always

N/AreturnDataSize

Ver.: always

N/AreturnData

Ver.: always

Returns

  • EmberStatus status code

Note

  • The iterator must have already been initialized


Definition at line 182 of file app/framework/plugin/ring-buffer/ring-buffer.h

emberAfPluginRingBufferUpdateEntryByIterator#

EmberStatus emberAfPluginRingBufferUpdateEntryByIterator (EmberRingBuffer * ring, uint16_t dataIndexInEntry, uint8_t * updatedData, uint16_t updatedDataLength)

Update a ring buffer entry by passing in the iterator.

Parameters
N/Aring

Ver.: always

N/AdataIndexInEntry

Ver.: always

N/AupdatedData

Ver.: always

N/AupdatedDataLength

Ver.: always

Returns

  • EmberStatus status code


Definition at line 199 of file app/framework/plugin/ring-buffer/ring-buffer.h

emberAfPluginRingBufferAppendLastEntry#

EmberStatus emberAfPluginRingBufferAppendLastEntry (EmberRingBuffer * ring, uint8_t * dataToAdd, uint16_t dataToAddSize)

Append an entry to end of the ring buffer.

Parameters
N/Aring

Ver.: always

N/AdataToAdd

Ver.: always

N/AdataToAddSize

Ver.: always

Returns

  • EmberStatus status code


Definition at line 213 of file app/framework/plugin/ring-buffer/ring-buffer.h

Typedef Documentation#

EmberAfPluginRingBufferDeleteFunction#

typedef void() EmberAfPluginRingBufferDeleteFunction(uint16_t entryNumber, uint16_t entrySize) (uint16_t entryNumber, uint16_t entrySize)

Definition at line 41 of file app/framework/plugin/ring-buffer/ring-buffer.h

Macro Definition Documentation#

EMBER_AF_PLUGIN_RING_BUFFER_WIDE_LENGTH_ENTRY_OVERHEAD#

#define EMBER_AF_PLUGIN_RING_BUFFER_WIDE_LENGTH_ENTRY_OVERHEAD
Value:
2

Definition at line 35 of file app/framework/plugin/ring-buffer/ring-buffer.h

EMBER_AF_PLUGIN_RING_BUFFER_NARROW_LENGTH_ENTRY_OVERHEAD#

#define EMBER_AF_PLUGIN_RING_BUFFER_NARROW_LENGTH_ENTRY_OVERHEAD
Value:
1

Definition at line 36 of file app/framework/plugin/ring-buffer/ring-buffer.h

EMBER_AF_PLUGIN_RING_BUFFER_MAX_LENGTH_ENTRY_OVERHEAD#

#define EMBER_AF_PLUGIN_RING_BUFFER_MAX_LENGTH_ENTRY_OVERHEAD
Value:
EMBER_AF_PLUGIN_RING_BUFFER_WIDE_LENGTH_ENTRY_OVERHEAD

Definition at line 38 of file app/framework/plugin/ring-buffer/ring-buffer.h