nl::Weave::TLV::WeaveCircularTLVBuffer

#include <src/lib/core/WeaveCircularTLVBuffer.h>

WeaveCircularTLVBuffer provides circular storage for the nl::Weave::TLV::TLVWriter and nl::Weave::TLVTLVReader.

Summary

nl::Weave::TLV::TLVWriter is able to write an unbounded number of TLV entries to the WeaveCircularTLVBuffer as long as each individual TLV entry fits entirely within the provided storage. The nl::Weave::TLV::TLVReader will read at most the size of the buffer, but will accommodate the wraparound within the buffer.

Constructors and Destructors
WeaveCircularTLVBuffer(uint8_t *inBuffer, size_t inBufferLength)
WeaveCircularTLVBuffer(uint8_t *inBuffer, size_t inBufferLength, uint8_t *inHead)

Public types
ProcessEvictedElementFunct)(WeaveCircularTLVBuffer &inBuffer, void *inAppData, TLVReader &inReader) WEAVE_ERROR(*
A function that is called to process a TLV element prior to it being evicted from the nl::Weave::TLV::WeaveCircularTLVBuffer.

Public attributes
mAppData
void *
An optional, user supplied context to be used with the callback processing the evicted element.
mImplicitProfileId
uint32_t
mProcessEvictedElement
An optional, user-supplied callback that processes the element prior to evicting it from the circular buffer.

Public functions
AvailableDataLength(void) const
size_t
DataLength(void) const
size_t
EvictHead(void)
Evicts the oldest top-level TLV element in the WeaveCircularTLVBuffer.
FinalizeBuffer(TLVWriter & ioWriter, uint8_t *inBufStart, uint32_t inBufLen)
FinalizeBuffer adjust the WeaveCircularTLVBuffer state on completion of output from the TLVWriter.
GetNewBuffer(TLVWriter & ioWriter, uint8_t *& outBufStart, uint32_t & outBufLen)
Get additional space for the TLVWriter.
GetNextBuffer(TLVReader & ioReader, const uint8_t *& outBufStart, uint32_t & outBufLen)
Get additional space for the TLVReader.
GetQueue(void) const
uint8_t *
GetQueueSize(void) const
size_t
QueueHead(void) const
uint8_t *
QueueTail(void) const
uint8_t *
SetQueueHead(uint8_t *aQueueHead)
void
SetQueueLength(size_t aQueueLength)
void

Public static functions
FinalizeBufferFunct(TLVWriter & ioWriter, uintptr_t inBufHandle, uint8_t *inBufStart, uint32_t inBufLen)
GetNewBufferFunct(TLVWriter & ioWriter, uintptr_t & inBufHandle, uint8_t *& outBufStart, uint32_t & outBufLen)
A trampoline to fetch more space for the TLVWriter.
GetNextBufferFunct(TLVReader & ioReader, uintptr_t & inBufHandle, const uint8_t *& outBufStart, uint32_t & outBufLen)

Public types

ProcessEvictedElementFunct

WEAVE_ERROR(* ProcessEvictedElementFunct)(WeaveCircularTLVBuffer &inBuffer, void *inAppData, TLVReader &inReader)

A function that is called to process a TLV element prior to it being evicted from the nl::Weave::TLV::WeaveCircularTLVBuffer.

Functions of this type are used to process a TLV element about to be evicted from the buffer. The function will be given a nl::Weave::TLV::TLVReader positioned on the element about to be deleted, as well as void * context where the user may have provided additional environment for the callback. If the function processed the element successfully, it must return WEAVE_NO_ERROR ; this signifies to the WeaveCircularTLVBuffer that the element may be safely evicted. Any other return value is treated as an error and will prevent the WeaveCircularTLVBuffer from evicting the element under consideration.

Note: This callback may be used to force WeaveCircularTLVBuffer to not evict the element. This may be useful in a number of circumstances, when it is desired to have an underlying circular buffer, but not to override any elements within it.

Details
Parameters
[in] inBuffer
A reference to the buffer from which the eviction takes place
[in] inAppData
A pointer to the user-provided structure containing additional context for this callback
[in] inReader
A TLVReader positioned at the element to be evicted.
Return Values
WEAVE_NO_ERROR
On success. Element will be evicted.
other
An error has occurred during the event processing. The element stays in the buffer. The write function that triggered this element eviction will fail.

Public attributes

mAppData

void * mAppData

An optional, user supplied context to be used with the callback processing the evicted element.

mImplicitProfileId

uint32_t mImplicitProfileId

mProcessEvictedElement

ProcessEvictedElementFunct mProcessEvictedElement

An optional, user-supplied callback that processes the element prior to evicting it from the circular buffer.

See the ProcessEvictedElementFunct type definition on additional information on implementing the mProcessEvictedElement function.

Public functions

AvailableDataLength

size_t AvailableDataLength(
  void
) const

DataLength

size_t DataLength(
  void
) const

EvictHead

WEAVE_ERROR EvictHead(
  void
)

Evicts the oldest top-level TLV element in the WeaveCircularTLVBuffer.

This function removes the oldest top level TLV element in the buffer. The function will call the callback registered at mProcessEvictedElement to process the element prior to removal. If the callback returns anything but WEAVE_NO_ERROR, the element is not removed. Similarly, if any other error occurs no elements within the buffer, etc the underlying WeaveCircularTLVBuffer remains unchanged.

Details
Return Values
WEAVE_NO_ERROR
On success.
other
On any other error returned either by the callback or by the TLVReader.

FinalizeBuffer

WEAVE_ERROR FinalizeBuffer(
  TLVWriter & ioWriter,
  uint8_t *inBufStart,
  uint32_t inBufLen
)

FinalizeBuffer adjust the WeaveCircularTLVBuffer state on completion of output from the TLVWriter.

This function affects the position of the queue tail.

Details
Parameters
[in,out] ioWriter
TLVWriter calling this function
[in] inBufStart
pointer to the start of data (from TLVWriter perspective)
[in] inBufLen
length of data in the buffer pointed to by inbufStart
Return Values
WEAVE_NO_ERROR
Unconditionally.

GetNewBuffer

WEAVE_ERROR GetNewBuffer(
  TLVWriter & ioWriter,
  uint8_t *& outBufStart,
  uint32_t & outBufLen
)

Get additional space for the TLVWriter.

In actuality, the function evicts an element from the circular buffer, and adjusts the head of this buffer queue

Details
Parameters
[in,out] ioWriter
TLVWriter calling this function
[out] outBufStart
The pointer to the new buffer
[out] outBufLen
The available length for writing
Return Values
WEAVE_NO_ERROR
On success.
other
If the function was unable to elide a complete top-level TLV element.

GetNextBuffer

WEAVE_ERROR GetNextBuffer(
  TLVReader & ioReader,
  const uint8_t *& outBufStart,
  uint32_t & outBufLen
)

Get additional space for the TLVReader.

The storage provided by the WeaveCircularTLVBuffer may be wraparound within the buffer. This function provides us with an ability to match the buffering of the circular buffer to the TLVReader constraints. The reader will read at most mQueueSize bytes from the buffer.

Details
Parameters
[in] ioReader
TLVReader calling this function.
[in,out] outBufStart
The reference to the data buffer. On return, it is set to a value within this buffer.
[out] outBufLen
On return, set to the number of continuous bytes that could be read out of the buffer.
Return Values
WEAVE_NO_ERROR
Succeeds unconditionally.

GetQueue

uint8_t * GetQueue(
  void
) const

GetQueueSize

size_t GetQueueSize(
  void
) const

QueueHead

uint8_t * QueueHead(
  void
) const

QueueTail

uint8_t * QueueTail(
  void
) const

SetQueueHead

void SetQueueHead(
  uint8_t *aQueueHead
)

SetQueueLength

void SetQueueLength(
  size_t aQueueLength
)

WeaveCircularTLVBuffer

 WeaveCircularTLVBuffer(
  uint8_t *inBuffer,
  size_t inBufferLength
)

WeaveCircularTLVBuffer constructor.

Details
Parameters
[in] inBuffer
A pointer to the backing store for the queue
[in] inBufferLength
Length, in bytes, of the backing store

WeaveCircularTLVBuffer

 WeaveCircularTLVBuffer(
  uint8_t *inBuffer,
  size_t inBufferLength,
  uint8_t *inHead
)

WeaveCircularTLVBuffer constructor.

Details
Parameters
[in] inBuffer
A pointer to the backing store for the queue
[in] inBufferLength
Length, in bytes, of the backing store
[in] inHead
Initial point for the head. The inHead pointer is must fall within the backing store for the circular buffer, i.e. within inBuffer and &(inBuffer[inBufferLength])

Public static functions

FinalizeBufferFunct

WEAVE_ERROR FinalizeBufferFunct(
  TLVWriter & ioWriter,
  uintptr_t inBufHandle,
  uint8_t *inBufStart,
  uint32_t inBufLen
)

A trampoline to WeaveCircularTLVBuffer::FinalizeBuffer.

Details
Parameters
[in,out] ioWriter
TLVWriter calling this function
[in,out] inBufHandle
A handle to the CircularTLVWriter object
[in] inBufStart
pointer to the start of data (from TLVWriter perspective)
[in] inBufLen
length of data in the buffer pointed to by inbufStart
Return Values
WEAVE_NO_ERROR
Unconditionally.

GetNewBufferFunct

WEAVE_ERROR GetNewBufferFunct(
  TLVWriter & ioWriter,
  uintptr_t & inBufHandle,
  uint8_t *& outBufStart,
  uint32_t & outBufLen
)

A trampoline to fetch more space for the TLVWriter.

Details
Parameters
[in,out] ioWriter
TLVWriter calling this function
[in,out] inBufHandle
A handle to the CircularTLVWriter object
[out] outBufStart
The pointer to the new buffer
[out] outBufLen
The available length for writing
Return Values
WEAVE_NO_ERROR
On success.
other
If the function was unable to elide a complete top-level TLV element.

GetNextBufferFunct

WEAVE_ERROR GetNextBufferFunct(
  TLVReader & ioReader,
  uintptr_t & inBufHandle,
  const uint8_t *& outBufStart,
  uint32_t & outBufLen
)

A trampoline to WeaveCircularTLVBuffer::GetNextBuffer.

Details
Parameters
[in,out] ioReader
TLVReader calling this function
[in,out] inBufHandle
A handle to the CircularTLVWriter object
[in,out] outBufStart
The reference to the data buffer. On return, it is set to a value within this buffer.
[out] outBufLen
On return, set to the number of continuous bytes that could be read out of the buffer.
Return Values
WEAVE_NO_ERROR
Succeeds unconditionally.