src/lib/core/TLVBackingStore.h - third_party/github/project-chip/connectedhomeip - Git at Google

 /*
  *
  *    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
	/*
	*
	* 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