nl::Weave::TLV::TLVWriter

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

Provides a memory efficient encoder for writing data in Weave TLV format.

Summary

TLVWriter implements a forward-only, stream-style encoder for Weave TLV data. Applications write data to an encoding by calling one of the writer's Put() methods, passing associated tag and value information as necessary. Similarly applications can encode TLV container types (structures, arrays or paths) by calling the writer's OpenContainer() or EnterContainer() methods.

A TLVWriter object can write data directly to a fixed output buffer, or to a chain of one or more PacketBuffer objects. Additionally, applications can supply their own GetNewBuffer and FinalizeBuffer functions to direct output to an arbitrary destination, e.g. a socket or an event queue.

Inheritance

Direct Known Subclasses: nl::Weave::TLV::CircularTLVWriter

Protected types

@60{
  kEndOfContainerMarkerSize = 1
}
enum

Public types

FinalizeBufferFunct)(TLVWriter &writer, uintptr_t bufHandle, uint8_t *bufStart, uint32_t bufLen) WEAVE_ERROR(*
A function used to perform finalization of the output from a TLVWriter object.
GetNewBufferFunct)(TLVWriter &writer, uintptr_t &bufHandle, uint8_t *&bufStart, uint32_t &bufLen) WEAVE_ERROR(*
A function that supplies new output buffer space to a TLVWriter.

Public attributes

AppData
void *
A pointer field that can be used for application-specific data.
FinalizeBuffer
A pointer to a function that will be called when the TLVWriter is finalized.
GetNewBuffer
A pointer to a function that will supply new output buffer space to a TLVWriter.
ImplicitProfileId
uint32_t
The profile id of tags that should be encoded in implicit form.

Protected attributes

mBufHandle
uintptr_t
mBufStart
uint8_t *
mContainerType
mLenWritten
uint32_t
mMaxLen
uint32_t
mRemainingLen
uint32_t
mWritePoint
uint8_t *

Public functions

CloseContainer(TLVWriter & containerWriter)
Completes the writing of a TLV container after a call to OpenContainer().
CopyContainer(TLVReader & container)
Copies a TLV container element from TLVReader object.
CopyContainer(uint64_t tag, TLVReader & container)
Encodes a TLV container element from a pre-encoded set of member elements.
CopyElement(TLVReader & reader)
Copies a TLV element from a reader object into the writer.
CopyElement(uint64_t tag, TLVReader & reader)
EndContainer(TLVType outerContainerType)
Completes the encoding of a TLV container element.
Finalize(void)
Finish the writing of a TLV encoding.
GetContainerType(void) const
Returns the type of container within which the TLVWriter is currently writing.
GetLengthWritten(void)
uint32_t
Returns the total number of bytes written since the writer was initialized.
Init(uint8_t *buf, uint32_t maxLen)
void
Initializes a TLVWriter object to write into a single output buffer.
Init(PacketBuffer *buf, uint32_t maxLen)
void
Initializes a TLVWriter object to write into a single PacketBuffer.
Init(PacketBuffer *buf, uint32_t maxLen, bool allowDiscontiguousBuffers)
void
Initializes a TLVWriter object to write into one or more PacketBuffers.
OpenContainer(uint64_t tag, TLVType containerType, TLVWriter & containerWriter)
Initializes a new TLVWriter object for writing the members of a TLV container element.
Put(uint64_t tag, int8_t v)
Encodes a TLV signed integer value.
Put(uint64_t tag, int8_t v, bool preserveSize)
Encodes a TLV signed integer value.
Put(uint64_t tag, int16_t v)
Put(uint64_t tag, int16_t v, bool preserveSize)
Put(uint64_t tag, int32_t v)
Put(uint64_t tag, int32_t v, bool preserveSize)
Put(uint64_t tag, int64_t v)
Put(uint64_t tag, int64_t v, bool preserveSize)
Put(uint64_t tag, uint8_t v)
Encodes a TLV unsigned integer value.
Put(uint64_t tag, uint8_t v, bool preserveSize)
Encodes a TLV unsigned integer value.
Put(uint64_t tag, uint16_t v)
Put(uint64_t tag, uint16_t v, bool preserveSize)
Put(uint64_t tag, uint32_t v)
Put(uint64_t tag, uint32_t v, bool preserveSize)
Put(uint64_t tag, uint64_t v)
Put(uint64_t tag, uint64_t v, bool preserveSize)
Put(uint64_t tag, float v)
Put(uint64_t tag, double v)
Encodes a TLV floating point value.
PutBoolean(uint64_t tag, bool v)
Encodes a TLV boolean value.
PutBytes(uint64_t tag, const uint8_t *buf, uint32_t len)
Encodes a TLV byte string value.
PutNull(uint64_t tag)
Encodes a TLV null value.
PutPreEncodedContainer(uint64_t tag, TLVType containerType, const uint8_t *data, uint32_t dataLen)
Encodes a TLV container element from a pre-encoded set of member elements.
PutString(uint64_t tag, const char *buf)
Encodes a TLV UTF8 string value.
PutString(uint64_t tag, const char *buf, uint32_t len)
Encodes a TLV UTF8 string value.
PutStringF(uint64_t tag, const char *fmt, ...)
Encode the string output formatted according to the format in the TLV element.
StartContainer(uint64_t tag, TLVType containerType, TLVType & outerContainerType)
Begins encoding a new TLV container element.
VPutStringF(uint64_t tag, const char *fmt, va_list ap)
Encode the string output formatted according to the format in the TLV element.

Public static functions

FinalizePacketBuffer(TLVWriter & writer, uintptr_t bufHandle, uint8_t *bufStart, uint32_t dataLen)
An implementation of a TLVWriter FinalizeBuffer function for writing to a chain of PacketBuffers.
GetNewPacketBuffer(TLVWriter & writer, uintptr_t & bufHandle, uint8_t *& bufStart, uint32_t & bufLen)
An implementation of a TLVWriter GetNewBuffer function for writing to a chain of PacketBuffers.

Protected functions

IsCloseContainerReserved(void) const
bool
Determine whether the container should reserve space for the CloseContainer symbol at the point of starting / opening the container.
IsContainerOpen(void) const
bool
SetCloseContainerReserved(bool aCloseContainerReserved)
void
Set whether the container should reserve the space for the CloseContainer symbol at the point of starting / opening the container.
SetContainerOpen(bool aContainerOpen)
void
WriteData(const uint8_t *p, uint32_t len)
WriteElementHead(TLVElementType elemType, uint64_t tag, uint64_t lenOrVal)
WriteElementWithData(TLVType type, uint64_t tag, const uint8_t *data, uint32_t dataLen)

Protected types

@60

 @60

Public types

FinalizeBufferFunct

WEAVE_ERROR(* FinalizeBufferFunct)(TLVWriter &writer, uintptr_t bufHandle, uint8_t *bufStart, uint32_t bufLen)

A function used to perform finalization of the output from a TLVWriter object.

Functions of this type are called when a TLVWriter's Finalize() method is called. The function is expected to perform any necessary clean-up or finalization related to consuming the output of the writer object. Examples of this include such things as recording the final length of the encoding, or closing a file descriptor.

Details
Parameters
[in] writer
A reference to the TLVWriter object that is being finalized.
[in,out] bufHandle
A uintptr_t context value that was set by previous calls to the GetNewBuffer function.
[in,out] bufStart
A pointer to the beginning of the current (and final) output buffer.
[in,out] bufLen
The number of bytes contained in the buffer pointed to by bufStart.
Return Values
WEAVE_NO_ERROR
If finalization was successful.
other
Other Weave or platform-specific error codes indicating that an error occurred during finalization.

GetNewBufferFunct

WEAVE_ERROR(* GetNewBufferFunct)(TLVWriter &writer, uintptr_t &bufHandle, uint8_t *&bufStart, uint32_t &bufLen)

A function that supplies new output buffer space to a TLVWriter.

Functions of this type are used to prepare new buffer space for a TLVWriter to write to. When called, the function is expected to return a pointer to a memory location where new data should be written, along with an associated maximum length. The function can supply write space either by allocating a new buffer to hold the data or by clearing out previously written data from an existing buffer.

Details
Parameters
[in] writer
A reference to the TLVWriter object that is requesting new buffer space.
[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 the beginning of the current output buffer. On exit, bufStart is expected to point to the beginning of the new output buffer. The new pointer value can be the same as the previous value (e.g. if the function copied the existing data elsewhere), or it can point to an entirely new location.
[in,out] bufLen
A reference to an unsigned integer. On entry to the function, bufLen contains the number of byte of unused space in the current buffer. On exit, bufLen is expected to contain the maximum number of bytes that can be written to the new output buffer.
Return Values
WEAVE_NO_ERROR
If the function was able to supply more buffer space for the writer.
other
Other Weave or platform-specific error codes indicating that an error occurred preventing the function from producing additional buffer space.

Public attributes

AppData

void * AppData

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

FinalizeBuffer

FinalizeBufferFunct FinalizeBuffer

A pointer to a function that will be called when the TLVWriter is finalized.

A TLVWriter object will call the FinalizeBuffer function whenever its Finalize() method is called. Applications can set the function pointer at any point prior to calling Finalize(). By default the pointer is set to NULL, which causes the Finalize() method to forego calling the function.

See the FinalizeBufferFunct type definition for additional information on implementing a FinalizeBuffer function.

GetNewBuffer

GetNewBufferFunct GetNewBuffer

A pointer to a function that will supply new output buffer space to a TLVWriter.

A TLVWriter object will call the GetNewBuffer function whenever an attempt is made to write data that exceeds the size of the current output buffer. If set to NULL (the default value), the writer will return a WEAVE_ERROR_NO_MEMORY if the output data overflows the current buffer.

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

See the GetNewBufferFunct type definition for additional information on implementing a GetNewBuffer function.

ImplicitProfileId

uint32_t ImplicitProfileId

The profile id of tags that should be encoded in implicit form.

When a writer is asked to encode a new element, if the profile id of the tag associated with the new element matches the value of the ImplicitProfileId member, the writer will encode the tag in implicit form, omitting the profile id in the process.

By default, the ImplicitProfileId property is set to kProfileIdNotSpecified, which instructs the writer not to emit implicitly encoded tags. Applications can set ImplicitProfileId at any time to enable encoding tags in implicit form starting at the current point in the encoding. The appropriate profile id to set is usually dependent on the context of the application or protocol being spoken.

Protected attributes

mBufHandle

uintptr_t mBufHandle

mBufStart

uint8_t * mBufStart

mContainerType

TLVType mContainerType

mLenWritten

uint32_t mLenWritten

mMaxLen

uint32_t mMaxLen

mRemainingLen

uint32_t mRemainingLen

mWritePoint

uint8_t * mWritePoint

Public functions

CloseContainer

WEAVE_ERROR CloseContainer(
  TLVWriter & containerWriter
)

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

The CloseContainer() method restores the state of a parent TLVWriter 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 writer to both methods.

When CloseContainer() returns, applications may continue to use the parent writer to write additional TLV elements that appear after the container element. At this point the supplied container writer should be considered 'de-initialized' and must not be used without re-initialization.

Details
Parameters
[in] containerWriter
A reference to the TLVWriter object that was supplied to the OpenContainer() method.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_INCORRECT_STATE
If the supplied container writer is not in the correct state.
WEAVE_ERROR_TLV_CONTAINER_OPEN
If another container writer has been opened on the supplied container writer and not yet closed.
WEAVE_ERROR_BUFFER_TOO_SMALL
If completing the encoding of the container would exceed the limit on the maximum number of bytes specified when the writer was initialized.
WEAVE_ERROR_NO_MEMORY
If an attempt to allocate an output buffer failed due to lack of memory.
other
Other Weave or platform-specific errors returned by the configured GetNewBuffer() or FinalizeBuffer() functions.

CopyContainer

WEAVE_ERROR CopyContainer(
  TLVReader & container
)

Copies a TLV container element from TLVReader object.

The CopyContainer() encodes a new TLV container element by copying a pre-encoded container element located at the current position of a TLVReader object. The method writes the entirety of the new container element in one call, copying the container's type, tag and elements from the source encoding. When the method returns, the writer object can be used to write additional TLV elements following the container element.

Details
Parameters
[in] container
A reference to a TLVReader object identifying the pre-encoded TLV container to be copied.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_INCORRECT_STATE
If the supplied reader is not positioned on a container element.
WEAVE_ERROR_TLV_CONTAINER_OPEN
If a container writer has been opened on the current writer and not yet closed.
WEAVE_ERROR_TLV_UNDERRUN
If the underlying TLV encoding associated with the supplied reader ended prematurely.
WEAVE_ERROR_INVALID_TLV_ELEMENT
If the supplied reader encountered an invalid or unsupported TLV element type.
WEAVE_ERROR_INVALID_TLV_TAG
If the supplied reader encountered a TLV tag in an invalid context, or if the tag associated with the source container is invalid or inappropriate in the context in which the new container is being written.
WEAVE_ERROR_BUFFER_TOO_SMALL
If writing the value would exceed the limit on the maximum number of bytes specified when the writer was initialized.
WEAVE_ERROR_NO_MEMORY
If an attempt to allocate an output buffer failed due to lack of memory.
other
Other Weave or platform-specific errors returned by the configured GetNewBuffer() or FinalizeBuffer() functions, or by the GetNextBuffer() function associated with the reader object.

CopyContainer

WEAVE_ERROR CopyContainer(
  uint64_t tag,
  TLVReader & container
)

Encodes a TLV container element from a pre-encoded set of member elements.

The CopyContainer() method encodes a new TLV container element (a structure, array or path) containing a set of member elements taken from a TLVReader object. When the method is called, the supplied reader object is expected to be positioned on a TLV container element. The newly encoded container will have the same type and members as the input container. The tag for the new container is specified as an input parameter.

When the method returns, the writer object can be used to write additional TLV elements following the container element.

Details
Parameters
[in] tag
The TLV tag to be encoded with the container, or AnonymousTag if the container should be encoded without a tag. Tag values should be constructed with one of the tag definition functions ProfileTag(), ContextTag() or CommonTag().
[in] container
A reference to a TLVReader object identifying a pre-encoded TLV container whose type and members should be copied.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_INCORRECT_STATE
If the supplied reader is not positioned on a container element.
WEAVE_ERROR_TLV_CONTAINER_OPEN
If a container writer has been opened on the current writer and not yet closed.
WEAVE_ERROR_TLV_UNDERRUN
If the underlying TLV encoding associated with the supplied reader ended prematurely.
WEAVE_ERROR_INVALID_TLV_ELEMENT
If the supplied reader encountered an invalid or unsupported TLV element type.
WEAVE_ERROR_INVALID_TLV_TAG
If the supplied reader encountered a TLV tag in an invalid context, or if the supplied tag is invalid or inappropriate in the context in which the new container is being written.
WEAVE_ERROR_BUFFER_TOO_SMALL
If writing the value would exceed the limit on the maximum number of bytes specified when the writer was initialized.
WEAVE_ERROR_NO_MEMORY
If an attempt to allocate an output buffer failed due to lack of memory.
other
Other Weave or platform-specific errors returned by the configured GetNewBuffer() or FinalizeBuffer() functions, or by the GetNextBuffer() function associated with the reader object.

CopyElement

WEAVE_ERROR CopyElement(
  TLVReader & reader
)

Copies a TLV element from a reader object into the writer.

The CopyElement() method encodes a new TLV element whose type, tag and value are taken from a TLVReader object. When the method is called, the supplied reader object is expected to be positioned on the source TLV element. The newly encoded element will have the same type, tag and contents as the input container. If the supplied element is a TLV container (structure, array or path), the entire contents of the container will be copied.

Details
Parameters
[in] reader
A reference to a TLVReader object identifying a pre-encoded TLV element that should be copied.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_INCORRECT_STATE
If the supplied reader is not positioned on an element.
WEAVE_ERROR_TLV_CONTAINER_OPEN
If a container writer has been opened on the current writer and not yet closed.
WEAVE_ERROR_TLV_UNDERRUN
If the underlying TLV encoding associated with the supplied reader ended prematurely.
WEAVE_ERROR_INVALID_TLV_ELEMENT
If the supplied reader encountered an invalid or unsupported TLV element type.
WEAVE_ERROR_INVALID_TLV_TAG
If the supplied reader encountered a TLV tag in an invalid context, or if the supplied tag is invalid or inappropriate in the context in which the new container is being written.
WEAVE_ERROR_BUFFER_TOO_SMALL
If writing the value would exceed the limit on the maximum number of bytes specified when the writer was initialized.
WEAVE_ERROR_NO_MEMORY
If an attempt to allocate an output buffer failed due to lack of memory.
other
Other Weave or platform-specific errors returned by the configured GetNewBuffer() or FinalizeBuffer() functions, or by the GetNextBuffer() function associated with the reader object.

CopyElement

WEAVE_ERROR CopyElement(
  uint64_t tag,
  TLVReader & reader
)

EndContainer

WEAVE_ERROR EndContainer(
  TLVType outerContainerType
)

Completes the encoding of a TLV container element.

The EndContainer() method completes the encoding of a TLV container element and restores the state of a TLVWrite object after an earlier call to StartContainer(). For every call to StartContainer() applications must make a corresponding call to EndContainer(), passing the TLVType value returned by the StartContainer() call. When EndContainer() returns, the writer object can be used to write additional TLV elements that follow the container element.

Details
Parameters
[in] outerContainerType
The TLVType value that was returned by the StartContainer() method.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_INCORRECT_STATE
If a corresponding StartContainer() call was not made.
WEAVE_ERROR_TLV_CONTAINER_OPEN
If a container writer has been opened on the current writer and not yet closed.
WEAVE_ERROR_BUFFER_TOO_SMALL
If writing the value would exceed the limit on the maximum number of bytes specified when the writer was initialized.
WEAVE_ERROR_NO_MEMORY
If an attempt to allocate an output buffer failed due to lack of memory.
other
Other Weave or platform-specific errors returned by the configured GetNewBuffer() or FinalizeBuffer() functions.

Finalize

WEAVE_ERROR Finalize(
  void
)

Finish the writing of a TLV encoding.

The Finalize() method completes the process of writing a TLV encoding to the underlying output buffer. The method must be called by the application before it uses the contents of the buffer. Finalize() can only be called when there are no container writers open for the current writer. (See OpenContainer()).

Details
Return Values
WEAVE_NO_ERROR
If the encoding was finalized successfully.
WEAVE_ERROR_TLV_CONTAINER_OPEN
If a container writer has been opened on the current writer and not yet closed.
other
Other Weave or platform-specific errors returned by the configured FinalizeBuffer() function.

GetContainerType

TLVType GetContainerType(
  void
) const 

Returns the type of container within which the TLVWriter is currently writing.

The GetContainerType() method returns the type of the TLV container within which the TLVWriter is currently writing. If the TLVWriter is not writing elements within a container (i.e. if writing at the outer-most level of an encoding) the method returns kTLVType_NotSpecified.

Details
Returns
The TLVType of the current container, or kTLVType_NotSpecified if the TLVWriter is not writing elements within a container.

GetLengthWritten

uint32_t GetLengthWritten(
  void
)

Returns the total number of bytes written since the writer was initialized.

Details
Returns
Total number of bytes written since the writer was initialized.

Init

void Init(
  uint8_t *buf,
  uint32_t maxLen
)

Initializes a TLVWriter object to write into a single output buffer.

Details
Parameters
[in] buf
A pointer to the buffer into which TLV should be written.
[in] maxLen
The maximum number of bytes that should be written to the output buffer.

Init

void Init(
  PacketBuffer *buf,
  uint32_t maxLen
)

Initializes a TLVWriter object to write into a single PacketBuffer.

Writing begins immediately after the last byte of existing data in the supplied buffer.

Details
Parameters
[in] buf
A pointer to an PacketBuffer into which TLV should be written.
[in] maxLen
The maximum number of bytes that should be written to the output buffer.

Init

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

Initializes a TLVWriter object to write into one or more PacketBuffers.

Writing begins immediately after the last byte of existing data in the specified buffer. If allowDiscontiguousBuffers is true, additional PacketBuffers will be allocated and chained to the supplied buffer as needed to accommodate the amount of data written. If the specified output buffer is already the head of a chain of buffers, output will be written to the subsequent buffers in the chain before any new buffers are allocated.

Details
Parameters
[in] buf
A pointer to an PacketBuffer into which TLV data should be written.
[in] maxLen
The maximum number of bytes that should be written to the output buffer(s).
[in] allowDiscontiguousBuffers
If true, write data to a chain of PacketBuffers, allocating new buffers as needed to store the data written. If false, writing will fail with WEAVE_ERROR_BUFFER_TOO_SMALL if the written data exceeds the space available in the initial output buffer.

OpenContainer

WEAVE_ERROR OpenContainer(
  uint64_t tag,
  TLVType containerType,
  TLVWriter & containerWriter
)

Initializes a new TLVWriter object for writing the members of a TLV container element.

The OpenContainer() method is used to write TLV container elements (structure, arrays or paths) to an encoding. The method takes the type and tag (if any) of the new container, and a reference to a new writer object (the container writer) that will be initialized for the purpose of writing the container's elements. Applications write the members of the new container using the container writer and then call CloseContainer() to complete the container encoding.

While the container writer is open, applications must not make calls on or otherwise alter the state of the parent writer.

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

  • The implicit profile id (ImplicitProfileId)
  • The application data pointer (AppData)
  • The GetNewBuffer and FinalizeBuffer function pointers

Details
Parameters
[in] tag
The TLV tag to be encoded with the container, or AnonymousTag if the container should be encoded without a tag. Tag values should be constructed with one of the tag definition functions ProfileTag(), ContextTag() or CommonTag().
[in] containerType
The type of container to encode. Must be one of kTLVType_Structure, kTLVType_Array or kTLVType_Path.
[out] containerWriter
A reference to a TLVWriter object that will be initialized for writing the members of the new container element. Any data associated with the supplied object is overwritten.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_WRONG_TLV_TYPE
If the value specified for containerType is incorrect.
WEAVE_ERROR_TLV_CONTAINER_OPEN
If a container writer has been opened on the current writer and not yet closed.
WEAVE_ERROR_INVALID_TLV_TAG
If the specified tag value is invalid or inappropriate in the context in which the value is being written.
WEAVE_ERROR_BUFFER_TOO_SMALL
If writing the value would exceed the limit on the maximum number of bytes specified when the writer was initialized.
WEAVE_ERROR_NO_MEMORY
If an attempt to allocate an output buffer failed due to lack of memory.
other
Other Weave or platform-specific errors returned by the configured GetNewBuffer() or FinalizeBuffer() functions.

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int8_t v
)

Encodes a TLV signed integer value.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Details
Parameters
[in] tag
The TLV tag to be encoded with the value, or AnonymousTag if the value should be encoded without a tag. Tag values should be constructed with one of the tag definition functions ProfileTag(), ContextTag() or CommonTag().
[in] v
The value to be encoded.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_TLV_CONTAINER_OPEN
If a container writer has been opened on the current writer and not yet closed.
WEAVE_ERROR_INVALID_TLV_TAG
If the specified tag value is invalid or inappropriate in the context in which the value is being written.
WEAVE_ERROR_BUFFER_TOO_SMALL
If writing the value would exceed the limit on the maximum number of bytes specified when the writer was initialized.
WEAVE_ERROR_NO_MEMORY
If an attempt to allocate an output buffer failed due to lack of memory.
other
Other Weave or platform-specific errors returned by the configured GetNewBuffer() or FinalizeBuffer() functions.

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int8_t v,
  bool preserveSize
)

Encodes a TLV signed integer value.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Details
Parameters
[in] tag
The TLV tag to be encoded with the value, or AnonymousTag if the value should be encoded without a tag. Tag values should be constructed with one of the tag definition functions ProfileTag(), ContextTag() or CommonTag().
[in] v
The value to be encoded.
[in] preserveSize
True if the value should be encoded in the same number of bytes as at the input type. False if value should be encoded in the minimum number of bytes necessary to represent the value. Note: Applications are strongly encouraged to set this parameter to false.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_TLV_CONTAINER_OPEN
If a container writer has been opened on the current writer and not yet closed.
WEAVE_ERROR_INVALID_TLV_TAG
If the specified tag value is invalid or inappropriate in the context in which the value is being written.
WEAVE_ERROR_BUFFER_TOO_SMALL
If writing the value would exceed the limit on the maximum number of bytes specified when the writer was initialized.
WEAVE_ERROR_NO_MEMORY
If an attempt to allocate an output buffer failed due to lack of memory.
other
Other Weave or platform-specific errors returned by the configured GetNewBuffer() or FinalizeBuffer() functions.

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int16_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int16_t v,
  bool preserveSize
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int32_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int32_t v,
  bool preserveSize
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int64_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  int64_t v,
  bool preserveSize
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint8_t v
)

Encodes a TLV unsigned integer value.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Details
Parameters
[in] tag
The TLV tag to be encoded with the value, or AnonymousTag if the value should be encoded without a tag. Tag values should be constructed with one of the tag definition functions ProfileTag(), ContextTag() or CommonTag().
[in] v
The value to be encoded.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_TLV_CONTAINER_OPEN
If a container writer has been opened on the current writer and not yet closed.
WEAVE_ERROR_INVALID_TLV_TAG
If the specified tag value is invalid or inappropriate in the context in which the value is being written.
WEAVE_ERROR_BUFFER_TOO_SMALL
If writing the value would exceed the limit on the maximum number of bytes specified when the writer was initialized.
WEAVE_ERROR_NO_MEMORY
If an attempt to allocate an output buffer failed due to lack of memory.
other
Other Weave or platform-specific errors returned by the configured GetNewBuffer() or FinalizeBuffer() functions.

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint8_t v,
  bool preserveSize
)

Encodes a TLV unsigned integer value.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Details
Parameters
[in] tag
The TLV tag to be encoded with the value, or AnonymousTag if the value should be encoded without a tag. Tag values should be constructed with one of the tag definition functions ProfileTag(), ContextTag() or CommonTag().
[in] v
The value to be encoded.
[in] preserveSize
True if the value should be encoded in the same number of bytes as at the input type. False if value should be encoded in the minimum number of bytes necessary to represent the value. Note: Applications are strongly encouraged to set this parameter to false.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_TLV_CONTAINER_OPEN
If a container writer has been opened on the current writer and not yet closed.
WEAVE_ERROR_INVALID_TLV_TAG
If the specified tag value is invalid or inappropriate in the context in which the value is being written.
WEAVE_ERROR_BUFFER_TOO_SMALL
If writing the value would exceed the limit on the maximum number of bytes specified when the writer was initialized.
WEAVE_ERROR_NO_MEMORY
If an attempt to allocate an output buffer failed due to lack of memory.
other
Other Weave or platform-specific errors returned by the configured GetNewBuffer() or FinalizeBuffer() functions.

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint16_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint16_t v,
  bool preserveSize
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint32_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint32_t v,
  bool preserveSize
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint64_t v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  uint64_t v,
  bool preserveSize
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  float v
)

Put

WEAVE_ERROR Put(
  uint64_t tag,
  double v
)

Encodes a TLV floating point value.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Details
Parameters
[in] tag
The TLV tag to be encoded with the value, or AnonymousTag if the value should be encoded without a tag. Tag values should be constructed with one of the tag definition functions ProfileTag(), ContextTag() or CommonTag().
[in] v
The value to be encoded.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_TLV_CONTAINER_OPEN
If a container writer has been opened on the current writer and not yet closed.
WEAVE_ERROR_INVALID_TLV_TAG
If the specified tag value is invalid or inappropriate in the context in which the value is being written.
WEAVE_ERROR_BUFFER_TOO_SMALL
If writing the value would exceed the limit on the maximum number of bytes specified when the writer was initialized.
WEAVE_ERROR_NO_MEMORY
If an attempt to allocate an output buffer failed due to lack of memory.
other
Other Weave or platform-specific errors returned by the configured GetNewBuffer() or FinalizeBuffer() functions.

PutBoolean

WEAVE_ERROR PutBoolean(
  uint64_t tag,
  bool v
)

Encodes a TLV boolean value.

Details
Parameters
[in] tag
The TLV tag to be encoded with the value, or AnonymousTag if the value should be encoded without a tag. Tag values should be constructed with one of the tag definition functions ProfileTag(), ContextTag() or CommonTag().
[in] v
The value to be encoded.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_TLV_CONTAINER_OPEN
If a container writer has been opened on the current writer and not yet closed.
WEAVE_ERROR_INVALID_TLV_TAG
If the specified tag value is invalid or inappropriate in the context in which the value is being written.
WEAVE_ERROR_BUFFER_TOO_SMALL
If writing the value would exceed the limit on the maximum number of bytes specified when the writer was initialized.
WEAVE_ERROR_NO_MEMORY
If an attempt to allocate an output buffer failed due to lack of memory.
other
Other Weave or platform-specific errors returned by the configured GetNewBuffer() or FinalizeBuffer() functions.

PutBytes

WEAVE_ERROR PutBytes(
  uint64_t tag,
  const uint8_t *buf,
  uint32_t len
)

Encodes a TLV byte string value.

Details
Parameters
[in] tag
The TLV tag to be encoded with the value, or AnonymousTag if the value should be encoded without a tag. Tag values should be constructed with one of the tag definition functions ProfileTag(), ContextTag() or CommonTag().
[in] buf
A pointer to a buffer containing the bytes string to be encoded.
[in] len
The number of bytes to be encoded.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_TLV_CONTAINER_OPEN
If a container writer has been opened on the current writer and not yet closed.
WEAVE_ERROR_INVALID_TLV_TAG
If the specified tag value is invalid or inappropriate in the context in which the value is being written.
WEAVE_ERROR_BUFFER_TOO_SMALL
If writing the value would exceed the limit on the maximum number of bytes specified when the writer was initialized.
WEAVE_ERROR_NO_MEMORY
If an attempt to allocate an output buffer failed due to lack of memory.
other
Other Weave or platform-specific errors returned by the configured GetNewBuffer() or FinalizeBuffer() functions.

PutNull

WEAVE_ERROR PutNull(
  uint64_t tag
)

Encodes a TLV null value.

Details
Parameters
[in] tag
The TLV tag to be encoded with the value, or AnonymousTag if the value should be encoded without a tag. Tag values should be constructed with one of the tag definition functions ProfileTag(), ContextTag() or CommonTag().
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_TLV_CONTAINER_OPEN
If a container writer has been opened on the current writer and not yet closed.
WEAVE_ERROR_INVALID_TLV_TAG
If the specified tag value is invalid or inappropriate in the context in which the value is being written.
WEAVE_ERROR_BUFFER_TOO_SMALL
If writing the value would exceed the limit on the maximum number of bytes specified when the writer was initialized.
WEAVE_ERROR_NO_MEMORY
If an attempt to allocate an output buffer failed due to lack of memory.
other
Other Weave or platform-specific errors returned by the configured GetNewBuffer() or FinalizeBuffer() functions.

PutPreEncodedContainer

WEAVE_ERROR PutPreEncodedContainer(
  uint64_t tag,
  TLVType containerType,
  const uint8_t *data,
  uint32_t dataLen
)

Encodes a TLV container element from a pre-encoded set of member elements.

The PutPreEncodedContainer() method encodes a new TLV container element (a structure, array or path) containing a set of member elements taken from a pre-encoded buffer. The input buffer is expected to contain zero or more full-encoded TLV elements, with tags that conform to the rules associated with the specified container type (e.g. structure members must have tags, while array members must not).

The method encodes the entirety of the container element in one call. When PutPreEncodedContainer() returns, the writer object can be used to write additional TLV elements following the container element.

Details
Parameters
[in] tag
The TLV tag to be encoded with the container, or AnonymousTag if the container should be encoded without a tag. Tag values should be constructed with one of the tag definition functions ProfileTag(), ContextTag() or CommonTag().
[in] containerType
The type of container to encode. Must be one of kTLVType_Structure, kTLVType_Array or kTLVType_Path.
[in] data
A pointer to a buffer containing zero of more encoded TLV elements that will become the members of the new container.
[in] dataLen
The number of bytes in the data buffer.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_WRONG_TLV_TYPE
If the value specified for containerType is incorrect.
WEAVE_ERROR_TLV_CONTAINER_OPEN
If a container writer has been opened on the current writer and not yet closed.
WEAVE_ERROR_INVALID_TLV_TAG
If the specified tag value is invalid or inappropriate in the context in which the value is being written.
WEAVE_ERROR_BUFFER_TOO_SMALL
If writing the value would exceed the limit on the maximum number of bytes specified when the writer was initialized.
WEAVE_ERROR_NO_MEMORY
If an attempt to allocate an output buffer failed due to lack of memory.
other
Other Weave or platform-specific errors returned by the configured GetNewBuffer() or FinalizeBuffer() functions.

PutString

WEAVE_ERROR PutString(
  uint64_t tag,
  const char *buf
)

Encodes a TLV UTF8 string value.

Details
Parameters
[in] tag
The TLV tag to be encoded with the value, or AnonymousTag if the value should be encoded without a tag. Tag values should be constructed with one of the tag definition functions ProfileTag(), ContextTag() or CommonTag().
[in] buf
A pointer to the null-terminated UTF-8 string to be encoded.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_TLV_CONTAINER_OPEN
If a container writer has been opened on the current writer and not yet closed.
WEAVE_ERROR_INVALID_TLV_TAG
If the specified tag value is invalid or inappropriate in the context in which the value is being written.
WEAVE_ERROR_BUFFER_TOO_SMALL
If writing the value would exceed the limit on the maximum number of bytes specified when the writer was initialized.
WEAVE_ERROR_NO_MEMORY
If an attempt to allocate an output buffer failed due to lack of memory.
other
Other Weave or platform-specific errors returned by the configured GetNewBuffer() or FinalizeBuffer() functions.

PutString

WEAVE_ERROR PutString(
  uint64_t tag,
  const char *buf,
  uint32_t len
)

Encodes a TLV UTF8 string value.

Details
Parameters
[in] tag
The TLV tag to be encoded with the value, or AnonymousTag if the value should be encoded without a tag. Tag values should be constructed with one of the tag definition functions ProfileTag(), ContextTag() or CommonTag().
[in] buf
A pointer to the UTF-8 string to be encoded.
[in] len
The length (in bytes) of the string to be encoded.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_TLV_CONTAINER_OPEN
If a container writer has been opened on the current writer and not yet closed.
WEAVE_ERROR_INVALID_TLV_TAG
If the specified tag value is invalid or inappropriate in the context in which the value is being written.
WEAVE_ERROR_BUFFER_TOO_SMALL
If writing the value would exceed the limit on the maximum number of bytes specified when the writer was initialized.
WEAVE_ERROR_NO_MEMORY
If an attempt to allocate an output buffer failed due to lack of memory.
other
Other Weave or platform-specific errors returned by the configured GetNewBuffer() or FinalizeBuffer() functions.

PutStringF

WEAVE_ERROR PutStringF(
  uint64_t tag,
  const char *fmt,
  ...
)

Encode the string output formatted according to the format in the TLV element.

PutStringF is an analog of a sprintf where the output is stored in a TLV element as opposed to a character buffer. When extended printf functionality is available, the function is able to output the result string into a discontinuous underlying storage. The implementation supports the following printf enhancements:

The platform supplies a callback-based vcbprintf that provides the ability to call a custom callback in place of putchar.

The platform supplies a variant of vsnprintf called vsnprintf_ex, that behaves exactly like vsnprintf except it has provisions for omitting the first n characters of the output.

Note that while the callback-based function may be the simplest and use the least amount of code, the vsprintf_ex variety of functions will consume less stack.

If neither of the above is available, but platform provides malloc the function will allocate a temporary buffer to hold the output. When the platform supplies neither enhancement to the printf family nor malloc, the output is truncated such that it fits in the continuous state in the current TLV storage

Details
Parameters
[in] tag
The TLV tag to be encoded with the value, or AnonymousTag if the value should be encoded without a tag. Tag values should be constructed with one of the tag definition functions ProfileTag(), ContextTag() or CommonTag().
[in] fmt
The format string used to format the argument list. Follows the same syntax and rules as the format string for printf family of functions.
[in] ...
A list of arguments to be formatted in the output value according to fmt.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
other
If underlying calls to TLVWriter methods WriteElementHead or GetNewBuffer failed, their error is immediately forwarded up the call stack.

StartContainer

WEAVE_ERROR StartContainer(
  uint64_t tag,
  TLVType containerType,
  TLVType & outerContainerType
)

Begins encoding a new TLV container element.

The StartContainer() method is used to write TLV container elements (structure, arrays or paths) to an encoding. The method takes the type and tag (if any) of the new container, and a reference to a TLVType value which will be used to save the current context of the writer while it is being used to write the container.

Once the StartContainer() method returns, the application should use the current TLVWriter object to write the elements of the container. When finish, the application must call the EndContainer() method to finish the encoding of the container.

Details
Parameters
[in] tag
The TLV tag to be encoded with the container, or AnonymousTag if the container should be encoded without a tag. Tag values should be constructed with one of the tag definition functions ProfileTag(), ContextTag() or CommonTag().
[in] containerType
The type of container to encode. Must be one of kTLVType_Structure, kTLVType_Array or kTLVType_Path.
[out] outerContainerType
A reference to a TLVType value that will receive the context of the writer.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
WEAVE_ERROR_WRONG_TLV_TYPE
If the value specified for containerType is incorrect.
WEAVE_ERROR_TLV_CONTAINER_OPEN
If a container writer has been opened on the current writer and not yet closed.
WEAVE_ERROR_INVALID_TLV_TAG
If the specified tag value is invalid or inappropriate in the context in which the value is being written.
WEAVE_ERROR_BUFFER_TOO_SMALL
If writing the value would exceed the limit on the maximum number of bytes specified when the writer was initialized.
WEAVE_ERROR_NO_MEMORY
If an attempt to allocate an output buffer failed due to lack of memory.
other
Other Weave or platform-specific errors returned by the configured GetNewBuffer() or FinalizeBuffer() functions.

VPutStringF

WEAVE_ERROR VPutStringF(
  uint64_t tag,
  const char *fmt,
  va_list ap
)

Encode the string output formatted according to the format in the TLV element.

PutStringF is an analog of a sprintf where the output is stored in a TLV element as opposed to a character buffer. When extended printf functionality is available, the function is able to output the result string into a discontinuous underlying storage. The implementation supports the following printf enhancements:

The platform supplies a callback-based vcbprintf that provides the ability to call a custom callback in place of putchar.

The platform supplies a variant of vsnprintf called vsnprintf_ex, that behaves exactly like vsnprintf except it has provisions for omitting the first n characters of the output.

Note that while the callback-based function may be the simplest and use the least amount of code, the vsprintf_ex variety of functions will consume less stack.

If neither of the above is available, but platform provides malloc the function will allocate a temporary buffer to hold the output. When the platform supplies neither enhancement to the printf family nor malloc, the output is truncated such that it fits in the continuous state in the current TLV storage

Details
Parameters
[in] tag
The TLV tag to be encoded with the value, or AnonymousTag if the value should be encoded without a tag. Tag values should be constructed with one of the tag definition functions ProfileTag(), ContextTag() or CommonTag().
[in] fmt
The format string used to format the argument list. Follows the same syntax and rules as the format string for printf family of functions.
[in] ap
A list of arguments to be formatted in the output value according to fmt.
Return Values
WEAVE_NO_ERROR
If the method succeeded.
other
If underlying calls to TLVWriter methods WriteElementHead or GetNewBuffer failed, their error is immediately forwarded up the call stack.

Public static functions

FinalizePacketBuffer

WEAVE_ERROR FinalizePacketBuffer(
  TLVWriter & writer,
  uintptr_t bufHandle,
  uint8_t *bufStart,
  uint32_t dataLen
)

An implementation of a TLVWriter FinalizeBuffer function for writing to a chain of PacketBuffers.

The FinalizePacketBuffer() function performs the necessary finalization required when using a TLVWriter to write to a chain of PacketBuffers. The function is designed to be used in conjunction with the GetNewPacketBuffer() function.

See the FinalizeBufferFunct type definition for additional information on the API of the FinalizePacketBuffer() function.

GetNewPacketBuffer

WEAVE_ERROR GetNewPacketBuffer(
  TLVWriter & writer,
  uintptr_t & bufHandle,
  uint8_t *& bufStart,
  uint32_t & bufLen
)

An implementation of a TLVWriter GetNewBuffer function for writing to a chain of PacketBuffers.

The GetNewPacketBuffer() function supplies new output space to a TLVWriter by allocating a chain of one or more PacketBuffers as needed to store the encoding. The function is designed to be assigned to the TLVWriter GetNewBuffer function pointer.

Note that when using the GetNewPacketBuffer with a TLVWriter, the corresponding FinalizePacketBuffer() function (or an equivalent) should also be used to finalize the buffer chain.

See the GetNewBufferFunct type definition for additional information on the API of the GetNewPacketBuffer() function.

Protected functions

IsCloseContainerReserved

bool IsCloseContainerReserved(
  void
) const 

Determine whether the container should reserve space for the CloseContainer symbol at the point of starting / opening the container.

IsContainerOpen

bool IsContainerOpen(
  void
) const 

SetCloseContainerReserved

void SetCloseContainerReserved(
  bool aCloseContainerReserved
)

Set whether the container should reserve the space for the CloseContainer symbol at the point of starting / opening the container.

SetContainerOpen

void SetContainerOpen(
  bool aContainerOpen
)

WriteData

WEAVE_ERROR WriteData(
  const uint8_t *p,
  uint32_t len
)

WriteElementHead

WEAVE_ERROR WriteElementHead(
  TLVElementType elemType,
  uint64_t tag,
  uint64_t lenOrVal
)

WriteElementWithData

WEAVE_ERROR WriteElementWithData(
  TLVType type,
  uint64_t tag,
  const uint8_t *data,
  uint32_t dataLen
)