Google Git
Sign in
pigweed / third_party / github / project-chip / connectedhomeip / 52e228f0d09974b90ad7ca51c95ce2202148dd4f / . / src / lib / core / CHIPTLV.h
blob: 3ab437560273d571d09f973dbc78d34f256a7ce8 [file] [log] [blame]
/*
*
* Copyright (c) 2020-2021 Project CHIP Authors
* Copyright (c) 2013-2017 Nest Labs, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* @file
* This file contains definitions for working with data encoded in CHIP TLV format.
*
* CHIP TLV (Tag-Length-Value) is a generalized encoding method for simple structured data. It
* shares many properties with the commonly used JSON serialization format while being considerably
* more compact over the wire.
*/
#pragma once
#include <lib/core/CHIPError.h>
#include <lib/core/CHIPTLVTags.h>
#include <lib/core/CHIPTLVTypes.h>
#include <lib/support/BitFlags.h>
#include <lib/support/BitMask.h>
#include <lib/support/DLLUtil.h>
#include <lib/support/EnforceFormat.h>
#include <lib/support/ScopedBuffer.h>
#include <lib/support/Span.h>
#include <lib/support/TypeTraits.h>
#include <lib/support/logging/Constants.h>
#include <stdarg.h>
#include <stdlib.h>
#include <type_traits>
/**
* @namespace chip::TLV
*
* Definitions for working with data encoded in CHIP TLV format.
*
* CHIP TLV is a generalized encoding method for simple structured data. It shares many properties
* with the commonly used JSON serialization format while being considerably more compact over the wire.
*/
namespace chip {
namespace TLV {
constexpr inline uint8_t operator|(TLVElementType lhs, TLVTagControl rhs)
{
return static_cast<uint8_t>(lhs) | static_cast<uint8_t>(rhs);
}
constexpr inline uint8_t operator|(TLVTagControl lhs, TLVElementType rhs)
{
return static_cast<uint8_t>(lhs) | static_cast<uint8_t>(rhs);
}
enum
{
kTLVControlByte_NotSpecified = 0xFFFF
};
class TLVBackingStore;
/**
* Provides a memory efficient parser for data encoded in CHIP TLV format.
*
* TLVReader implements a forward-only, “pull-style” parser for CHIP 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 encountered--either a structure,
* an array or a path--the 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 CHIP_END_OF_TLV error from the Next() method.
* The reader will continue to return CHIP_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 memory provided
* by a TLVBackingStore.
*/
class DLL_EXPORT TLVReader
{
friend class TLVWriter;
friend class TLVUpdater;
public:
/**
* Initializes a TLVReader object from another TLVReader object.
*
* @param[in] aReader A read-only reference to the TLVReader to initialize
* this from.
*
*/
void Init(const TLVReader & aReader);
/**
* Initializes a TLVReader object to read from a single input buffer.
*
* @param[in] data A pointer to a buffer containing the TLV data to be parsed.
* @param[in] dataLen The length of the TLV data to be parsed.
*
*/
void Init(const uint8_t * data, size_t dataLen);
/**
* Initializes a TLVReader object to read from a single input buffer
* represented as a span.
*
* @param[in] data A byte span to read from
*
*/
void Init(const ByteSpan & data) { Init(data.data(), data.size()); }
/**
* Initializes a TLVReader object to read from a single input buffer
* represented as byte array.
*
* @param[in] data A byte buffer to read from
*
*/
template <size_t N>
void Init(const uint8_t (&data)[N])
{
Init(data, N);
}
/**
* Initializes a TLVReader object to read from a TLVBackingStore.
*
* Parsing begins at the backing store's start position and continues until the
* end of the data in the buffer, or maxLen bytes have been parsed.
*
* @param[in] backingStore A reference to a TLVBackingStore providing the TLV data to be parsed.
* @param[in] maxLen The maximum number of bytes to parse. Defaults to the amount of data
* in the input buffer.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval other Other error codes returned by TLVBackingStore::OnInit().
*/
CHIP_ERROR Init(TLVBackingStore & backingStore, uint32_t maxLen = UINT32_MAX);
/**
* 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 @em 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 #CHIP_END_OF_TLV error and the position of the reader will remain unchanged.
*
* @retval #CHIP_NO_ERROR If the reader was successfully positioned on a new element.
* @retval #CHIP_END_OF_TLV If no further elements are available.
* @retval #CHIP_ERROR_TLV_UNDERRUN If the underlying TLV encoding ended prematurely.
* @retval #CHIP_ERROR_INVALID_TLV_ELEMENT
* If the reader encountered an invalid or unsupported TLV element
* type.
* @retval #CHIP_ERROR_INVALID_TLV_TAG If the reader encountered a TLV tag in an invalid context.
* @retval #CHIP_ERROR_UNKNOWN_IMPLICIT_TLV_TAG
* If the reader encountered a implicitly-encoded TLV tag for which
* the corresponding profile id is unknown.
* @retval other Other CHIP or platform error codes returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR Next();
/**
* Advances the TLVReader object to the next TLV element to be read, asserting the tag of
* the new element.
*
* The Next(Tag expectedTag) method is a convenience method that has the
* same behavior as Next(), but also verifies that the tag of the new TLV element matches
* the supplied argument.
*
* @param[in] expectedTag The expected tag for the next element.
*
* @retval #CHIP_NO_ERROR If the reader was successfully positioned on a new element.
* @retval #CHIP_END_OF_TLV If no further elements are available.
* @retval #CHIP_ERROR_UNEXPECTED_TLV_ELEMENT
* If the tag associated with the new element does not match the
* value of the @p expectedTag argument.
* @retval #CHIP_ERROR_TLV_UNDERRUN If the underlying TLV encoding ended prematurely.
* @retval #CHIP_ERROR_INVALID_TLV_ELEMENT
* If the reader encountered an invalid or unsupported TLV
* element type.
* @retval #CHIP_ERROR_INVALID_TLV_TAG If the reader encountered a TLV tag in an invalid context.
* @retval other Other CHIP or platform error codes returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR Next(Tag 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, Tag 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.
*
* @param[in] expectedType The expected data type for the next element.
* @param[in] expectedTag The expected tag for the next element.
*
* @retval #CHIP_NO_ERROR If the reader was successfully positioned on a new element.
* @retval #CHIP_END_OF_TLV If no further elements are available.
* @retval #CHIP_ERROR_WRONG_TLV_TYPE If the type of the new element does not match the value
* of the @p expectedType argument.
* @retval #CHIP_ERROR_UNEXPECTED_TLV_ELEMENT
* If the tag associated with the new element does not match the
* value of the @p expectedTag argument.
* @retval #CHIP_ERROR_TLV_UNDERRUN If the underlying TLV encoding ended prematurely.
* @retval #CHIP_ERROR_INVALID_TLV_ELEMENT
* If the reader encountered an invalid or unsupported TLV
* element type.
* @retval #CHIP_ERROR_INVALID_TLV_TAG If the reader encountered a TLV tag in an invalid context.
* @retval other Other CHIP or platform error codes returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR Next(TLVType expectedType, Tag expectedTag);
/**
* Returns the type of the current TLV element.
*
* @return 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.
*/
TLVType GetType() 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.
*
* @note If the reader is not positioned on a TLV element when GetTag() is called, the return value
* is undefined. Therefore whenever the position of the reader is uncertain applications should call
* GetType() to determine if the reader is position on an element (GetType() != kTLVType_NotSpecified)
* before calling GetTag().
*
* @return An unsigned integer containing information about the tag associated with the current
* TLV element.
*/
Tag GetTag() const { return mElemTag; }
/**
* 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.
*
* @return 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.
*/
uint32_t GetLength() 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
* TLV Debug Utilities (that try to decode the tag control byte when pretty
* printing the TLV buffer contents).
*
* @note Unless you really know what you are doing, please refrain from using
* this method and the associated control byte information.
*
* @return An unsigned integer containing the control byte associated with
* the current TLV element. kTLVControlByte_NotSpecified is
* returned if the reader is not positioned @em on an element.
*/
uint16_t GetControlByte() const { return mControlByte; }
/**
* Get the value of the current element as a bool type.
*
* @param[out] v Receives the value associated with current TLV element.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_WRONG_TLV_TYPE If the current element is not a TLV boolean type, or the
* reader is not positioned on an element.
*/
CHIP_ERROR Get(bool & 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.
*
* @param[out] v Receives the value associated with current TLV element.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_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.
*
*/
CHIP_ERROR Get(int8_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.
*
* @param[out] v Receives the value associated with current TLV element.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_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.
*
*/
CHIP_ERROR Get(int16_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.
*
* @param[out] v Receives the value associated with current TLV element.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_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.
*
*/
CHIP_ERROR Get(int32_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.
*
* @param[out] v Receives the value associated with current TLV element.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_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.
*
*/
CHIP_ERROR Get(int64_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.
*
* @param[out] v Receives the value associated with current TLV element.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_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.
*
*/
CHIP_ERROR Get(uint8_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.
*
* @param[out] v Receives the value associated with current TLV element.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_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.
*
*/
CHIP_ERROR Get(uint16_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.
*
* @param[out] v Receives the value associated with current TLV element.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_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.
*
*/
CHIP_ERROR Get(uint32_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.
*
* @param[out] v Receives the value associated with current TLV element.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_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.
*
*/
CHIP_ERROR Get(uint64_t & v);
/**
* Get the value of the current element as a double-precision floating point number.
*
* @param[out] v Receives the value associated with current TLV element.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_WRONG_TLV_TYPE If the current element is not a TLV floating point type, or
* the reader is not positioned on an element.
*
*/
CHIP_ERROR Get(double & v);
/**
* Get the value of the current element as a single-precision floating point number.
*
* @param[out] v Receives the value associated with current TLV element.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_WRONG_TLV_TYPE If the current element is not a TLV floating point type, or
* the reader is not positioned on an element.
*
*/
CHIP_ERROR Get(float & v);
/**
* Get the value of the current element as a ByteSpan
*
* @param[out] v Receives the value associated with current TLV element.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_WRONG_TLV_TYPE If the current element is not a TLV bytes array, or
* the reader is not positioned on an element.
*
*/
CHIP_ERROR Get(ByteSpan & v);
/**
* Get the value of the current element as a FixedByteSpan
*
* @param[out] v Receives the value associated with current TLV element.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_WRONG_TLV_TYPE If the current element is not a TLV bytes array, or
* the reader is not positioned on an element.
*
*/
template <size_t N>
CHIP_ERROR Get(FixedByteSpan<N> & v)
{
const uint8_t * val;
ReturnErrorOnFailure(GetDataPtr(val));
VerifyOrReturnError(GetLength() == N, CHIP_ERROR_UNEXPECTED_TLV_ELEMENT);
v = FixedByteSpan<N>(val);
return CHIP_NO_ERROR;
}
/**
* Get the value of the current element as a CharSpan
*
* @param[out] v Receives the value associated with current TLV element.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_WRONG_TLV_TYPE If the current element is not a TLV character string, or
* the reader is not positioned on an element.
*
*/
CHIP_ERROR Get(CharSpan & v);
/**
* Get the value of the current element as an enum value, if it's an integer
* value that fits in the enum type.
*
* @param[out] v Receives the value associated with current TLV element.
*/
template <typename T, typename = std::enable_if_t<std::is_enum<T>::value>>
CHIP_ERROR Get(T & v)
{
std::underlying_type_t<T> val;
ReturnErrorOnFailure(Get(val));
v = static_cast<T>(val);
return CHIP_NO_ERROR;
}
/**
* Get the value of the current element as a BitFlags value, if it's an integer
* value that fits in the BitFlags type.
*
* @param[out] v Receives the value associated with current TLV element.
*/
template <typename T>
CHIP_ERROR Get(BitFlags<T> & v)
{
std::underlying_type_t<T> val;
ReturnErrorOnFailure(Get(val));
v.SetRaw(val);
return CHIP_NO_ERROR;
}
/**
* Get the value of the current element as a BitMask value, if it's an integer
* value that fits in the BitMask type.
*
* @param[out] v Receives the value associated with current TLV element.
*/
template <typename T>
CHIP_ERROR Get(BitMask<T> & v)
{
std::underlying_type_t<T> val;
ReturnErrorOnFailure(Get(val));
v.SetRaw(val);
return CHIP_NO_ERROR;
}
/**
* 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().
*
* @note The data output by this method is NOT null-terminated.
*
* @param[in] buf A pointer to a buffer to receive the string data.
* @param[in] bufSize The size in bytes of the buffer pointed to by @p buf.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_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.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If the supplied buffer is too small to hold the data associated
* with the current element.
* @retval #CHIP_ERROR_TLV_UNDERRUN If the underlying TLV encoding ended prematurely.
* @retval other Other CHIP or platform error codes returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR GetBytes(uint8_t * buf, size_t bufSize);
/**
* 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
* Platform::MemoryAlloc() and should be freed with Platform::MemoryFree() by the caller when
* it is no longer needed.
*
* @note The data returned by this method is NOT null-terminated.
*
* @param[out] buf A reference to a pointer to which a heap-allocated buffer of
* @p dataLen bytes will be assigned on success.
* @param[out] dataLen A reference to storage for the size, in bytes, of @p buf on
* success.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_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.
* @retval #CHIP_ERROR_NO_MEMORY If memory could not be allocated for the output buffer.
* @retval #CHIP_ERROR_TLV_UNDERRUN If the underlying TLV encoding ended prematurely.
* @retval other Other CHIP or platform error codes returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR DupBytes(uint8_t *& buf, uint32_t & dataLen);
/**
* 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.
*
* @param[in] buf A pointer to a buffer to receive the byte string data.
* @param[in] bufSize The size in bytes of the buffer pointed to by @p buf.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_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.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If the supplied buffer is too small to hold the data associated
* with the current element.
* @retval #CHIP_ERROR_TLV_UNDERRUN If the underlying TLV encoding ended prematurely.
* @retval other Other CHIP or platform error codes returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR GetString(char * buf, size_t bufSize);
/**
* 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
* Platform::MemoryAlloc() and should be freed with chip::Platform::MemoryFree() by the caller when
* it is no longer needed.
*
* @param[out] buf A reference to a pointer to which a heap-allocated buffer of
* will be assigned on success.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_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.
* @retval #CHIP_ERROR_NO_MEMORY If memory could not be allocated for the output buffer.
* @retval #CHIP_ERROR_TLV_UNDERRUN If the underlying TLV encoding ended prematurely.
* @retval other Other CHIP or platform error codes returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR DupString(char *& buf);
/**
* Get a pointer to the initial encoded byte of a TLV byte or UTF8 string element.
*
* This method returns a direct pointer to the encoded string value within the underlying input buffer
* if a non-zero length string payload is present. To succeed, the method requires that the entirety of the
* string value be present in a single buffer. Otherwise the method returns #CHIP_ERROR_TLV_UNDERRUN.
* This makes the method of limited use when reading data from multiple discontiguous buffers.
*
* If no string data is present (i.e the length is zero), data shall be updated to point to null.
*
* @param[out] data A reference to a const pointer that will receive a pointer to
* the underlying string data.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_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.
* @retval #CHIP_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.
* @retval other Other CHIP or platform error codes returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR GetDataPtr(const uint8_t *& data);
/**
* 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 @em 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 CHIP_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.
*
* @param[out] outerContainerType A reference to a TLVType value that will receive the context
* of the reader.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_INCORRECT_STATE If the current element is not positioned on a container element.
*
*/
CHIP_ERROR EnterContainer(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.
*
* @note Any changes made to the configuration of the reader between the calls to EnterContainer()
* and ExitContainer() are NOT undone by the call to ExitContainer(). For example, a change to the
* implicit profile id (@p ImplicitProfileId) will not be reversed when a container is exited. Thus
* it is the application's responsibility to adjust the configuration accordingly at the appropriate
* times.
*
* @param[in] outerContainerType The TLVType value that was returned by the EnterContainer() method.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_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.
* @retval #CHIP_ERROR_TLV_UNDERRUN If the underlying TLV encoding ended prematurely.
* @retval #CHIP_ERROR_INVALID_TLV_ELEMENT
* If the reader encountered an invalid or unsupported TLV element type.
* @retval #CHIP_ERROR_INVALID_TLV_TAG If the reader encountered a TLV tag in an invalid context.
* @retval other Other CHIP or platform error codes returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR ExitContainer(TLVType outerContainerType);
/**
* 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 <em>container reader</em> while the reader on which OpenContainer() is called is known as the <em>parent
* reader</em>.
*
* 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 CHIP_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:
*
* @li The implicit profile id (ImplicitProfileId)
* @li The application data pointer (AppData)
* @li The GetNextBuffer function pointer
*
* @note The EnterContainer() method can be used as an alternative to OpenContainer() to read a
* container element without initializing a new reader object.
*
* @param[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.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_INCORRECT_STATE If the current element is not positioned on a container element.
*
*/
CHIP_ERROR OpenContainer(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.
*
* @param[in] containerReader A reference to the TLVReader object that was supplied to the
* OpenContainer() method.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_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.
* @retval #CHIP_ERROR_TLV_UNDERRUN If the underlying TLV encoding ended prematurely.
* @retval #CHIP_ERROR_INVALID_TLV_ELEMENT
* If the reader encountered an invalid or unsupported TLV
* element type.
* @retval #CHIP_ERROR_INVALID_TLV_TAG If the reader encountered a TLV tag in an invalid context.
* @retval other Other CHIP or platform error codes returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR CloseContainer(TLVReader & containerReader);
/**
* 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.
*
* @return The TLVType of the current container, or kTLVType_NotSpecified if the TLVReader is not
* positioned within a container.
*/
TLVType GetContainerType() const { return mContainerType; }
/**
* Verifies that the TLVReader 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 CHIP_END_OF_TLV.
*
* @note When there are more TLV elements in the collection, this method will change the position
* of the reader.
*
* @retval #CHIP_NO_ERROR If there are no further TLV elements to be read.
* @retval #CHIP_ERROR_UNEXPECTED_TLV_ELEMENT
* If another TLV element was found in the collection.
* @retval #CHIP_ERROR_TLV_UNDERRUN If the underlying TLV encoding ended prematurely.
* @retval #CHIP_ERROR_INVALID_TLV_ELEMENT
* If the reader encountered an invalid or unsupported TLV element
* type.
* @retval #CHIP_ERROR_INVALID_TLV_TAG If the reader encountered a TLV tag in an invalid context.
* @retval other Other CHIP or platform error codes returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR VerifyEndOfContainer();
/**
* Returns the total number of bytes read since the reader was initialized.
*
* @return Total number of bytes read since the reader was initialized.
*/
uint32_t GetLengthRead() const { return mLenRead; }
/**
* Returns the total number of bytes that can be read until the max read length is reached.
*
* @return Total number of bytes that can be read until the max read length is reached.
*/
uint32_t GetRemainingLength() const { return mMaxLen - mLenRead; }
/**
* Return the total number of bytes for the TLV data
* @return the total number of bytes for the TLV data
*/
uint32_t GetTotalLength() const { return mMaxLen; }
/**
* Returns the stored backing store.
*
* @return the stored backing store.
*/
TLVBackingStore * GetBackingStore() { return mBackingStore; }
/**
* Gets the point in the underlying input buffer that corresponds to the reader's current position.
*
* @note Depending on the type of the current element, GetReadPoint() will return a pointer that
* is some number of bytes *after* the first byte of the element. For string types (UTF8 and byte
* strings), the pointer will point to the first byte of the string's value. For container types
* (structures, arrays and paths), the pointer will point to the first member element within the
* container. For all other types, the pointer will point to the byte immediately after the element's
* encoding.
*
* @return A pointer into underlying input buffer that corresponds to the reader's current position.
*/
const uint8_t * GetReadPoint() const { return mReadPoint; }
/**
* Advances the TLVReader object to immediately after the current TLV element.
*
* The Skip() method positions the reader object immediately @em 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.
*
* @retval #CHIP_NO_ERROR If the reader was successfully positioned on a new element.
* @retval #CHIP_END_OF_TLV If no further elements are available.
* @retval #CHIP_ERROR_TLV_UNDERRUN If the underlying TLV encoding ended prematurely.
* @retval #CHIP_ERROR_INVALID_TLV_ELEMENT
* If the reader encountered an invalid or unsupported TLV
* element type.
* @retval #CHIP_ERROR_INVALID_TLV_TAG If the reader encountered a TLV tag in an invalid context.
* @retval other Other CHIP or platform error codes returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR Skip();
/**
* Position the destination reader on the next element with the given tag within this reader's current container context
*
* @param[in] tagInApiForm The destination context tag value
* @param[in] destReader The destination TLV reader value that was located by given tag
*
* @retval #CHIP_NO_ERROR If the reader was successfully positioned at the given tag
* @retval #CHIP_END_OF_TLV If the given tag cannot be found
* @retval other Other CHIP or platform error codes
*/
CHIP_ERROR FindElementWithTag(Tag tagInApiForm, TLVReader & destReader) const;
/**
* Count how many elements remain in the currently-open container. Will
* fail with CHIP_ERROR_INCORRECT_STATE if not currently in a container.
*
* @param[out] size On success, set to the number of items following the
* current reader position in the container.
*/
CHIP_ERROR CountRemainingInContainer(size_t * size) const;
/**
* 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 @p ImplicitProfileId property as the assumed profile id for the tag.
*
* By default, the @p ImplicitProfileId property is set to kProfileIdNotSpecified. When decoding
* TLV that contains implicitly-encoded tags, applications must set @p 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 @p ImplicitProfileId is set to
* kProfileIdNotSpecified, the reader will return a #CHIP_ERROR_UNKNOWN_IMPLICIT_TLV_TAG error.
*/
uint32_t ImplicitProfileId;
/**
* A pointer field that can be used for application-specific data.
*/
void * AppData;
protected:
Tag mElemTag;
uint64_t mElemLenOrVal;
TLVBackingStore * mBackingStore;
const uint8_t * mReadPoint;
const uint8_t * mBufEnd;
uint32_t mLenRead;
uint32_t mMaxLen;
TLVType mContainerType;
uint16_t mControlByte;
private:
bool mContainerOpen;
protected:
bool IsContainerOpen() const { return mContainerOpen; }
void SetContainerOpen(bool aContainerOpen) { mContainerOpen = aContainerOpen; }
CHIP_ERROR ReadElement();
void ClearElementState();
CHIP_ERROR SkipData();
CHIP_ERROR SkipToEndOfContainer();
CHIP_ERROR VerifyElement();
Tag ReadTag(TLVTagControl tagControl, const uint8_t *& p) const;
CHIP_ERROR EnsureData(CHIP_ERROR noDataErr);
CHIP_ERROR ReadData(uint8_t * buf, uint32_t len);
CHIP_ERROR GetElementHeadLength(uint8_t & elemHeadBytes) const;
TLVElementType ElementType() const;
};
/*
* A TLVReader that is backed by a scoped memory buffer that is owned by the reader
*/
class ScopedBufferTLVReader : public TLVReader
{
public:
/*
* Construct and initialize the reader by taking ownership of the provided scoped buffer.
*/
ScopedBufferTLVReader(Platform::ScopedMemoryBuffer<uint8_t> && buffer, size_t dataLen) { Init(std::move(buffer), dataLen); }
ScopedBufferTLVReader() {}
/*
* Initialize the reader by taking ownership of a passed in scoped buffer.
*/
void Init(Platform::ScopedMemoryBuffer<uint8_t> && buffer, size_t dataLen)
{
mBuffer = std::move(buffer);
TLVReader::Init(mBuffer.Get(), dataLen);
}
/*
* Take back the buffer owned by the reader and transfer its ownership to
* the provided buffer reference. This also re-initializes the reader with
* a null buffer to prevent further use of the reader.
*/
void TakeBuffer(Platform::ScopedMemoryBuffer<uint8_t> & buffer)
{
buffer = std::move(mBuffer);
TLVReader::Init(nullptr, 0);
}
private:
Platform::ScopedMemoryBuffer<uint8_t> mBuffer;
};
/**
* A TLVReader that is guaranteed to be backed by a single contiguous buffer.
* This allows it to expose some additional methods that allow consumers to
* directly access the data in that buffer in a safe way that is guaranteed to
* work as long as the reader object stays in scope.
*/
class ContiguousBufferTLVReader : public TLVReader
{
public:
ContiguousBufferTLVReader() : TLVReader() {}
/**
* Init with input buffer as ptr + length pair.
*/
void Init(const uint8_t * data, size_t dataLen) { TLVReader::Init(data, dataLen); }
/**
* Init with input buffer as ByteSpan.
*/
void Init(const ByteSpan & data) { Init(data.data(), data.size()); }
/**
* Init with input buffer as byte array.
*/
template <size_t N>
void Init(const uint8_t (&data)[N])
{
Init(data, N);
}
/**
* Allow opening a container, with a new ContiguousBufferTLVReader reading
* that container. See TLVReader::OpenContainer for details.
*/
CHIP_ERROR OpenContainer(ContiguousBufferTLVReader & containerReader);
/**
* Get the value of the current UTF8 string as a Span<const char> pointing
* into the TLV data. Consumers may need to copy the data elsewhere as
* needed (e.g. before releasing the reader and its backing buffer if they
* plan to use the data after that point).
*
* @param[out] data A Span<const char> representing the string data.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_WRONG_TLV_TYPE If the current element is not a TLV UTF8 string, or
* the reader is not positioned on an element.
* @retval #CHIP_ERROR_TLV_UNDERRUN If the underlying TLV encoding ended prematurely (i.e. the string length was "too big").
*
*/
CHIP_ERROR GetStringView(Span<const char> & data);
/**
* Get the value of the current octet string as a ByteSpan pointing into the
* TLV data. Consumers may need to copy the data elsewhere as needed
* (e.g. before releasing the reader and its backing buffer if they plan to
* use the data after that point).
*
* @param[out] data A ByteSpan representing the string data.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_WRONG_TLV_TYPE If the current element is not a TLV octet string, or
* the reader is not positioned on an element.
* @retval #CHIP_ERROR_TLV_UNDERRUN If the underlying TLV encoding ended prematurely (i.e. the string length was "too big").
*
*/
CHIP_ERROR GetByteView(ByteSpan & data);
};
/**
* Provides a memory efficient encoder for writing data in CHIP TLV format.
*
* TLVWriter implements a forward-only, stream-style encoder for CHIP 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 memory provided by
* a TLVBackingStore.
*/
class DLL_EXPORT TLVWriter
{
friend class TLVUpdater;
public:
/**
* Initializes a TLVWriter object to write into a single output buffer.
*
* @note Applications must call Finalize() on the writer before using the contents of the output
* buffer.
*
* @param[in] buf A pointer to the buffer into which TLV should be written.
* @param[in] maxLen The maximum number of bytes that should be written to the output buffer.
*
*/
void Init(uint8_t * buf, size_t maxLen);
/**
* Initializes a TLVWriter object to write into a single output buffer
* represented by a MutableSpan. See documentation for the two-arg Init()
* form for details.
*
*/
void Init(const MutableByteSpan & data) { Init(data.data(), data.size()); }
/**
* Initializes a TLVWriter object to write into a single output buffer
* represented by a fixed-size byte array. See documentation for the
* two-arg Init() form for details.
*
*/
template <size_t N>
void Init(uint8_t (&data)[N])
{
Init(data, N);
}
/**
* Initializes a TLVWriter object to write into memory provided by a TLVBackingStore.
*
* @note Applications must call Finalize() on the writer before using the contents of the buffer.
*
* @param[in] backingStore A TLVBackingStore providing memory, which must outlive the TVLWriter.
* @param[in] maxLen The maximum number of bytes that should be written to the output buffer.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval other Other error codes returned by TLVBackingStore::OnInit().
*/
CHIP_ERROR Init(TLVBackingStore & backingStore, uint32_t maxLen = UINT32_MAX);
/**
* 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 @p OpenContainer()).
*
* @retval #CHIP_NO_ERROR If the encoding was finalized successfully.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval other Other CHIP or platform-specific errors returned by the configured
* FinalizeBuffer() function.
*/
CHIP_ERROR Finalize();
/**
* Reserve some buffer for encoding future fields.
*
* @retval #CHIP_NO_ERROR Successfully reserved required buffer size.
* @retval #CHIP_ERROR_NO_MEMORY The reserved buffer size cannot fits into the remaining buffer size.
*/
CHIP_ERROR ReserveBuffer(uint32_t aBufferSize)
{
VerifyOrReturnError(mRemainingLen >= aBufferSize, CHIP_ERROR_NO_MEMORY);
mReservedSize += aBufferSize;
mRemainingLen -= aBufferSize;
return CHIP_NO_ERROR;
}
/**
* Release previously reserved buffer.
*
* @retval #CHIP_NO_ERROR Successfully released reserved buffer size.
* @retval #CHIP_ERROR_NO_MEMORY The released buffer is larger than previously reserved buffer size.
*/
CHIP_ERROR UnreserveBuffer(uint32_t aBufferSize)
{
VerifyOrReturnError(mReservedSize >= aBufferSize, CHIP_ERROR_NO_MEMORY);
mReservedSize -= aBufferSize;
mRemainingLen += aBufferSize;
return CHIP_NO_ERROR;
}
/**
* Encodes a TLV signed integer value.
*
* @param[in] tag The TLV tag to be encoded with the value, or @p 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().
* @param[in] v The value to be encoded.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_INVALID_TLV_TAG
* If the specified tag value is invalid or inappropriate in the context
* in which the value is being written.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR Put(Tag tag, int8_t v);
/**
* Encodes a TLV signed integer value.
*
* @param[in] tag The TLV tag to be encoded with the value, or @p 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().
* @param[in] v The value to be encoded.
* @param[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.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_INVALID_TLV_TAG
* If the specified tag value is invalid or inappropriate in the context
* in which the value is being written.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR Put(Tag tag, int8_t v, bool preserveSize);
/**
* @overload CHIP_ERROR TLVWriter::Put(Tag tag, int8_t v)
*/
CHIP_ERROR Put(Tag tag, int16_t v);
/**
* @overload CHIP_ERROR TLVWriter::Put(Tag tag, int8_t v, bool preserveSize)
*/
CHIP_ERROR Put(Tag tag, int16_t v, bool preserveSize);
/**
* @overload CHIP_ERROR TLVWriter::Put(Tag tag, int8_t v)
*/
CHIP_ERROR Put(Tag tag, int32_t v);
/**
* @overload CHIP_ERROR TLVWriter::Put(Tag tag, int8_t v, bool preserveSize)
*/
CHIP_ERROR Put(Tag tag, int32_t v, bool preserveSize);
/**
* @overload CHIP_ERROR TLVWriter::Put(Tag tag, int8_t v)
*/
CHIP_ERROR Put(Tag tag, int64_t v);
/**
* @overload CHIP_ERROR TLVWriter::Put(Tag tag, int8_t v, bool preserveSize)
*/
CHIP_ERROR Put(Tag tag, int64_t v, bool preserveSize);
/**
* Encodes a TLV unsigned integer value.
*
* @param[in] tag The TLV tag to be encoded with the value, or @p 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().
* @param[in] v The value to be encoded.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_INVALID_TLV_TAG
* If the specified tag value is invalid or inappropriate in the context
* in which the value is being written.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR Put(Tag tag, uint8_t v);
/**
* Encodes a TLV unsigned integer value.
*
* @param[in] tag The TLV tag to be encoded with the value, or @p 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().
* @param[in] v The value to be encoded.
* @param[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.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_INVALID_TLV_TAG
* If the specified tag value is invalid or inappropriate in the context
* in which the value is being written.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR Put(Tag tag, uint8_t v, bool preserveSize);
/**
* @overload CHIP_ERROR TLVWriter::Put(Tag tag, uint8_t v)
*/
CHIP_ERROR Put(Tag tag, uint16_t v);
/**
* @overload CHIP_ERROR TLVWriter::Put(Tag tag, uint8_t v, bool preserveSize)
*/
CHIP_ERROR Put(Tag tag, uint16_t v, bool preserveSize);
/**
* @overload CHIP_ERROR TLVWriter::Put(Tag tag, uint8_t v)
*/
CHIP_ERROR Put(Tag tag, uint32_t v);
/**
* @overload CHIP_ERROR TLVWriter::Put(Tag tag, uint8_t v, bool preserveSize)
*/
CHIP_ERROR Put(Tag tag, uint32_t v, bool preserveSize);
/**
* @overload CHIP_ERROR TLVWriter::Put(Tag tag, uint8_t v)
*/
CHIP_ERROR Put(Tag tag, uint64_t v);
/**
* @overload CHIP_ERROR TLVWriter::Put(Tag tag, uint8_t v, bool preserveSize)
*/
CHIP_ERROR Put(Tag tag, uint64_t v, bool preserveSize);
/**
* Encodes a TLV floating point value.
*
* @param[in] tag The TLV tag to be encoded with the value, or @p 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().
* @param[in] v The value to be encoded.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_INVALID_TLV_TAG
* If the specified tag value is invalid or inappropriate in the context
* in which the value is being written.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR Put(Tag tag, double v);
/**
* @overload CHIP_ERROR TLVWriter::Put(Tag tag, double v)
*/
CHIP_ERROR Put(Tag tag, float v);
/**
* Encodes a TLV byte string value using ByteSpan class.
*
* @param[in] tag The TLV tag to be encoded with the value, or @p 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().
* @param[in] data A ByteSpan object containing the bytes string to be encoded.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_INVALID_TLV_TAG
* If the specified tag value is invalid or inappropriate in the context
* in which the value is being written.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR Put(Tag tag, ByteSpan data);
/**
* static_cast to enumerations' underlying type when data is an enumeration.
*/
template <typename T, typename = std::enable_if_t<std::is_enum<T>::value>>
CHIP_ERROR Put(Tag tag, T data)
{
return Put(tag, to_underlying(data));
}
/**
*
* Encodes an unsigned integer with bits corresponding to the flags set when data is a BitFlags
*/
template <typename T>
CHIP_ERROR Put(Tag tag, BitFlags<T> data)
{
return Put(tag, data.Raw());
}
/**
*
* Encodes an unsigned integer with bits corresponding to the flags set when data is a BitMask
*/
template <typename T>
CHIP_ERROR Put(Tag tag, BitMask<T> data)
{
return Put(tag, data.Raw());
}
/**
* Encodes a TLV boolean value.
*
* @param[in] tag The TLV tag to be encoded with the value, or @p 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().
* @param[in] v The value to be encoded.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_INVALID_TLV_TAG
* If the specified tag value is invalid or inappropriate in the context
* in which the value is being written.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR PutBoolean(Tag tag, bool v);
/**
* @overload CHIP_ERROR TLVWriter::Put(Tag tag, bool v)
*/
CHIP_ERROR Put(Tag tag, bool v)
{
/*
* In TLV, boolean values are encoded as standalone tags without actual values, so we have a separate
* PutBoolean method.
*/
return PutBoolean(tag, v);
}
/**
* Encodes a TLV byte string value.
*
* @param[in] tag The TLV tag to be encoded with the value, or @p 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().
* @param[in] buf A pointer to a buffer containing the bytes string to be encoded.
* @param[in] len The number of bytes to be encoded.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_INVALID_TLV_TAG
* If the specified tag value is invalid or inappropriate in the context
* in which the value is being written.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR PutBytes(Tag tag, const uint8_t * buf, uint32_t len);
/**
* Encodes a TLV UTF8 string value.
*
* @param[in] tag The TLV tag to be encoded with the value, or @p 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().
* @param[in] buf A pointer to the null-terminated UTF-8 string to be encoded.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_INVALID_TLV_TAG
* If the specified tag value is invalid or inappropriate in the context
* in which the value is being written.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR PutString(Tag tag, const char * buf);
/**
* Encodes a TLV UTF8 string value.
*
* @param[in] tag The TLV tag to be encoded with the value, or @p 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().
* @param[in] buf A pointer to the UTF-8 string to be encoded.
* @param[in] len The length (in bytes) of the string to be encoded.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_INVALID_TLV_TAG
* If the specified tag value is invalid or inappropriate in the context
* in which the value is being written.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR PutString(Tag tag, const char * buf, uint32_t len);
/**
* Encodes a TLV UTF8 string value that's passed in as a Span.
*
* @param[in] tag The TLV tag to be encoded with the value, or @p 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().
* @param[in] str A Span containing a pointer and a length of the string to be encoded.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_INVALID_TLV_TAG
* If the specified tag value is invalid or inappropriate in the context
* in which the value is being written.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR PutString(Tag tag, Span<const char> str);
/**
* @brief
* 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, the function will allocate a
* temporary buffer to hold the output, using Platform::MemoryAlloc().
*
* @param[in] tag The TLV tag to be encoded with the value, or @p
* 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().
*
* @param[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.
*
* @param[in] ... A list of arguments to be formatted in the output value
* according to fmt.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
*
* @retval other If underlying calls to TLVWriter methods --
* `WriteElementHead` or `GetNewBuffer` -- failed, their
* error is immediately forwarded up the call stack.
*/
// The ENFORCE_FORMAT args are "off by one" because this is a class method,
// with an implicit "this" as first arg.
CHIP_ERROR PutStringF(Tag tag, const char * fmt, ...) ENFORCE_FORMAT(3, 4);
/**
* @brief
* 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, the function will allocate a
* temporary buffer to hold the output, using Platform::MemoryAlloc().
*
* @param[in] tag The TLV tag to be encoded with the value, or @p
* 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().
*
* @param[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.
*
* @param[in] ap A list of arguments to be formatted in the output value
* according to fmt.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
*
* @retval other If underlying calls to TLVWriter methods --
* `WriteElementHead` or `GetNewBuffer` -- failed, their
* error is immediately forwarded up the call stack.
*/
// The ENFORCE_FORMAT args are "off by one" because this is a class method,
// with an implicit "this" as first arg.
CHIP_ERROR VPutStringF(Tag tag, const char * fmt, va_list ap) ENFORCE_FORMAT(3, 0);
/**
* Encodes a TLV null value.
*
* @param[in] tag The TLV tag to be encoded with the value, or @p 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().
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_INVALID_TLV_TAG
* If the specified tag value is invalid or inappropriate in the context
* in which the value is being written.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR PutNull(Tag tag);
/**
* 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.
*
* @note This method requires the supplied TVLReader object to be reading from a single, contiguous
* input buffer that contains the entirety of the underlying TLV encoding. Supplying a reader in any
* other mode has undefined behavior.
*
* @param[in] reader A reference to a TLVReader object identifying a pre-encoded TLV
* element that should be copied.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_INCORRECT_STATE
* If the supplied reader is not positioned on an element.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_TLV_UNDERRUN
* If the underlying TLV encoding associated with the supplied reader ended
* prematurely.
* @retval #CHIP_ERROR_INVALID_TLV_ELEMENT
* If the supplied reader encountered an invalid or unsupported TLV element
* type.
* @retval #CHIP_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.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* GetNewBuffer() or FinalizeBuffer() functions, or by the GetNextBuffer()
* function associated with the reader object.
*
*/
CHIP_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 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 and contents as the input
* container, however the tag will be set to the specified argument. If the supplied element is a
* TLV container (structure, array or path), the entire contents of the container will be copied.
*
* @note This method requires the supplied TVLReader object to be reading from a single, contiguous
* input buffer that contains the entirety of the underlying TLV encoding. Supplying a reader in any
* other mode has undefined behavior.
*
* @param[in] tag The TLV tag to be encoded with the container, or @p 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().
* @param[in] reader A reference to a TLVReader object identifying a pre-encoded TLV
* element whose type and value should be copied.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_INCORRECT_STATE
* If the supplied reader is not positioned on an element.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_TLV_UNDERRUN
* If the underlying TLV encoding associated with the supplied reader ended
* prematurely.
* @retval #CHIP_ERROR_INVALID_TLV_ELEMENT
* If the supplied reader encountered an invalid or unsupported TLV element
* type.
* @retval #CHIP_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.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* GetNewBuffer() or FinalizeBuffer() functions, or by the GetNextBuffer()
* function associated with the reader object.
*
*/
CHIP_ERROR CopyElement(Tag tag, TLVReader & reader);
/**
* 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.
*
* @param[in] tag The TLV tag to be encoded with the container, or @p 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().
* @param[in] containerType The type of container to encode. Must be one of @p kTLVType_Structure,
* @p kTLVType_Array or @p kTLVType_List.
* @param[out] outerContainerType
* A reference to a TLVType value that will receive the context of the
* writer.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_WRONG_TLV_TYPE
* If the value specified for containerType is incorrect.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_INVALID_TLV_TAG
* If the specified tag value is invalid or inappropriate in the context
* in which the value is being written.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR StartContainer(Tag tag, TLVType containerType, 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.
*
* @note Any changes made to the configuration of the writer between the calls to StartContainer()
* and EndContainer() are NOT undone by the call to EndContainer(). For example, a change to the
* implicit profile id (@p ImplicitProfileId) will not be reversed when a container is ended. Thus
* it is the application's responsibility to adjust the configuration accordingly at the appropriate
* times.
*
* @param[in] outerContainerType
* The TLVType value that was returned by the StartContainer() method.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_INCORRECT_STATE
* If a corresponding StartContainer() call was not made.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR EndContainer(TLVType outerContainerType);
/**
* 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 <em>container writer</em>) 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:
*
* @li The implicit profile id (ImplicitProfileId)
* @li The application data pointer (AppData)
* @li The GetNewBuffer and FinalizeBuffer function pointers
*
* @note The StartContainer() method can be used as an alternative to OpenContainer() to write a
* container element without initializing a new writer object.
*
* @param[in] tag The TLV tag to be encoded with the container, or @p 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().
* @param[in] containerType The type of container to encode. Must be one of @p kTLVType_Structure,
* @p kTLVType_Array or @p kTLVType_List.
* @param[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.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_WRONG_TLV_TYPE
* If the value specified for containerType is incorrect.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_INVALID_TLV_TAG
* If the specified tag value is invalid or inappropriate in the context
* in which the value is being written.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR OpenContainer(Tag tag, TLVType containerType, 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.
*
* @param[in] containerWriter A reference to the TLVWriter object that was supplied to the
* OpenContainer() method.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_INCORRECT_STATE
* If the supplied container writer is not in the correct state.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If another container writer has been opened on the supplied
* container writer and not yet closed.
* @retval #CHIP_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.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack
* of memory.
* @retval other Other CHIP or platform-specific errors returned by the
* configured TLVBackingStore.
*
*/
CHIP_ERROR CloseContainer(TLVWriter & containerWriter);
/**
* 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.
*
* @param[in] tag The TLV tag to be encoded with the container, or @p 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().
* @param[in] containerType The type of container to encode. Must be one of @p kTLVType_Structure,
* @p kTLVType_Array or @p kTLVType_List.
* @param[in] data A pointer to a buffer containing zero of more encoded TLV elements that
* will become the members of the new container.
* @param[in] dataLen The number of bytes in the @p data buffer.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_WRONG_TLV_TYPE
* If the value specified for containerType is incorrect.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_INVALID_TLV_TAG
* If the specified tag value is invalid or inappropriate in the context
* in which the value is being written.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR PutPreEncodedContainer(Tag tag, TLVType containerType, const uint8_t * data, uint32_t dataLen);
/**
* 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.
*
* @note This method requires the supplied TVLReader object to be reading from a single, contiguous
* input buffer that contains the entirety of the underlying TLV encoding.
*
* @param[in] container A reference to a TLVReader object identifying the pre-encoded TLV
* container to be copied.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_INVALID_ARGUMENT
* If the supplied reader uses a TLVBackingStore rather than a simple buffer.
* @retval #CHIP_ERROR_INCORRECT_STATE
* If the supplied reader is not positioned on a container element.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_TLV_UNDERRUN
* If the underlying TLV encoding associated with the supplied reader ended
* prematurely.
* @retval #CHIP_ERROR_INVALID_TLV_ELEMENT
* If the supplied reader encountered an invalid or unsupported TLV element
* type.
* @retval #CHIP_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.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR CopyContainer(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.
*
* @note This method requires the supplied TVLReader object to be reading from a single, contiguous
* input buffer that contains the entirety of the underlying TLV encoding.
*
* @param[in] tag The TLV tag to be encoded with the container, or @p 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().
* @param[in] container A reference to a TLVReader object identifying a pre-encoded TLV
* container whose type and members should be copied.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_INVALID_ARGUMENT
* If the supplied reader uses a TLVBackingStore rather than a simple buffer.
* @retval #CHIP_ERROR_INCORRECT_STATE
* If the supplied reader is not positioned on a container element.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_TLV_UNDERRUN
* If the underlying TLV encoding associated with the supplied reader ended
* prematurely.
* @retval #CHIP_ERROR_INVALID_TLV_ELEMENT
* If the supplied reader encountered an invalid or unsupported TLV element
* type.
* @retval #CHIP_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.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR CopyContainer(Tag tag, TLVReader & container);
/**
* Encodes a TLV container element that contains member elements from a pre-encoded container
*
* The CopyContainer() method encodes a new TLV container element (a structure, array or path)
* containing a set of member elements taken from the contents of a supplied pre-encoded container.
* When the method is called, data in the supplied input buffer is parsed as a TLV container element
* an a new container is written that has 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.
*
* @param[in] tag The TLV tag to be encoded with the container, or @p 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().
* @param[in] encodedContainer A buffer containing a pre-encoded TLV container whose type and members
* should be copied.
* @param[in] encodedContainerLen The length in bytes of the pre-encoded container.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
* If a container writer has been opened on the current writer and not
* yet closed.
* @retval #CHIP_ERROR_TLV_UNDERRUN
* If the encoded container ended prematurely.
* @retval #CHIP_ERROR_INVALID_TLV_ELEMENT
* If the encoded container contained an invalid or unsupported TLV element type.
* @retval #CHIP_ERROR_INVALID_TLV_TAG
* If the encoded container contained 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.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL
* If writing the value would exceed the limit on the maximum number of
* bytes specified when the writer was initialized.
* @retval #CHIP_ERROR_NO_MEMORY
* If an attempt to allocate an output buffer failed due to lack of
* memory.
* @retval other Other CHIP or platform-specific errors returned by the configured
* TLVBackingStore.
*
*/
CHIP_ERROR CopyContainer(Tag tag, const uint8_t * encodedContainer, uint16_t encodedContainerLen);
/**
* 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.
*
* @return The TLVType of the current container, or kTLVType_NotSpecified if the TLVWriter is not
* writing elements within a container.
*/
TLVType GetContainerType() const { return mContainerType; }
/**
* Returns the total number of bytes written since the writer was initialized.
*
* @return Total number of bytes written since the writer was initialized.
*/
uint32_t GetLengthWritten() const { return mLenWritten; }
/**
* Returns the total remaining number of bytes for current tlv writer
*
* @return the total remaining number of bytes.
*/
uint32_t GetRemainingFreeLength() const { return mRemainingLen; }
/**
* 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 @p ImplicitProfileId member, the writer will encode the tag
* in implicit form, omitting the profile id in the process.
*
* By default, the @p ImplicitProfileId property is set to kProfileIdNotSpecified, which instructs
* the writer not to emit implicitly encoded tags. Applications can set @p 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.
*
* @note The value of the @p ImplicitProfileId member affects the encoding of profile-specific
* tags only; the encoding of context-specific tags is unchanged.
*/
uint32_t ImplicitProfileId;
/**
* A pointer field that can be used for application-specific data.
*/
void * AppData;
protected:
TLVBackingStore * mBackingStore;
uint8_t * mBufStart;
uint8_t * mWritePoint;
uint32_t mRemainingLen;
uint32_t mLenWritten;
uint32_t mMaxLen;
uint32_t mReservedSize;
TLVType mContainerType;
private:
bool mContainerOpen;
bool mCloseContainerReserved;
protected:
bool IsContainerOpen() const { return mContainerOpen; }
void SetContainerOpen(bool aContainerOpen) { mContainerOpen = aContainerOpen; }
enum
{
kEndOfContainerMarkerSize = 1, /**< Size of the EndOfContainer marker, used in reserving space. */
};
/**
* @brief
* Determine whether the container should reserve space for the
* CloseContainer symbol at the point of starting / opening the
* container.
*/
bool IsCloseContainerReserved() const { return mCloseContainerReserved; }
/**
* @brief
* Set whether the container should reserve the space for the
* CloseContainer symbol at the point of starting / opening the
* container.
*/
void SetCloseContainerReserved(bool aCloseContainerReserved) { mCloseContainerReserved = aCloseContainerReserved; }
#if CONFIG_HAVE_VCBPRINTF
static void CHIPTLVWriterPutcharCB(uint8_t c, void * appState);
#endif
CHIP_ERROR WriteElementHead(TLVElementType elemType, Tag tag, uint64_t lenOrVal);
CHIP_ERROR WriteElementWithData(TLVType type, Tag tag, const uint8_t * data, uint32_t dataLen);
CHIP_ERROR WriteData(const uint8_t * p, uint32_t len);
};
/*
* A TLVWriter that is backed by a scoped memory buffer that is owned by the writer.
*/
class ScopedBufferTLVWriter : public TLVWriter
{
public:
/*
* Construct and initialize the writer by taking ownership of the provided scoped buffer.
*/
ScopedBufferTLVWriter(Platform::ScopedMemoryBuffer<uint8_t> && buffer, size_t dataLen)
{
mBuffer = std::move(buffer);
Init(mBuffer.Get(), dataLen);
}
/*
* Finalize the writer and take back the buffer owned by the writer. This transfers its
* ownership to the provided buffer reference. This also re-initializes the writer with
* a null buffer to prevent further inadvertent use of the writer.
*/
CHIP_ERROR Finalize(Platform::ScopedMemoryBuffer<uint8_t> & buffer)
{
ReturnErrorOnFailure(TLVWriter::Finalize());
buffer = std::move(mBuffer);
Init(nullptr, 0);
return CHIP_NO_ERROR;
}
private:
Platform::ScopedMemoryBuffer<uint8_t> mBuffer;
};
/**
* Provides a unified Reader/Writer interface for editing/adding/deleting elements in TLV encoding.
*
* The TLVUpdater is a union of the TLVReader and TLVWriter objects and provides interface methods
* for editing/deleting data in an encoding as well as adding new elements to the TLV encoding. The
* TLVUpdater object essentially acts like two cursors, one for reading existing encoding and
* another for writing (either for copying over existing data or writing new data).
*
* Semantically, the TLVUpdater object functions like a union of the TLVReader and TLVWriter. The
* TLVUpdater methods have more or less similar meanings as similarly named counterparts in
* TLVReader/TLVWriter. Where there are differences in the semantics, the differences are clearly
* documented in the function's comment section in CHIPTLVUpdater.cpp.
*
* One particularly important note about the TLVUpdater's PutBytes() and PutString() methods is that
* it can leave the encoding in a corrupt state with only the element header written when an
* overflow occurs. Applications can call GetRemainingFreeLength() to make sure there is
* @em approximately enough free space to write the encoding. Note that GetRemainingFreeLength()
* only tells you the available free bytes and there is @em no way for the application to know the
* length of encoded data that gets written. In the event of an overflow, both PutBytes() and
* PutString() will return CHIP_ERROR_BUFFER_TOO_SMALL to the caller.
*
* Also, note that Next() method is overloaded to both skip the current element and also advance the
* internal reader to the next element. Because skipping already encoded elements requires changing
* the internal writer's free space state variables to account for the new freed space (made
* available by skipping), the application is expected to call Next() on the updater after a Get()
* method whose value it doesn't wish to write back (which is equivalent to skipping the current
* element).
*
* @note The application is expected to use the TLVUpdater object atomically from the time it calls
* Init() till it calls Finalize(). The same buffer should NOT be used with other TLVWriter objects.
*
* @note The TLVUpdater currently only supports single static buffers. TLVBackingStore is NOT supported.
*/
class DLL_EXPORT TLVUpdater
{
public:
/**
* Initialize a TLVUpdater object to edit a single input buffer.
*
* On calling this method, the TLV data in the buffer is moved to the end of the
* buffer and a private TLVReader object is initialized on this relocated
* buffer. A private TLVWriter object is also initialized on the free space that
* is now available at the beginning. Applications can use the TLVUpdater object
* to parse the TLV data and modify/delete existing elements or add new elements
* to the encoding.
*
* @param[in] buf A pointer to a buffer containing the TLV data to be edited.
* @param[in] dataLen The length of the TLV data in the buffer.
* @param[in] maxLen The total length of the buffer.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_INVALID_ARGUMENT If the buffer address is invalid.
* @retval #CHIP_ERROR_BUFFER_TOO_SMALL If the buffer is too small.
*
*/
CHIP_ERROR Init(uint8_t * buf, uint32_t dataLen, uint32_t maxLen);
/**
* Initialize a TLVUpdater object using a TLVReader.
*
* On calling this method, TLV data in the buffer pointed to by the TLVReader
* is moved from the current read point to the end of the buffer. A new
* private TLVReader object is initialized to read from this new location, while
* a new private TLVWriter object is initialized to write to the freed up buffer
* space.
*
* Note that if the TLVReader is already positioned "on" an element, it is first
* backed-off to the start of that element. Also note that this backing off
* works well with container elements, i.e., if the TLVReader was already used
* to call EnterContainer(), then there is nothing to back-off. But if the
* TLVReader was positioned on the container element and EnterContainer() was
* not yet called, then the TLVReader object is backed-off to the start of the
* container head.
*
* The input TLVReader object will be destroyed before returning and the
* application must not make use of the same on return.
*
* @param[in,out] aReader Reference to a TLVReader object that will be
* destroyed before returning.
* @param[in] freeLen The length of free space (in bytes) available
* in the pre-encoded data buffer.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_INVALID_ARGUMENT If the buffer address is invalid.
* @retval #CHIP_ERROR_NOT_IMPLEMENTED If reader was initialized on a chain
* of buffers.
*/
CHIP_ERROR Init(TLVReader & aReader, uint32_t freeLen);
CHIP_ERROR Finalize() { return mUpdaterWriter.Finalize(); }
// Common methods
/**
* Set the Implicit Profile ID for the TLVUpdater object.
*
* This method sets the implicit profile ID for the TLVUpdater object. When the
* updater is asked to encode a new element, if the profile ID of the tag
* associated with the new element matches the value of the @p profileId, the
* updater will encode the tag in implicit form, thereby omitting the profile ID
* in the process.
*
* @param[in] profileId The profile id of tags that should be encoded in
* implicit form.
*/
void SetImplicitProfileId(uint32_t profileId);
uint32_t GetImplicitProfileId() const { return mUpdaterReader.ImplicitProfileId; }
/**
* Copies the current element from input TLV to output TLV.
*
* The Move() method copies the current element on which the TLVUpdater's reader
* is positioned on, to the TLVUpdater's writer. The application should call
* Next() and position the TLVUpdater's reader on an element before calling this
* method. Just like the TLVReader::Next() method, if the reader is positioned
* on a container element at the time of the call, all the members of the
* container will be copied. If the reader is not positioned on any element,
* nothing changes on calling this method.
*
* @retval #CHIP_NO_ERROR If the TLVUpdater reader was
* successfully positioned on a new
* element.
* @retval #CHIP_END_OF_TLV If the TLVUpdater's reader is pointing
* to end of container.
* @retval #CHIP_ERROR_INVALID_TLV_ELEMENT
* If the TLVIpdater's reader is not
* positioned on a valid TLV element.
* @retval other Returns other error codes returned by
* TLVReader::Skip() method.
*
*/
CHIP_ERROR Move();
/**
* Move everything from the TLVUpdater's current read point till end of input
* TLV buffer over to output.
*
* This method supports moving everything from the TLVUpdater's current read
* point till the end of the reader buffer over to the TLVUpdater's writer.
*
* @note This method can be called with the TLVUpdater's reader positioned
* anywhere within the input TLV. The reader can also be positioned under
* multiple levels of nested containers and this method will still work.
*
* @note This method also changes the state of the TLVUpdater object to a state
* it would be in if the application had painstakingly parsed each element from
* the current read point till the end of the input encoding and copied them to
* the output TLV.
*/
void MoveUntilEnd();
/**
* Prepares a TLVUpdater object for reading elements of a container. It also
* encodes a start of container object in the output TLV.
*
* The EnterContainer() method prepares the current TLVUpdater 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 TLVUpdater's reader must be positioned on
* the container element. The method takes as an argument a reference to a
* TLVType value which will be used to save the context of the updater while it
* is reading the container.
*
* When the EnterContainer() method returns, the updater is positioned
* immediately @em before the first member of the container. Repeatedly calling
* Next() will advance the updater through the members of the collection until
* the end is reached, at which point the updater will return CHIP_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.
*
* @note This method implicitly encodes a start of container element in the
* output TLV buffer.
*
* @param[out] outerContainerType A reference to a TLVType value that will
* receive the context of the updater.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_INCORRECT_STATE If the TLVUpdater reader is not
* positioned on a container element.
* @retval other Any other CHIP or platform error code
* returned by TLVWriter::StartContainer()
* or TLVReader::EnterContainer().
*
*/
CHIP_ERROR EnterContainer(TLVType & outerContainerType);
/**
* Completes the reading of a TLV container element and encodes an end of TLV
* element in the output TLV.
*
* The ExitContainer() method restores the state of a TLVUpdater 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 TLVUpdater reader is positioned immediately
* before the first element that follows the container in the input TLV. From
* this point applications can call Next() to advance through any remaining
* elements.
*
* Once EnterContainer() has been called, applications can call ExitContainer()
* on the updater at any point in time, regardless of whether all elements in
* the underlying container have been read. Also, note that calling
* ExitContainer() before reading all the elements in the container, will result
* in the updated container getting truncated in the output TLV.
*
* @note Any changes made to the configuration of the updater between the calls
* to EnterContainer() and ExitContainer() are NOT undone by the call to
* ExitContainer(). For example, a change to the implicit profile id
* (@p ImplicitProfileId) will not be reversed when a container is exited. Thus
* it is the application's responsibility to adjust the configuration
* accordingly at the appropriate times.
*
* @param[in] outerContainerType The TLVType value that was returned by
* the EnterContainer() method.
*
* @retval #CHIP_NO_ERROR If the method succeeded.
* @retval #CHIP_ERROR_TLV_UNDERRUN If the underlying TLV encoding ended
* prematurely.
* @retval #CHIP_ERROR_INVALID_TLV_ELEMENT
* If the updater encountered an invalid or
* unsupported TLV element type.
* @retval #CHIP_ERROR_INVALID_TLV_TAG If the updater encountered a TLV tag in
* an invalid context.
* @retval other Any other CHIP or platform error code
* returned by TLVWriter::EndContainer() or
* TLVReader::ExitContainer().
*
*/
CHIP_ERROR ExitContainer(TLVType outerContainerType);
void GetReader(TLVReader & containerReader) { containerReader = mUpdaterReader; }
// Reader methods
/**
* Skip the current element and advance the TLVUpdater object to the next
* element in the input TLV.
*
* The Next() method skips the current element in the input TLV and advances the
* TLVUpdater's reader to the next element 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 it 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 it 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 @em 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 #CHIP_END_OF_TLV error and the position of
* the reader will remain unchanged.
*
* @note The Next() method implicitly skips the current element. Hence, the
* TLVUpdater's private writer state variables will be adjusted to account for
* the new freed space (made available by skipping). This means that the
* application is expected to call Next() on the TLVUpdater object after a Get()
* whose value the application does @em not write back (which from the
* TLVUpdater's view is equivalent to skipping that element).
*
* @note Applications are also expected to call Next() when they are at the end
* of a container, and want to add new elements there. This is particularly
* important in situations where there is a fixed schema. Applications that have
* fixed schemas and know where the container end is cannot just add new
* elements at the end, because the TLVUpdater writer's state will not reflect
* the correct free space available for the Put() operation. Hence, applications
* must call Next() (and possibly also test for CHIP_END_OF_TLV) before adding
* elements at the end of a container.
*
* @retval #CHIP_NO_ERROR If the TLVUpdater reader was
* successfully positioned on a new
* element.
* @retval other Returns the CHIP or platform error
* codes returned by the TLVReader::Skip()
* and TLVReader::Next() method.
*
*/
CHIP_ERROR Next();
CHIP_ERROR Get(bool & v) { return mUpdaterReader.Get(v); }
CHIP_ERROR Get(int8_t & v) { return mUpdaterReader.Get(v); }
CHIP_ERROR Get(int16_t & v) { return mUpdaterReader.Get(v); }
CHIP_ERROR Get(int32_t & v) { return mUpdaterReader.Get(v); }
CHIP_ERROR Get(int64_t & v) { return mUpdaterReader.Get(v); }
CHIP_ERROR Get(uint8_t & v) { return mUpdaterReader.Get(v); }
CHIP_ERROR Get(uint16_t & v) { return mUpdaterReader.Get(v); }
CHIP_ERROR Get(uint32_t & v) { return mUpdaterReader.Get(v); }
CHIP_ERROR Get(uint64_t & v) { return mUpdaterReader.Get(v); }
CHIP_ERROR Get(float & v) { return mUpdaterReader.Get(v); }
CHIP_ERROR Get(double & v) { return mUpdaterReader.Get(v); }
CHIP_ERROR Get(ByteSpan & v) { return mUpdaterReader.Get(v); }
CHIP_ERROR Get(CharSpan & v) { return mUpdaterReader.Get(v); }
CHIP_ERROR GetBytes(uint8_t * buf, uint32_t bufSize) { return mUpdaterReader.GetBytes(buf, bufSize); }
CHIP_ERROR DupBytes(uint8_t *& buf, uint32_t & dataLen) { return mUpdaterReader.DupBytes(buf, dataLen); }
CHIP_ERROR GetString(char * buf, uint32_t bufSize) { return mUpdaterReader.GetString(buf, bufSize); }
CHIP_ERROR DupString(char *& buf) { return mUpdaterReader.DupString(buf); }
TLVType GetType() const { return mUpdaterReader.GetType(); }
Tag GetTag() const { return mUpdaterReader.GetTag(); }
uint32_t GetLength() const { return mUpdaterReader.GetLength(); }
CHIP_ERROR GetDataPtr(const uint8_t *& data) { return mUpdaterReader.GetDataPtr(data); }
CHIP_ERROR VerifyEndOfContainer() { return mUpdaterReader.VerifyEndOfContainer(); }
TLVType GetContainerType() const { return mUpdaterReader.GetContainerType(); }
uint32_t GetLengthRead() const { return mUpdaterReader.GetLengthRead(); }
uint32_t GetRemainingLength() const { return mUpdaterReader.GetRemainingLength(); }
// Writer methods
CHIP_ERROR Put(Tag tag, int8_t v) { return mUpdaterWriter.Put(tag, v); }
CHIP_ERROR Put(Tag tag, int16_t v) { return mUpdaterWriter.Put(tag, v); }
CHIP_ERROR Put(Tag tag, int32_t v) { return mUpdaterWriter.Put(tag, v); }
CHIP_ERROR Put(Tag tag, int64_t v) { return mUpdaterWriter.Put(tag, v); }
CHIP_ERROR Put(Tag tag, uint8_t v) { return mUpdaterWriter.Put(tag, v); }
CHIP_ERROR Put(Tag tag, uint16_t v) { return mUpdaterWriter.Put(tag, v); }
CHIP_ERROR Put(Tag tag, uint32_t v) { return mUpdaterWriter.Put(tag, v); }
CHIP_ERROR Put(Tag tag, uint64_t v) { return mUpdaterWriter.Put(tag, v); }
CHIP_ERROR Put(Tag tag, int8_t v, bool preserveSize) { return mUpdaterWriter.Put(tag, v, preserveSize); }
CHIP_ERROR Put(Tag tag, int16_t v, bool preserveSize) { return mUpdaterWriter.Put(tag, v, preserveSize); }
CHIP_ERROR Put(Tag tag, int32_t v, bool preserveSize) { return mUpdaterWriter.Put(tag, v, preserveSize); }
CHIP_ERROR Put(Tag tag, int64_t v, bool preserveSize) { return mUpdaterWriter.Put(tag, v, preserveSize); }
CHIP_ERROR Put(Tag tag, uint8_t v, bool preserveSize) { return mUpdaterWriter.Put(tag, v, preserveSize); }
CHIP_ERROR Put(Tag tag, uint16_t v, bool preserveSize) { return mUpdaterWriter.Put(tag, v, preserveSize); }
CHIP_ERROR Put(Tag tag, uint32_t v, bool preserveSize) { return mUpdaterWriter.Put(tag, v, preserveSize); }
CHIP_ERROR Put(Tag tag, uint64_t v, bool preserveSize) { return mUpdaterWriter.Put(tag, v, preserveSize); }
CHIP_ERROR Put(Tag tag, float v) { return mUpdaterWriter.Put(tag, v); }
CHIP_ERROR Put(Tag tag, double v) { return mUpdaterWriter.Put(tag, v); }
CHIP_ERROR PutBoolean(Tag tag, bool v) { return mUpdaterWriter.PutBoolean(tag, v); }
CHIP_ERROR PutNull(Tag tag) { return mUpdaterWriter.PutNull(tag); }
CHIP_ERROR PutBytes(Tag tag, const uint8_t * buf, uint32_t len) { return mUpdaterWriter.PutBytes(tag, buf, len); }
CHIP_ERROR PutString(Tag tag, const char * buf) { return mUpdaterWriter.PutString(tag, buf); }
CHIP_ERROR PutString(Tag tag, const char * buf, uint32_t len) { return mUpdaterWriter.PutString(tag, buf, len); }
CHIP_ERROR CopyElement(TLVReader & reader) { return mUpdaterWriter.CopyElement(reader); }
CHIP_ERROR CopyElement(Tag tag, TLVReader & reader) { return mUpdaterWriter.CopyElement(tag, reader); }
CHIP_ERROR StartContainer(Tag tag, TLVType containerType, TLVType & outerContainerType)
{
return mUpdaterWriter.StartContainer(tag, containerType, outerContainerType);
}
CHIP_ERROR EndContainer(TLVType outerContainerType) { return mUpdaterWriter.EndContainer(outerContainerType); }
uint32_t GetLengthWritten() { return mUpdaterWriter.GetLengthWritten(); }
uint32_t GetRemainingFreeLength() const { return mUpdaterWriter.mRemainingLen; }
private:
void AdjustInternalWriterFreeSpace();
TLVWriter mUpdaterWriter;
TLVReader mUpdaterReader;
const uint8_t * mElementStartAddr;
};
/**
* Provides an interface for TLVReader or TLVWriter to use memory other than a simple contiguous buffer.
*/
class DLL_EXPORT TLVBackingStore
{
public:
virtual ~TLVBackingStore() {}
/**
* A function to provide a backing store's initial start position and data length to a reader.
*
* @param[in] reader A reference to the TLVReader object that is requesting input data.
* @param[out] bufStart A reference to a data pointer. On exit, bufStart is expected to point
* to the first byte of TLV data to be parsed.
* @param[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.
*
* @retval #CHIP_NO_ERROR If the function successfully produced TLV data.
* @retval other Other CHIP or platform-specific error codes indicating that an error
* occurred preventing the function from producing the requested data.
*/
virtual CHIP_ERROR OnInit(TLVReader & reader, const uint8_t *& bufStart, uint32_t & bufLen) = 0;
/**
* A function that can be used to retrieve additional TLV data to be parsed.
*
* 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.
*
* @param[in] reader A reference to the TLVReader object that is requesting input data.
* @param[in,out] bufStart A reference to a data pointer. On entry to the function, @p 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.
* @param[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.
*
* @retval #CHIP_NO_ERROR If the function successfully produced more TLV data, or the end of
* the input data was reached (@p bufLen should be set to 0 in this case).
* @retval other Other CHIP or platform-specific error codes indicating that an error
* occurred preventing the function from producing the requested data.
*/
virtual CHIP_ERROR GetNextBuffer(TLVReader & reader, const uint8_t *& bufStart, uint32_t & bufLen) = 0;
/**
* A function to provide a backing store's initial start position and data length to a writer.
*
* @param[in] writer A reference to the TLVWriter object that is requesting new buffer
* space.
* @param[out] bufStart A reference to a data pointer. On exit, @p bufStart is expected to
* point to the beginning of the new output buffer.
* @param[out] bufLen A reference to an unsigned integer. On exit, @p bufLen is expected
* to contain the maximum number of bytes that can be written to the
* new output buffer.
*
* @retval #CHIP_NO_ERROR If the function was able to supply buffer space for the writer.
* @retval other Other CHIP or platform-specific error codes indicating that an error
* occurred preventing the function from producing buffer space.
*/
virtual CHIP_ERROR OnInit(TLVWriter & writer, uint8_t *& bufStart, uint32_t & bufLen) = 0;
/**
* A function that supplies new output buffer space to a TLVWriter.
*
* 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.
*
* @param[in] writer A reference to the TLVWriter object that is requesting new buffer
* space.
* @param[in,out] bufStart A reference to a data pointer. On entry to the function, @p bufStart
* points the beginning of the current output buffer. On exit, @p 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.
* @param[in,out] bufLen A reference to an unsigned integer. On entry to the function,
* @p bufLen contains the number of byte of @em unused space in the
* current buffer. On exit, @p bufLen is expected to contain the maximum
* number of bytes that can be written to the new output buffer.
*
* @retval #CHIP_NO_ERROR If the function was able to supply more buffer space for the writer.
* @retval other Other CHIP or platform-specific error codes indicating that an error
* occurred preventing the function from producing additional buffer
* space.
*/
virtual CHIP_ERROR GetNewBuffer(TLVWriter & writer, uint8_t *& bufStart, uint32_t & bufLen) = 0;
/**
* 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.
*
* @param[in] writer A reference to the TLVWriter object that is being finalized.
* @param[in,out] bufStart A pointer to the beginning of the current (and final) output buffer.
* @param[in,out] bufLen The number of bytes contained in the buffer pointed to by @p bufStart.
*
* @retval #CHIP_NO_ERROR If finalization was successful.
* @retval other Other CHIP or platform-specific error codes indicating that an error
* occurred during finalization.
*
*/
virtual CHIP_ERROR FinalizeBuffer(TLVWriter & writer, uint8_t * bufStart, uint32_t bufLen) = 0;
};
constexpr size_t EstimateStructOverhead()
{
// The struct itself has a control byte and an end-of-struct marker.
return 2;
}
template <typename... FieldSizes>
constexpr size_t EstimateStructOverhead(size_t firstFieldSize, FieldSizes... otherFields)
{
// Estimate 4 bytes of overhead per field. This can happen for a large
// octet string field: 1 byte control, 1 byte context tag, 2 bytes
// length.
return firstFieldSize + 4u + EstimateStructOverhead(otherFields...);
}
} // namespace TLV
} // namespace chip