| /* |
| * |
| * Copyright (c) 2020-2023 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/DataModelTypes.h> |
| #include <lib/core/Optional.h> |
| |
| #include "TLVCommon.h" |
| |
| #include "TLVWriter.h" |
| |
| /** |
| * @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 { |
| |
| /** |
| * 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 Localized String Identifier contained in the current element.. |
| * |
| * The method takes what's after the first Information Separator 1 <IS1>, and until end of string |
| * or second <IS1>, and return the hex-decoded string identifier, if one was there. |
| * |
| * @param[out] lsid Optional Localized String Identifier. Returns empty |
| * if the value is not found or it was invalidly encoded. |
| * |
| * @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. |
| * @retval #CHIP_ERROR_INVALID_TLV_ELEMENT If the Localized String Identifier is malformed. |
| */ |
| CHIP_ERROR Get(Optional<LocalizedStringIdentifier> & lsid); |
| |
| /** |
| * 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); |
| }; |
| |
| } // namespace TLV |
| } // namespace chip |
