nl::Weave::TLV::TLVReader

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

Provides a memory efficient parser for data encoded in Weave TLV format.

Summary

TLVReader implements a forward-only, “pull-style” parser for Weave TLV data. The TLVReader object operates as a cursor that can be used to iterate over a sequence of TLV elements and interpret their contents. When positioned on an element, applications can make calls to the reader's Get() methods to query the current element’s type and tag, and to extract any associated value. The reader’s Next() method is used to advance from element to element.

A TLVReader object is always positioned either before, on or after a TLV element. When first initialized, a TLVReader is positioned immediately before the first element of the encoding. To begin reading, an application must make an initial call to the Next() method to position the reader on the first element. When a container element is encounteredeither a structure, an array or a paththe OpenContainer() or EnterContainer() methods can be used to iterate through the contents of the container.

When the reader reaches the end of a TLV encoding, or the last element within a container, it signals the application by returning a WEAVE_END_OF_TLV error from the Next() method. The reader will continue to return WEAVE_END_OF_TLV until it is reinitialized, or the current container is exited (via CloseContainer() / ExitContainer()).

A TLVReader object can parse data directly from a fixed input buffer, or from a chain of one or more PacketBuffers. Additionally, applications can supply a GetNextBuffer function to feed data to the reader from an arbitrary source, e.g. a socket or a serial port.

Inheritance

Direct Known Subclasses:
  nl::Weave::Profiles::DataManagement_Current::CircularEventReader
  nl::Weave::TLV::CircularTLVReader

Public types

GetNextBufferFunct)(TLVReader &reader, uintptr_t &bufHandle, const uint8_t *&bufStart, uint32_t &bufLen) WEAVE_ERROR(*
A function that can be used to retrieve additional TLV data to be parsed.

Public attributes

AppData
void *
A pointer field that can be used for application-specific data.
GetNextBuffer
A pointer to a function that will produce input data for the TLVReader object.
ImplicitProfileId
uint32_t
The profile id to be used for profile tags encoded in implicit form.

Protected attributes

mBufEnd
const uint8_t *
mBufHandle
uintptr_t
mContainerType
mControlByte
uint16_t
mElemLenOrVal
uint64_t
mElemTag
uint64_t
mLenRead
uint32_t
mMaxLen
uint32_t
mReadPoint
const uint8_t *

Public functions

CloseContainer(TLVReader & containerReader)
Completes the reading of a TLV container after a call to OpenContainer().
DupBytes(uint8_t *& buf, uint32_t & dataLen)
Allocates and returns a buffer containing the value of the current byte or UTF8 string.
DupString(char *& buf)
Allocates and returns a buffer containing the null-terminated value of the current byte or UTF8 string.
EnterContainer(TLVType & outerContainerType)
Prepares a TLVReader object for reading the members of TLV container element.
ExitContainer(TLVType outerContainerType)
Completes the reading of a TLV container and prepares a TLVReader object to read elements after the container.
Get(bool & v)
Get the value of the current element as a bool type.
Get(int8_t & v)
Get the value of the current element as an 8-bit signed integer.
Get(int16_t & v)
Get the value of the current element as a 16-bit signed integer.
Get(int32_t & v)
Get the value of the current element as a 32-bit signed integer.
Get(int64_t & v)
Get the value of the current element as a 64-bit signed integer.
Get(uint8_t & v)
Get the value of the current element as an 8-bit unsigned integer.
Get(uint16_t & v)
Get the value of the current element as a 16-bit unsigned integer.
Get(uint32_t & v)
Get the value of the current element as a 32-bit unsigned integer.
Get(uint64_t & v)
Get the value of the current element as a 64-bit unsigned integer.
Get(float & v)
Get(double & v)
Get the value of the current element as a double-precision floating point number.
GetBufHandle(void) const
uintptr_t
GetBytes(uint8_t *buf, uint32_t bufSize)
Get the value of the current byte or UTF8 string element.
GetContainerType(void) const
Returns the type of the container within which the TLVReader is currently reading.
GetControlByte(void) const
uint16_t
Returns the control byte associated with current TLV element.
GetDataPtr(const uint8_t *& data)
Get a pointer to the initial encoded byte of a TLV byte or UTF8 string element.
GetLength(void) const
uint32_t
Returns the length of data associated with current TLV element.
GetLengthRead(void) const
uint32_t
Returns the total number of bytes read since the reader was initialized.
GetReadPoint(void) const
const uint8_t *
Gets the point in the underlying input buffer that corresponds to the reader's current position.
GetRemainingLength(void) const
uint32_t
Returns the total number of bytes that can be read until the max read length is reached.
GetString(char *buf, uint32_t bufSize)
Get the value of the current byte or UTF8 string element as a null terminated string.
GetTag(void) const
uint64_t
Returns the tag associated with current TLV element.
GetType(void) const
Returns the type of the current TLV element.
Init(const TLVReader & aReader)
void
Initializes a TLVReader object from another TLVReader object.
Init(const uint8_t *data, uint32_t dataLen)
void
Initializes a TLVReader object to read from a single input buffer.
Init(PacketBuffer *buf, uint32_t maxLen)
void
Initializes a TLVReader object to read from a single PacketBuffer.
Init(PacketBuffer *buf, uint32_t maxLen, bool allowDiscontiguousBuffers)
void
Initializes a TLVReader object to read from a one or more PacketBuffers.
Next(void)
Advances the TLVReader object to the next TLV element to be read.
Next(TLVType expectedType, uint64_t expectedTag)
Advances the TLVReader object to the next TLV element to be read, asserting the type and tag of the new element.
OpenContainer(TLVReader & containerReader)
Initializes a new TLVReader object for reading the members of a TLV container element.
Skip(void)
Advances the TLVReader object to immediately after the current TLV element.
VerifyEndOfContainer(void)
Verifies that the TVLReader object is at the end of a TLV container.

Protected functions

ClearElementState(void)
void
Clear the state of the TLVReader.
ElementType(void) const
TLVElementType
This is a private method that returns the TLVElementType from mControlByte.
EnsureData(WEAVE_ERROR noDataErr)
GetElementHeadLength(uint8_t & elemHeadBytes) const
This is a private method used to compute the length of a TLV element head.
IsContainerOpen(void) const
bool
ReadData(uint8_t *buf, uint32_t len)
ReadElement(void)
ReadTag(TLVTagControl tagControl, const uint8_t *& p)
uint64_t
SetContainerOpen(bool aContainerOpen)
void
SkipData(void)
Skip any data contained in the current TLV by reading over it without a destination buffer.
SkipToEndOfContainer(void)
VerifyElement(void)

Protected static functions

FailGetNextBuffer(TLVReader & reader, uintptr_t & bufHandle, const uint8_t *& bufStart, uint32_t & bufLen)
GetNextPacketBuffer(TLVReader & reader, uintptr_t & bufHandle, const uint8_t *& bufStart, uint32_t & bufLen)

Public types

GetNextBufferFunct

WEAVE_ERROR(* GetNextBufferFunct)(TLVReader &reader, uintptr_t &bufHandle, const uint8_t *&bufStart, uint32_t &bufLen)

A function that can be used to retrieve additional TLV data to be parsed.

Functions of this type are used to feed input data to a TLVReader. When called, the function is expected to produce additional data for the reader to parse or signal the reader that no more data is available.

Details
Parameters
[in] reader
A reference to the TLVReader object that is requesting input data.
[in,out] bufHandle
A reference to a uintptr_t value that the function can use to store context data between calls. This value is initialized to 0 prior to the first call.
[in,out] bufStart
A reference to a data pointer. On entry to the function, bufStart points to one byte beyond the last TLV data byte consumed by the reader. On exit, bufStart is expected to point to the first byte of new TLV data to be parsed. The new pointer value can be within the same buffer as the previously consumed data, or it can point to an entirely new buffer.
[out] bufLen
A reference to an unsigned integer that the function must set to the number of TLV data bytes being returned. If the end of the input TLV data has been reached, the function should set this value to 0.
Return Values
WEAVE_NO_ERROR
If the function successfully produced more TLV data, or the end of the input data was reached (bufLen should be set to 0 in this case).
other
Other Weave or platform-specific error codes indicating that an error occurred preventing the function from producing the requested data.

Public attributes

AppData

void * AppData

A pointer field that can be used for application-specific data.

GetNextBuffer

GetNextBufferFunct GetNextBuffer

A pointer to a function that will produce input data for the TLVReader object.

If set to NULL (the default value), the reader will assume that no further input data is available.

GetNextBuffer can be set by an application at any time, but is typically set when the reader is initialized.

See the GetNextBufferFunct type definition for additional information on implementing a GetNextBuffer function.

ImplicitProfileId

uint32_t ImplicitProfileId

The profile id to be used for profile tags encoded in implicit form.

When the reader encounters a profile-specific tag that has been encoded in implicit form, it uses the value of the ImplicitProfileId property as the assumed profile id for the tag.

By default, the ImplicitProfileId property is set to kProfileIdNotSpecified. When decoding TLV that contains implicitly-encoded tags, applications must set ImplicitProfileId prior to reading any TLV elements having such tags. The appropriate profile id is usually dependent on the context of the application or protocol being spoken.

If an implicitly-encoded tag is encountered while ImplicitProfileId is set to kProfileIdNotSpecified, the reader will return a WEAVE_ERROR_UNKNOWN_IMPLICIT_TLV_TAG error.

Protected attributes

mBufEnd

const uint8_t * mBufEnd

mBufHandle

uintptr_t mBufHandle

mContainerType

TLVType mContainerType

mControlByte

uint16_t mControlByte

mElemLenOrVal

uint64_t mElemLenOrVal

mElemTag

uint64_t mElemTag

mLenRead

uint32_t mLenRead

mMaxLen

uint32_t mMaxLen

mReadPoint

const uint8_t * mReadPoint

Public functions

CloseContainer

WEAVE_ERROR CloseContainer(
  TLVReader & containerReader
)

Completes the reading of a TLV container after a call to OpenContainer().

The CloseContainer() method restores the state of a parent TLVReader object after a call to OpenContainer(). For every call to OpenContainer() applications must make a corresponding call to CloseContainer(), passing a reference to the same container reader to both methods.

When CloseContainer() returns, the parent reader is positioned immediately before the first element that follows the container. From this point an application can use the Next() method to advance through any remaining elements.

Applications can call close CloseContainer() on a parent reader at any point in time, regardless of whether all elements in the underlying container have been read. After CloseContainer() has been called, the application should consider the container reader 'de-initialized' and must not use it further without re-initializing it.

Details
Parameters
[in] containerReader
A reference to the TLVReader object that was supplied to the OpenContainer() method.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_INCORRECT_STATE
If OpenContainer() has not been called on the reader, or if the container reader does not match the one passed to the OpenContainer() method.
WEAVE_ERROR_TLV_UNDERRUN
If the underlying TLV encoding ended prematurely.
WEAVE_ERROR_INVALID_TLV_ELEMENT
If the reader encountered an invalid or unsupported TLV element type.
WEAVE_ERROR_INVALID_TLV_TAG
If the reader encountered a TLV tag in an invalid context.
other
Other Weave or platform error codes returned by the configured GetNextBuffer() function. Only possible when GetNextBuffer is non-NULL.

DupBytes

WEAVE_ERROR DupBytes(
  uint8_t *& buf,
  uint32_t & dataLen
)

Allocates and returns a buffer containing the value of the current byte or UTF8 string.

This method creates a buffer for and returns a copy of the data associated with the byte or UTF-8 string element at the current position. Memory for the buffer is obtained with malloc() and should be freed with free() by the caller when it is no longer needed.

Details
Parameters
[out] buf
A reference to a pointer to which a heap-allocated buffer of dataLen bytes will be assigned on success.
[out] dataLen
A reference to storage for the size, in bytes, of buf on success.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_WRONG_TLV_TYPE
If the current element is not a TLV byte or UTF8 string, or the reader is not positioned on an element.
WEAVE_ERROR_NO_MEMORY
If memory could not be allocated for the output buffer.
WEAVE_ERROR_TLV_UNDERRUN
If the underlying TLV encoding ended prematurely.
WEAVE_ERROR_UNSUPPORTED_WEAVE_FEATURE
If the target platform does not support malloc() and free().
other
Other Weave or platform error codes returned by the configured GetNextBuffer() function. Only possible when GetNextBuffer is non-NULL.

DupString

WEAVE_ERROR DupString(
  char *& buf
)

Allocates and returns a buffer containing the null-terminated value of the current byte or UTF8 string.

This method creates a buffer for and returns a null-terminated copy of the data associated with the byte or UTF-8 string element at the current position. Memory for the buffer is obtained with malloc() and should be freed with free() by the caller when it is no longer needed.

Details
Parameters
[out] buf
A reference to a pointer to which a heap-allocated buffer of will be assigned on success.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_WRONG_TLV_TYPE
If the current element is not a TLV byte or UTF8 string, or the reader is not positioned on an element.
WEAVE_ERROR_NO_MEMORY
If memory could not be allocated for the output buffer.
WEAVE_ERROR_TLV_UNDERRUN
If the underlying TLV encoding ended prematurely.
WEAVE_ERROR_UNSUPPORTED_WEAVE_FEATURE
If the target platform does not support malloc() and free().
other
Other Weave or platform error codes returned by the configured GetNextBuffer() function. Only possible when GetNextBuffer is non-NULL.

EnterContainer

WEAVE_ERROR EnterContainer(
  TLVType & outerContainerType
)

Prepares a TLVReader object for reading the members of TLV container element.

The EnterContainer() method prepares the current TLVReader object to begin reading the member elements of a TLV container (a structure, array or path). For every call to EnterContainer() applications must make a corresponding call to ExitContainer().

When EnterContainer() is called the TLVReader object must be positioned on the container element to be read. The method takes as an argument a reference to a TLVType value which will be used to save the context of the reader while it is reading the container.

When the EnterContainer() method returns, the reader is positioned immediately before the first member of the container. Repeatedly calling Next() will advance the reader through the members of the collection until the end is reached, at which point the reader will return WEAVE_END_OF_TLV.

Once the application has finished reading a container it can continue reading the elements after the container by calling the ExitContainer() method.

Details
Parameters
[out] outerContainerType
A reference to a TLVType value that will receive the context of the reader.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_INCORRECT_STATE
If the current element is not positioned on a container element.

ExitContainer

WEAVE_ERROR ExitContainer(
  TLVType outerContainerType
)

Completes the reading of a TLV container and prepares a TLVReader object to read elements after the container.

The ExitContainer() method restores the state of a TLVReader object after a call to EnterContainer(). For every call to EnterContainer() applications must make a corresponding call to ExitContainer(), passing the context value returned by the EnterContainer() method.

When ExitContainer() returns, the reader is positioned immediately before the first element that follows the container. From this point an application can use the Next() method to advance through any remaining elements.

Once EnterContainer() has been called, applications can call ExitContainer() on a reader at any point in time, regardless of whether all elements in the underlying container have been read.

Details
Parameters
[in] outerContainerType
The TLVType value that was returned by the EnterContainer() method.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_INCORRECT_STATE
If OpenContainer() has not been called on the reader, or if the container reader does not match the one passed to the OpenContainer() method.
WEAVE_ERROR_TLV_UNDERRUN
If the underlying TLV encoding ended prematurely.
WEAVE_ERROR_INVALID_TLV_ELEMENT
If the reader encountered an invalid or unsupported TLV element type.
WEAVE_ERROR_INVALID_TLV_TAG
If the reader encountered a TLV tag in an invalid context.
other
Other Weave or platform error codes returned by the configured GetNextBuffer() function. Only possible when GetNextBuffer is non-NULL.

Get

WEAVE_ERROR Get(
  bool & v
)

Get the value of the current element as a bool type.

Details
Parameters
[out] v
Receives the value associated with current TLV element.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_WRONG_TLV_TYPE
If the current element is not a TLV boolean type, or the reader is not positioned on an element.

Get

WEAVE_ERROR Get(
  int8_t & v
)

Get the value of the current element as an 8-bit signed integer.

If the encoded integer value is larger than the output data type the resultant value will be truncated.

Details
Parameters
[out] v
Receives the value associated with current TLV element.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_WRONG_TLV_TYPE
If the current element is not a TLV integer type (signed or unsigned), or the reader is not positioned on an element.

Get

WEAVE_ERROR Get(
  int16_t & v
)

Get the value of the current element as a 16-bit signed integer.

If the encoded integer value is larger than the output data type the resultant value will be truncated.

Details
Parameters
[out] v
Receives the value associated with current TLV element.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_WRONG_TLV_TYPE
If the current element is not a TLV integer type (signed or unsigned), or the reader is not positioned on an element.

Get

WEAVE_ERROR Get(
  int32_t & v
)

Get the value of the current element as a 32-bit signed integer.

If the encoded integer value is larger than the output data type the resultant value will be truncated.

Details
Parameters
[out] v
Receives the value associated with current TLV element.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_WRONG_TLV_TYPE
If the current element is not a TLV integer type (signed or unsigned), or the reader is not positioned on an element.

Get

WEAVE_ERROR Get(
  int64_t & v
)

Get the value of the current element as a 64-bit signed integer.

If the encoded integer value is larger than the output data type the resultant value will be truncated.

Details
Parameters
[out] v
Receives the value associated with current TLV element.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_WRONG_TLV_TYPE
If the current element is not a TLV integer type (signed or unsigned), or the reader is not positioned on an element.

Get

WEAVE_ERROR Get(
  uint8_t & v
)

Get the value of the current element as an 8-bit unsigned integer.

If the encoded integer value is larger than the output data type the resultant value will be truncated. Similarly, if the encoded integer value is negative, the value will be converted to unsigned.

Details
Parameters
[out] v
Receives the value associated with current TLV element.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_WRONG_TLV_TYPE
If the current element is not a TLV integer type (signed or unsigned), or the reader is not positioned on an element.

Get

WEAVE_ERROR Get(
  uint16_t & v
)

Get the value of the current element as a 16-bit unsigned integer.

If the encoded integer value is larger than the output data type the resultant value will be truncated. Similarly, if the encoded integer value is negative, the value will be converted to unsigned.

Details
Parameters
[out] v
Receives the value associated with current TLV element.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_WRONG_TLV_TYPE
If the current element is not a TLV integer type (signed or unsigned), or the reader is not positioned on an element.

Get

WEAVE_ERROR Get(
  uint32_t & v
)

Get the value of the current element as a 32-bit unsigned integer.

If the encoded integer value is larger than the output data type the resultant value will be truncated. Similarly, if the encoded integer value is negative, the value will be converted to unsigned.

Details
Parameters
[out] v
Receives the value associated with current TLV element.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_WRONG_TLV_TYPE
If the current element is not a TLV integer type (signed or unsigned), or the reader is not positioned on an element.

Get

WEAVE_ERROR Get(
  uint64_t & v
)

Get the value of the current element as a 64-bit unsigned integer.

If the encoded integer value is negative, the value will be converted to unsigned.

Details
Parameters
[out] v
Receives the value associated with current TLV element.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_WRONG_TLV_TYPE
If the current element is not a TLV integer type (signed or unsigned), or the reader is not positioned on an element.

Get

WEAVE_ERROR Get(
  float & v
)

Get

WEAVE_ERROR Get(
  double & v
)

Get the value of the current element as a double-precision floating point number.

Details
Parameters
[out] v
Receives the value associated with current TLV element.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_WRONG_TLV_TYPE
If the current element is not a TLV floating point type, or the reader is not positioned on an element.

GetBufHandle

uintptr_t GetBufHandle(
  void
) const 

GetBytes

WEAVE_ERROR GetBytes(
  uint8_t *buf,
  uint32_t bufSize
)

Get the value of the current byte or UTF8 string element.

To determine the required input buffer size, call the GetLength() method before calling GetBytes().

Details
Parameters
[in] buf
A pointer to a buffer to receive the string data.
[in] bufSize
The size in bytes of the buffer pointed to by buf.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_WRONG_TLV_TYPE
If the current element is not a TLV byte or UTF8 string, or the reader is not positioned on an element.
WEAVE_ERROR_BUFFER_TOO_SMALL
If the supplied buffer is too small to hold the data associated with the current element.
WEAVE_ERROR_TLV_UNDERRUN
If the underlying TLV encoding ended prematurely.
other
Other Weave or platform error codes returned by the configured GetNextBuffer() function. Only possible when GetNextBuffer is non-NULL.

GetContainerType

TLVType GetContainerType(
  void
) const 

Returns the type of the container within which the TLVReader is currently reading.

The GetContainerType() method returns the type of the TLV container within which the TLVReader is reading. If the TLVReader is positioned at the outer-most level of a TLV encoding (i.e. before, on or after the outer-most TLV element), the method will return kTLVType_NotSpecified.

Details
Returns
The TLVType of the current container, or kTLVType_NotSpecified if the TLVReader is not positioned within a container.

GetControlByte

uint16_t GetControlByte(
  void
) const 

Returns the control byte associated with current TLV element.

Ideally, nobody ever needs to know about the control byte and only the internal implementation of TLV should have access to it. But, nevertheless, having access to the control byte is helpful for debugging purposes by the TLVDebugUtilities (that try to decode the tag control byte when pretty printing the TLV buffer contents).

Details
Returns
An unsigned integer containing the control byte associated with the current TLV element. kTLVControlByte_NotSpecified is returned if the reader is not positioned on an element.

GetDataPtr

WEAVE_ERROR GetDataPtr(
  const uint8_t *& data
)

Get a pointer to the initial encoded byte of a TLV byte or UTF8 string element.

This method returns a direct pointer the encoded string value within the underlying input buffer. To succeed, the method requires that the entirety of the string value be present in a single buffer. Otherwise the method returns WEAVE_ERROR_TLV_UNDERRUN. This makes the method of limited use when reading data from multiple discontiguous buffers.

Details
Parameters
[out] data
A reference to a const pointer that will receive a pointer to the underlying string data.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_WRONG_TLV_TYPE
If the current element is not a TLV byte or UTF8 string, or the reader is not positioned on an element.
WEAVE_ERROR_TLV_UNDERRUN
If the underlying TLV encoding ended prematurely or the value of the current string element is not contained within a single contiguous buffer.
other
Other Weave or platform error codes returned by the configured GetNextBuffer() function. Only possible when GetNextBuffer is non-NULL.

GetLength

uint32_t GetLength(
  void
) const 

Returns the length of data associated with current TLV element.

Data length only applies to elements of type UTF8 string or byte string. For UTF8 strings, the value returned is the number of bytes in the string, not the number of characters.

Details
Returns
The length (in bytes) of data associated with the current TLV element, or 0 if the current element is not a UTF8 string or byte string, or if the reader is not positioned on an element.

GetLengthRead

uint32_t GetLengthRead(
  void
) const 

Returns the total number of bytes read since the reader was initialized.

Details
Returns
Total number of bytes read since the reader was initialized.

GetReadPoint

const uint8_t * GetReadPoint(
  void
) const 

Gets the point in the underlying input buffer that corresponds to the reader's current position.

Details
Returns
A pointer into underlying input buffer that corresponds to the reader's current position.

GetRemainingLength

uint32_t GetRemainingLength(
  void
) const 

Returns the total number of bytes that can be read until the max read length is reached.

Details
Returns
Total number of bytes that can be read until the max read length is reached.

GetString

WEAVE_ERROR GetString(
  char *buf,
  uint32_t bufSize
)

Get the value of the current byte or UTF8 string element as a null terminated string.

To determine the required input buffer size, call the GetLength() method before calling GetBytes(). The input buffer should be at least one byte bigger than the string length to accommodate the null character.

Details
Parameters
[in] buf
A pointer to a buffer to receive the byte string data.
[in] bufSize
The size in bytes of the buffer pointed to by buf.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_WRONG_TLV_TYPE
If the current element is not a TLV byte or UTF8 string, or the reader is not positioned on an element.
WEAVE_ERROR_BUFFER_TOO_SMALL
If the supplied buffer is too small to hold the data associated with the current element.
WEAVE_ERROR_TLV_UNDERRUN
If the underlying TLV encoding ended prematurely.
other
Other Weave or platform error codes returned by the configured GetNextBuffer() function. Only possible when GetNextBuffer is non-NULL.

GetTag

uint64_t GetTag(
  void
) const 

Returns the tag associated with current TLV element.

The value returned by GetTag() can be used with the tag utility functions (IsProfileTag(), IsContextTag(), ProfileIdFromTag(), etc.) to determine the type of tag and to extract various tag field values.

Details
Returns
An unsigned integer containing information about the tag associated with the current TLV element.

GetType

TLVType GetType(
  void
) const 

Returns the type of the current TLV element.

Details
Returns
A TLVType value describing the data type of the current TLV element. If the reader is not positioned on a TLV element, the return value will be kTLVType_NotSpecified.

Init

void Init(
  const TLVReader & aReader
)

Initializes a TLVReader object from another TLVReader object.

Details
Parameters
[in] aReader
A read-only reference to the TLVReader to initialize this from.

Init

void Init(
  const uint8_t *data,
  uint32_t dataLen
)

Initializes a TLVReader object to read from a single input buffer.

Details
Parameters
[in] data
A pointer to a buffer containing the TLV data to be parsed.
[in] dataLen
The length of the TLV data to be parsed.

Init

void Init(
  PacketBuffer *buf,
  uint32_t maxLen
)

Initializes a TLVReader object to read from a single PacketBuffer.

Parsing begins at the buffer's start position (buf->DataStart()) and continues until the end of the data in the buffer (as denoted by buf->Datalen()), or maxLen bytes have been parsed.

Details
Parameters
[in] buf
A pointer to an PacketBuffer containing the TLV data to be parsed.
[in] maxLen
The maximum of bytes to parse. Defaults to the amount of data in the input buffer.

Init

void Init(
  PacketBuffer *buf,
  uint32_t maxLen,
  bool allowDiscontiguousBuffers
)

Initializes a TLVReader object to read from a one or more PacketBuffers.

Parsing begins at the initial buffer's start position (buf->DataStart()). If allowDiscontiguousBuffers is true, the reader will advance through the chain of buffers linked by their Next() pointers. Parsing continues until all data in the buffer chain has been consumed (as denoted by buf->Datalen()), or maxLen bytes have been parsed.

Details
Parameters
[in] buf
A pointer to an PacketBuffer containing the TLV data to be parsed.
[in] maxLen
The maximum of bytes to parse. Defaults to the total amount of data in the input buffer chain.
[in] allowDiscontiguousBuffers
If true, advance to the next buffer in the chain once all data in the current buffer has been consumed. If false, stop parsing at the end of the initial buffer.

Next

WEAVE_ERROR Next(
  void
)

Advances the TLVReader object to the next TLV element to be read.

The Next() method positions the reader object on the next element in a TLV encoding that resides in the same containment context. In particular, if the reader is positioned at the outer-most level of a TLV encoding, calling Next() will advance the reader to the next, top-most element. If the reader is positioned within a TLV container element (a structure, array or path), calling Next() will advance the reader to the next member element of the container.

Since Next() constrains reader motion to the current containment context, calling Next() when the reader is positioned on a container element will advance over the container, skipping its member elements (and the members of any nested containers) until it reaches the first element after the container.

When there are no further elements within a particular containment context the Next() method will return a WEAVE_END_OF_TLV error and the position of the reader will remain unchanged.

Details
Return Values
WEAVE_NO_ERROR
If the reader was successfully positioned on a new element.
WEAVE_END_OF_TLV
If no further elements are available.
WEAVE_ERROR_TLV_UNDERRUN
If the underlying TLV encoding ended prematurely.
WEAVE_ERROR_INVALID_TLV_ELEMENT
If the reader encountered an invalid or unsupported TLV element type.
WEAVE_ERROR_INVALID_TLV_TAG
If the reader encountered a TLV tag in an invalid context.
WEAVE_ERROR_UNKNOWN_IMPLICIT_TLV_TAG
If the reader encountered a implicitly-encoded TLV tag for which the corresponding profile id is unknown.
other
Other Weave or platform error codes returned by the configured GetNextBuffer() function. Only possible when GetNextBuffer is non-NULL.

Next

WEAVE_ERROR Next(
  TLVType expectedType,
  uint64_t expectedTag
)

Advances the TLVReader object to the next TLV element to be read, asserting the type and tag of the new element.

The Next(TLVType expectedType, uint64_t expectedTag) method is a convenience method that has the same behavior as Next(), but also verifies that the type and tag of the new TLV element match the supplied arguments.

Details
Parameters
[in] expectedType
The expected data type for the next element.
[in] expectedTag
The expected tag for the next element.
Return Values
WEAVE_NO_ERROR
If the reader was successfully positioned on a new element.
WEAVE_END_OF_TLV
If no further elements are available.
WEAVE_ERROR_WRONG_TLV_TYPE
If the type of the new element does not match the value of the expectedType argument.
WEAVE_ERROR_UNEXPECTED_TLV_ELEMENT
If the tag associated with the new element does not match the value of the expectedTag argument.
WEAVE_ERROR_TLV_UNDERRUN
If the underlying TLV encoding ended prematurely.
WEAVE_ERROR_INVALID_TLV_ELEMENT
If the reader encountered an invalid or unsupported TLV element type.
WEAVE_ERROR_INVALID_TLV_TAG
If the reader encountered a TLV tag in an invalid context.
other
Other Weave or platform error codes returned by the configured GetNextBuffer() function. Only possible when GetNextBuffer is non-NULL.

OpenContainer

WEAVE_ERROR OpenContainer(
  TLVReader & containerReader
)

Initializes a new TLVReader object for reading the members of a TLV container element.

The OpenContainer() method initializes a new TLVReader object for reading the member elements of a TLV container (a structure, array or path). When OpenContainer() is called, the current TLVReader object must be positioned on the container element to be read. The method takes as its sole argument a reference to a new reader that will be initialized to read the container. This reader is known as the container reader while the reader on which OpenContainer() is called is known as the parent reader.

When the OpenContainer() method returns, the container reader is positioned immediately before the first member of the container. Calling Next() on the container reader will advance through the members of the collection until the end is reached, at which point the reader will return WEAVE_END_OF_TLV.

While the container reader is open, applications must not make calls on or otherwise alter the state of the parent reader. Once an application has finished using the container reader it must close it by calling CloseContainer() on the parent reader, passing the container reader as an argument. Applications may close the container reader at any point, with or without reading all elements contained in the underlying container. After the container reader is closed, applications may continue their use of the parent reader.

The container reader inherits various configuration properties from the parent reader. These are:

  • The implicit profile id (ImplicitProfileId)
  • The application data pointer (AppData)
  • The GetNextBuffer function pointer

Details
Parameters
[out] containerReader
A reference to a TLVReader object that will be initialized for reading the members of the current container element. Any data associated with the supplied object is overwritten.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_INCORRECT_STATE
If the current element is not positioned on a container element.

Skip

WEAVE_ERROR Skip(
  void
)

Advances the TLVReader object to immediately after the current TLV element.

The Skip() method positions the reader object immediately after the current TLV element, such that a subsequent call to Next() will advance the reader to the following element. Like Next(), if the reader is positioned on a container element at the time of the call, the members of the container will be skipped. If the reader is not positioned on any element, its position remains unchanged.

Details
Return Values
WEAVE_NO_ERROR
If the reader was successfully positioned on a new element.
WEAVE_END_OF_TLV
If no further elements are available.
WEAVE_ERROR_TLV_UNDERRUN
If the underlying TLV encoding ended prematurely.
WEAVE_ERROR_INVALID_TLV_ELEMENT
If the reader encountered an invalid or unsupported TLV element type.
WEAVE_ERROR_INVALID_TLV_TAG
If the reader encountered a TLV tag in an invalid context.
other
Other Weave or platform error codes returned by the configured GetNextBuffer() function. Only possible when GetNextBuffer is non-NULL.

VerifyEndOfContainer

WEAVE_ERROR VerifyEndOfContainer(
  void
)

Verifies that the TVLReader object is at the end of a TLV container.

The VerifyEndOfContainer() method verifies that there are no further TLV elements to be read within the current TLV container. This is a convenience method that is equivalent to calling Next() and checking for a return value of WEAVE_END_OF_TLV.

Details
Return Values
WEAVE_NO_ERROR
If there are no further TLV elements to be read.
WEAVE_ERROR_UNEXPECTED_TLV_ELEMENT
If another TLV element was found in the collection.
WEAVE_ERROR_TLV_UNDERRUN
If the underlying TLV encoding ended prematurely.
WEAVE_ERROR_INVALID_TLV_ELEMENT
If the reader encountered an invalid or unsupported TLV element type.
WEAVE_ERROR_INVALID_TLV_TAG
If the reader encountered a TLV tag in an invalid context.
other
Other Weave or platform error codes returned by the configured GetNextBuffer() function. Only possible when GetNextBuffer is non-NULL.

Protected functions

ClearElementState

void ClearElementState(
  void
)

Clear the state of the TLVReader.

This method is used to position the reader before the first TLV, between TLVs or after the last TLV.

ElementType

TLVElementType ElementType(
  void
) const 

This is a private method that returns the TLVElementType from mControlByte.

EnsureData

WEAVE_ERROR EnsureData(
  WEAVE_ERROR noDataErr
)

GetElementHeadLength

WEAVE_ERROR GetElementHeadLength(
  uint8_t & elemHeadBytes
) const 

This is a private method used to compute the length of a TLV element head.

IsContainerOpen

bool IsContainerOpen(
  void
) const 

ReadData

WEAVE_ERROR ReadData(
  uint8_t *buf,
  uint32_t len
)

ReadElement

WEAVE_ERROR ReadElement(
  void
)

ReadTag

uint64_t ReadTag(
  TLVTagControl tagControl,
  const uint8_t *& p
)

SetContainerOpen

void SetContainerOpen(
  bool aContainerOpen
)

SkipData

WEAVE_ERROR SkipData(
  void
)

Skip any data contained in the current TLV by reading over it without a destination buffer.

Details
Return Values
WEAVE_NO_ERROR
If the reader was successfully positioned at the end of the data.
other
Other Weave or platform error codes returned by the configured GetNextBuffer() function. Only possible when GetNextBuffer is non-NULL.

SkipToEndOfContainer

WEAVE_ERROR SkipToEndOfContainer(
  void
)

VerifyElement

WEAVE_ERROR VerifyElement(
  void
)

Protected static functions

FailGetNextBuffer

WEAVE_ERROR FailGetNextBuffer(
  TLVReader & reader,
  uintptr_t & bufHandle,
  const uint8_t *& bufStart,
  uint32_t & bufLen
)

GetNextPacketBuffer

WEAVE_ERROR GetNextPacketBuffer(
  TLVReader & reader,
  uintptr_t & bufHandle,
  const uint8_t *& bufStart,
  uint32_t & bufLen
)