src/system/TLVPacketBufferBackingStore.h

   1 /*
   2  *
   3  *    Copyright (c) 2021 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 an implementation of TLVBackingStore using PacketBuffers.
  22  */
  23
  24 #pragma once
  25
  26 #include <core/CHIPTLV.h>
  27 #include <system/SystemPacketBuffer.h>
  28
  29 #include <utility>
  30
  31 namespace chip {
  32 namespace System {
  33
  34 /**
  35  * An implementation of TLVBackingStore using PacketBuffers.
  36  */
  37 class TLVPacketBufferBackingStore : public chip::TLV::TLVBackingStore
  38 {
  39 public:
  40     TLVPacketBufferBackingStore() : mHeadBuffer(nullptr), mCurrentBuffer(nullptr), mUseChainedBuffers(false) {}
  41     TLVPacketBufferBackingStore(chip::System::PacketBufferHandle && buffer, bool useChainedBuffers = false)
  42     {
  43         Init(std::move(buffer), useChainedBuffers);
  44     }
  45     virtual ~TLVPacketBufferBackingStore() {}
  46
  47     /**
  48      * Take ownership of a backing packet buffer.
  49      *
  50      * @param[in]    buffer  A handle to a packet buffer, to be used as backing store for a TLV class.
  51      * @param[in]    useChainedBuffers
  52      *                       If true, advance to the next buffer in the chain once all data or space
  53      *                       in the current buffer has been consumed; a write will allocate new
  54      *                       packet buffers if necessary.
  55      *
  56      * @note This must take place before initializing a TLV class with this backing store.
  57      */
  58     void Init(chip::System::PacketBufferHandle && buffer, bool useChainedBuffers = false)
  59     {
  60         mHeadBuffer        = std::move(buffer);
  61         mCurrentBuffer     = mHeadBuffer.Retain();
  62         mUseChainedBuffers = useChainedBuffers;
  63     }
  64     void Adopt(chip::System::PacketBufferHandle && buffer) { Init(std::move(buffer), mUseChainedBuffers); }
  65
  66     /**
  67      * Release ownership of the backing packet buffer.
  68      *
  69      * @note TLV operations must no longer be performed on this store.
  70      */
  71     CHECK_RETURN_VALUE chip::System::PacketBufferHandle Release()
  72     {
  73         mCurrentBuffer = nullptr;
  74         return std::move(mHeadBuffer);
  75     }
  76
  77     // TLVBackingStore overrides:
  78     CHIP_ERROR OnInit(chip::TLV::TLVReader & reader, const uint8_t *& bufStart, uint32_t & bufLen) override;
  79     CHIP_ERROR GetNextBuffer(chip::TLV::TLVReader & reader, const uint8_t *& bufStart, uint32_t & bufLen) override;
  80     CHIP_ERROR OnInit(chip::TLV::TLVWriter & writer, uint8_t *& bufStart, uint32_t & bufLen) override;
  81     CHIP_ERROR GetNewBuffer(chip::TLV::TLVWriter & writer, uint8_t *& bufStart, uint32_t & bufLen) override;
  82     CHIP_ERROR FinalizeBuffer(chip::TLV::TLVWriter & writer, uint8_t * bufStart, uint32_t bufLen) override;
  83
  84 protected:
  85     chip::System::PacketBufferHandle mHeadBuffer;
  86     chip::System::PacketBufferHandle mCurrentBuffer;
  87     bool mUseChainedBuffers;
  88 };
  89
  90 class DLL_EXPORT PacketBufferTLVReader : public chip::TLV::TLVReader
  91 {
  92 public:
  93     /**
  94      * Initializes a TLVReader object to read from a PacketBuffer.
  95      *
  96      * @param[in]    buffer  A handle to PacketBuffer, to be used as backing store for a TLV class.
  97      * @param[in]    useChainedBuffers
  98      *                       If true, advance to the next buffer in the chain once all data
  99      *                       in the current buffer has been consumed.
 100      */
 101     void Init(chip::System::PacketBufferHandle && buffer, bool useChainedBuffers = false)
 102     {
 103         mBackingStore.Init(std::move(buffer), useChainedBuffers);
 104         chip::TLV::TLVReader::Init(mBackingStore);
 105     }
 106
 107 private:
 108     TLVPacketBufferBackingStore mBackingStore;
 109 };
 110
 111 class DLL_EXPORT PacketBufferTLVWriter : public chip::TLV::TLVWriter
 112 {
 113 public:
 114     /**
 115      * Initializes a TLVWriter object to write to a PacketBuffer.
 116      *
 117      * @param[in]    buffer  A handle to PacketBuffer, to be used as backing store for a TLV class.
 118      * @param[in]    useChainedBuffers
 119      *                       If true, advance to the next buffer in the chain once all space
 120      *                       in the current buffer has been consumed. Once all existing buffers
 121      *                       have been used, new PacketBuffers will be allocated as necessary.
 122      */
 123     void Init(chip::System::PacketBufferHandle && buffer, bool useChainedBuffers = false)
 124     {
 125         mBackingStore.Init(std::move(buffer), useChainedBuffers);
 126         chip::TLV::TLVWriter::Init(mBackingStore);
 127     }
 128     /**
 129      * Finish the writing of a TLV encoding and release ownership of the underlying PacketBuffer.
 130      *
 131      * @param[in,out] outBuffer     The backing packet buffer.
 132      *
 133      * @retval #CHIP_NO_ERROR       If the encoding was finalized successfully.
 134      * @retval #CHIP_ERROR_TLV_CONTAINER_OPEN
 135      *                              If a container writer has been opened on the current writer and not
 136      *                              yet closed.
 137      * @retval #CHIP_ERROR_INVALID_ARGUMENT
 138      *                              If the apparent data length does not fit in uint16_t.
 139      *
 140      * @note No further TLV operations may be performed, unless or until this PacketBufferTLVWriter is re-initialized.
 141      */
 142     CHIP_ERROR Finalize(chip::System::PacketBufferHandle * outBuffer)
 143     {
 144         CHIP_ERROR err = Finalize();
 145         *outBuffer     = mBackingStore.Release();
 146         return err;
 147     }
 148     /**
 149      * Free the underlying PacketBuffer.
 150      *
 151      * @note No further TLV operations may be performed, unless or until this PacketBufferTLVWriter is re-initialized.
 152      */
 153     void Reset() { static_cast<void>(mBackingStore.Release()); }
 154
 155 private:
 156     CHIP_ERROR Finalize() { return chip::TLV::TLVWriter::Finalize(); }
 157     TLVPacketBufferBackingStore mBackingStore;
 158 };
 159
 160 } // namespace System
 161 } // namespace chip