| /* |
| * |
| * Copyright (c) 2020-2021 Project CHIP Authors |
| * Copyright (c) 2016-2017 Nest Labs, Inc. |
| * All rights reserved. |
| * |
| * 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 defines the circular buffer for TLV |
| * elements. When used as the backing store for the TLVReader and |
| * TLVWriter, those classes will work with the wraparound of data |
| * within the buffer. Additionally, the TLVWriter will be able |
| * to continually add top-level TLV elements by evicting |
| * pre-existing elements. |
| */ |
| |
| #pragma once |
| |
| #include <lib/core/CHIPError.h> |
| #include <lib/core/CHIPTLV.h> |
| #include <lib/core/CHIPTLVTags.h> |
| #include <lib/core/CHIPTLVTypes.h> |
| |
| #include <lib/support/DLLUtil.h> |
| |
| #include <stdlib.h> |
| |
| namespace chip { |
| namespace TLV { |
| |
| /** |
| * @class CHIPCircularTLVBuffer |
| * |
| * @brief |
| * CHIPCircularTLVBuffer provides circular storage for the |
| * chip::TLV::TLVWriter and chip::TLVTLVReader. chip::TLV::TLVWriter is able to write an |
| * unbounded number of TLV entries to the CHIPCircularTLVBuffer |
| * as long as each individual TLV entry fits entirely within the |
| * provided storage. The chip::TLV::TLVReader will read at most the size of |
| * the buffer, but will accommodate the wraparound within the |
| * buffer. |
| * |
| */ |
| class DLL_EXPORT CHIPCircularTLVBuffer : public chip::TLV::TLVBackingStore |
| { |
| public: |
| CHIPCircularTLVBuffer(uint8_t * inBuffer, uint32_t inBufferLength); |
| CHIPCircularTLVBuffer(uint8_t * inBuffer, uint32_t inBufferLength, uint8_t * inHead); |
| |
| void Init(uint8_t * inBuffer, uint32_t inBufferLength); |
| inline uint8_t * QueueHead() const { return mQueueHead; } |
| inline uint8_t * QueueTail() const { return mQueue + ((static_cast<size_t>(mQueueHead - mQueue) + mQueueLength) % mQueueSize); } |
| inline uint32_t DataLength() const { return mQueueLength; } |
| inline uint32_t AvailableDataLength() const { return mQueueSize - mQueueLength; } |
| inline uint32_t GetTotalDataLength() const { return mQueueSize; } |
| inline uint8_t * GetQueue() const { return mQueue; } |
| |
| CHIP_ERROR EvictHead(); |
| |
| // chip::TLV::TLVBackingStore overrides: |
| CHIP_ERROR OnInit(TLVReader & reader, const uint8_t *& bufStart, uint32_t & bufLen) override; |
| CHIP_ERROR GetNextBuffer(TLVReader & ioReader, const uint8_t *& outBufStart, uint32_t & outBufLen) override; |
| CHIP_ERROR OnInit(TLVWriter & writer, uint8_t *& bufStart, uint32_t & bufLen) override; |
| CHIP_ERROR GetNewBuffer(TLVWriter & ioWriter, uint8_t *& outBufStart, uint32_t & outBufLen) override; |
| CHIP_ERROR FinalizeBuffer(TLVWriter & ioWriter, uint8_t * inBufStart, uint32_t inBufLen) override; |
| |
| /** |
| * @typedef CHIP_ERROR (*ProcessEvictedElementFunct)(CHIPCircularTLVBuffer &inBuffer, void * inAppData, TLVReader &inReader) |
| * |
| * A function that is called to process a TLV element prior to it |
| * being evicted from the chip::TLV::CHIPCircularTLVBuffer |
| * |
| * Functions of this type are used to process a TLV element about |
| * to be evicted from the buffer. The function will be given a |
| * chip::TLV::TLVReader positioned on the element about to be deleted, as |
| * well as void * context where the user may have provided |
| * additional environment for the callback. If the function |
| * processed the element successfully, it must return |
| * #CHIP_NO_ERROR ; this signifies to the CHIPCircularTLVBuffer |
| * that the element may be safely evicted. Any other return |
| * value is treated as an error and will prevent the |
| * #CHIPCircularTLVBuffer from evicting the element under |
| * consideration. |
| * |
| * Note: This callback may be used to force |
| * CHIPCircularTLVBuffer to not evict the element. This may be |
| * useful in a number of circumstances, when it is desired to |
| * have an underlying circular buffer, but not to override any |
| * elements within it. |
| * |
| * @param[in] inBuffer A reference to the buffer from which the |
| * eviction takes place |
| * |
| * @param[in] inAppData A pointer to the user-provided structure |
| * containing additional context for this |
| * callback |
| * |
| * @param[in] inReader A TLVReader positioned at the element to |
| * be evicted. |
| * |
| * @retval #CHIP_NO_ERROR On success. Element will be evicted. |
| * |
| * @retval other An error has occurred during the event |
| * processing. The element stays in the |
| * buffer. The write function that |
| * triggered this element eviction will |
| * fail. |
| */ |
| typedef CHIP_ERROR (*ProcessEvictedElementFunct)(CHIPCircularTLVBuffer & inBuffer, void * inAppData, TLVReader & inReader); |
| |
| uint32_t mImplicitProfileId; |
| void * mAppData; /**< An optional, user supplied context to be used with the callback processing the evicted element. */ |
| ProcessEvictedElementFunct |
| mProcessEvictedElement; /**< An optional, user-supplied callback that processes the element prior to evicting it from the |
| circular buffer. See the ProcessEvictedElementFunct type definition on additional information on |
| implementing the mProcessEvictedElement function. */ |
| |
| private: |
| uint8_t * mQueue; |
| uint32_t mQueueSize; |
| uint8_t * mQueueHead; |
| uint32_t mQueueLength; |
| }; |
| |
| class DLL_EXPORT CircularTLVReader : public TLVReader |
| { |
| public: |
| /** |
| * @brief |
| * Initializes a TLVReader object to read from a single CHIPCircularTLVBuffer |
| * |
| * Parsing begins at the start of the buffer (obtained by the |
| * buffer->Start() position) and continues until the end of the buffer |
| * Parsing may wraparound within the buffer (on any element). At most |
| * buffer->GetQueueSize() bytes are read out. |
| * |
| * @param[in] buf A pointer to a fully initialized CHIPCircularTLVBuffer |
| * |
| */ |
| void Init(CHIPCircularTLVBuffer & buf) { TLVReader::Init(buf, buf.DataLength()); } |
| }; |
| |
| class DLL_EXPORT CircularTLVWriter : public TLVWriter |
| { |
| public: |
| /** |
| * @brief |
| * Initializes a TLVWriter object to write from a single CHIPCircularTLVBuffer |
| * |
| * Writing begins at the last byte of the buffer. The number of bytes |
| * to be written is not constrained by the underlying circular buffer: |
| * writing new elements to the buffer will kick out previous elements |
| * as long as an individual top-level TLV structure fits within the |
| * buffer. For example, writing a 7-byte top-level boolean TLV into a |
| * 7 byte buffer will work indefinitely, but writing an 8-byte TLV |
| * structure will result in an error. |
| * |
| * @param[in] buf A pointer to a fully initialized CHIPCircularTLVBuffer |
| * |
| */ |
| void Init(CHIPCircularTLVBuffer & buf) { TLVWriter::Init(buf, UINT32_MAX); } |
| }; |
| |
| } // namespace TLV |
| } // namespace chip |