Line data    Source code

       1             : /*
       2             :  *
       3             :  *    Copyright (c) 2020-2023 Project CHIP Authors
       4             :  *    Copyright (c) 2013-2017 Nest Labs, Inc.
       5             :  *
       6             :  *    Licensed under the Apache License, Version 2.0 (the "License");
       7             :  *    you may not use this file except in compliance with the License.
       8             :  *    You may obtain a copy of the License at
       9             :  *
      10             :  *        http://www.apache.org/licenses/LICENSE-2.0
      11             :  *
      12             :  *    Unless required by applicable law or agreed to in writing, software
      13             :  *    distributed under the License is distributed on an "AS IS" BASIS,
      14             :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      15             :  *    See the License for the specific language governing permissions and
      16             :  *    limitations under the License.
      17             :  */
      18             : 
      19             : /**
      20             :  *    @file
      21             :  *      This file contains definitions for working with data encoded in CHIP TLV format.
      22             :  *
      23             :  *      CHIP TLV (Tag-Length-Value) is a generalized encoding method for simple structured data. It
      24             :  *      shares many properties with the commonly used JSON serialization format while being considerably
      25             :  *      more compact over the wire.
      26             :  */
      27             : 
      28             : #pragma once
      29             : 
      30             : #include "TLVCommon.h"
      31             : 
      32             : #include "TLVReader.h"
      33             : #include "TLVWriter.h"
      34             : 
      35             : /**
      36             :  * @namespace chip::TLV
      37             :  *
      38             :  * Definitions for working with data encoded in CHIP TLV format.
      39             :  *
      40             :  * CHIP TLV is a generalized encoding method for simple structured data. It shares many properties
      41             :  * with the commonly used JSON serialization format while being considerably more compact over the wire.
      42             :  */
      43             : 
      44             : namespace chip {
      45             : namespace TLV {
      46             : 
      47             : /**
      48             :  * Provides an interface for TLVReader or TLVWriter to use memory other than a simple contiguous buffer.
      49             :  */
      50             : class DLL_EXPORT TLVBackingStore
      51             : {
      52             : public:
      53       17063 :     virtual ~TLVBackingStore() {}
      54             :     /**
      55             :      * A function to provide a backing store's initial start position and data length to a reader.
      56             :      *
      57             :      * @param[in]       reader          A reference to the TLVReader object that is requesting input data.
      58             :      * @param[out]      bufStart        A reference to a data pointer. On exit, bufStart is expected to point
      59             :      *                                  to the first byte of TLV data to be parsed.
      60             :      * @param[out]      bufLen          A reference to an unsigned integer that the function must set to
      61             :      *                                  the number of TLV data bytes being returned.  If the end of the
      62             :      *                                  input TLV data has been reached, the function should set this value
      63             :      *                                  to 0.
      64             :      *
      65             :      * @retval #CHIP_NO_ERROR           If the function successfully produced TLV data.
      66             :      * @retval other                    Other CHIP or platform-specific error codes indicating that an error
      67             :      *                                  occurred preventing the function from producing the requested data.
      68             :      */
      69             :     virtual CHIP_ERROR OnInit(TLVReader & reader, const uint8_t *& bufStart, uint32_t & bufLen) = 0;
      70             : 
      71             :     /**
      72             :      * A function that can be used to retrieve additional TLV data to be parsed.
      73             :      *
      74             :      * When called, the function is expected to produce additional data for the reader to parse or signal
      75             :      * the reader that no more data is available.
      76             :      *
      77             :      * @param[in]       reader          A reference to the TLVReader object that is requesting input data.
      78             :      * @param[in,out]   bufStart        A reference to a data pointer. On entry to the function, @p bufStart
      79             :      *                                  points to one byte beyond the last TLV data byte consumed by the
      80             :      *                                  reader.  On exit, bufStart is expected to point to the first byte
      81             :      *                                  of new TLV data to be parsed.  The new pointer value can be within
      82             :      *                                  the same buffer as the previously consumed data, or it can point
      83             :      *                                  to an entirely new buffer.
      84             :      * @param[out]      bufLen          A reference to an unsigned integer that the function must set to
      85             :      *                                  the number of TLV data bytes being returned.  If the end of the
      86             :      *                                  input TLV data has been reached, the function should set this value
      87             :      *                                  to 0.
      88             :      *
      89             :      * @retval #CHIP_NO_ERROR           If the function successfully produced more TLV data, or the end of
      90             :      *                                  the input data was reached (@p bufLen should be set to 0 in this case).
      91             :      * @retval other                    Other CHIP or platform-specific error codes indicating that an error
      92             :      *                                  occurred preventing the function from producing the requested data.
      93             :      */
      94             :     virtual CHIP_ERROR GetNextBuffer(TLVReader & reader, const uint8_t *& bufStart, uint32_t & bufLen) = 0;
      95             : 
      96             :     /**
      97             :      * A function to provide a backing store's initial start position and data length to a writer.
      98             :      *
      99             :      * @param[in]       writer          A reference to the TLVWriter object that is requesting new buffer
     100             :      *                                  space.
     101             :      * @param[out]      bufStart        A reference to a data pointer. On exit, @p bufStart is expected to
     102             :      *                                  point to the beginning of the new output buffer.
     103             :      * @param[out]      bufLen          A reference to an unsigned integer. On exit, @p bufLen is expected
     104             :      *                                  to contain the maximum number of bytes that can be written to the
     105             :      *                                  new output buffer.
     106             :      *
     107             :      * @retval #CHIP_NO_ERROR           If the function was able to supply buffer space for the writer.
     108             :      * @retval other                    Other CHIP or platform-specific error codes indicating that an error
     109             :      *                                  occurred preventing the function from producing buffer space.
     110             :      */
     111             :     virtual CHIP_ERROR OnInit(TLVWriter & writer, uint8_t *& bufStart, uint32_t & bufLen) = 0;
     112             : 
     113             :     /**
     114             :      * A function that supplies new output buffer space to a TLVWriter.
     115             :      *
     116             :      * The function is expected to return a pointer to a memory location where new data should be written,
     117             :      * along with an associated maximum length. The function can supply write space either by allocating
     118             :      * a new buffer to hold the data or by clearing out previously written data from an existing buffer.
     119             :      *
     120             :      * @param[in]       writer          A reference to the TLVWriter object that is requesting new buffer
     121             :      *                                  space.
     122             :      * @param[in,out]   bufStart        A reference to a data pointer. On entry to the function, @p bufStart
     123             :      *                                  points the beginning of the current output buffer.  On exit, @p bufStart
     124             :      *                                  is expected to point to the beginning of the new output buffer.
     125             :      *                                  The new pointer value can be the same as the previous value (e.g.
     126             :      *                                  if the function copied the existing data elsewhere), or it can point
     127             :      *                                  to an entirely new location.
     128             :      * @param[in,out]   bufLen          A reference to an unsigned integer. On entry to the function,
     129             :      *                                  @p bufLen contains the number of byte of @em unused space in the
     130             :      *                                  current buffer.  On exit, @p bufLen is expected to contain the maximum
     131             :      *                                  number of bytes that can be written to the new output buffer.
     132             :      *
     133             :      * @retval #CHIP_NO_ERROR          If the function was able to supply more buffer space for the writer.
     134             :      * @retval other                    Other CHIP or platform-specific error codes indicating that an error
     135             :      *                                  occurred preventing the function from producing additional buffer
     136             :      *                                  space.
     137             :      */
     138             :     virtual CHIP_ERROR GetNewBuffer(TLVWriter & writer, uint8_t *& bufStart, uint32_t & bufLen) = 0;
     139             : 
     140             :     /**
     141             :      * A function used to perform finalization of the output from a TLVWriter object.
     142             :      *
     143             :      * Functions of this type are called when a TLVWriter's Finalize() method is called. The function is
     144             :      * expected to perform any necessary clean-up or finalization related to consuming the output of the
     145             :      * writer object. Examples of this include such things as recording the final length of the encoding,
     146             :      * or closing a file descriptor.
     147             :      *
     148             :      * @param[in]       writer          A reference to the TLVWriter object that is being finalized.
     149             :      * @param[in,out]   bufStart        A pointer to the beginning of the current (and final) output buffer.
     150             :      * @param[in,out]   bufLen          The number of bytes contained in the buffer pointed to by @p bufStart.
     151             :      *
     152             :      * @retval #CHIP_NO_ERROR           If finalization was successful.
     153             :      * @retval other                    Other CHIP or platform-specific error codes indicating that an error
     154             :      *                                  occurred during finalization.
     155             :      *
     156             :      */
     157             :     virtual CHIP_ERROR FinalizeBuffer(TLVWriter & writer, uint8_t * bufStart, uint32_t bufLen) = 0;
     158             : 
     159             :     /**
     160             :      * Returns whether call to GetNewBuffer will always fail.
     161             :      *
     162             :      * There are some implementations of TLVBackingStore that provide some level of utility, such as access to pool
     163             :      * of particular kind of buffer and/or reserving space for headers. Some implementation allow the caller to
     164             :      * specify that they only intend to use a single buffer. It is useful for TLVWriter to know if this is the case.
     165             :      *
     166             :      */
     167           0 :     virtual bool GetNewBufferWillAlwaysFail() { return false; }
     168             : };
     169             : 
     170             : } // namespace TLV
     171             : } // namespace chip