| /* |
| * |
| * 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 "TLVCommon.h" |
| |
| #include "TLVReader.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 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 TLVUpdater.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; |
| }; |
| |
| } // namespace TLV |
| } // namespace chip |
