| /* |
| * |
| * 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 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; |
| }; |
| |
| } // namespace TLV |
| } // namespace chip |