Line data    Source code

       1              : /*
       2              :  *    Copyright (c) 2021 Project CHIP Authors
       3              :  *
       4              :  *    Licensed under the Apache License, Version 2.0 (the "License");
       5              :  *    you may not use this file except in compliance with the License.
       6              :  *    You may obtain a copy of the License at
       7              :  *
       8              :  *        http://www.apache.org/licenses/LICENSE-2.0
       9              :  *
      10              :  *    Unless required by applicable law or agreed to in writing, software
      11              :  *    distributed under the License is distributed on an "AS IS" BASIS,
      12              :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      13              :  *    See the License for the specific language governing permissions and
      14              :  *    limitations under the License.
      15              :  */
      16              : #pragma once
      17              : 
      18              : #include <app/ConcreteAttributePath.h>
      19              : #include <app/util/attribute-metadata.h>
      20              : #include <lib/support/Span.h>
      21              : 
      22              : namespace chip {
      23              : namespace app {
      24              : 
      25              : /**
      26              :  * Interface for persisting attribute values. This will write attributes in storage with platform endianness for scalars
      27              :  * and uses a different key space from SafeAttributePersistenceProvider.
      28              :  * When storing cluster attributes that are managed via the AttributeAccessInterface, it is recommended to
      29              :  * use SafeAttributePersistenceProvider.
      30              :  */
      31              : 
      32              : class AttributePersistenceProvider
      33              : {
      34              : public:
      35           62 :     virtual ~AttributePersistenceProvider() = default;
      36           62 :     AttributePersistenceProvider()          = default;
      37              : 
      38              :     /**
      39              :      * Write an attribute value from the attribute store (i.e. not a struct or
      40              :      * list) to non-volatile memory.
      41              :      *
      42              :      * @param [in] aPath the attribute path for the data being written.
      43              :      * @param [in] aValue the data to write.  Integers and floats are
      44              :      *             represented in native endianness.  Strings are represented
      45              :      *             as Pascal-style strings, as in ZCL, with a length prefix
      46              :      *             whose size depends on the actual string type.  The length is
      47              :      *             stored as little-endian.
      48              :      *
      49              :      *             Integer and float values have a size that matches the `size`
      50              :      *             member of aMetadata.
      51              :      *
      52              :      *             String values have a size that corresponds to the actual size
      53              :      *             of the data in the string (including the length prefix),
      54              :      *             which is no larger than the `size` member of aMetadata.
      55              :      */
      56              :     virtual CHIP_ERROR WriteValue(const ConcreteAttributePath & aPath, const ByteSpan & aValue) = 0;
      57              : 
      58              :     /**
      59              :      * Read an attribute value from non-volatile memory.
      60              :      *
      61              :      * @param [in]     aPath the attribute path for the data being persisted.
      62              :      * @param [in]     aMetadata the attribute metadata, as a convenience.
      63              :      * @param [in,out] aValue where to place the data.  The size of the buffer
      64              :      *                 will be equal to `size` member of aMetadata.
      65              :      *
      66              :      *                 The data is expected to be in native endianness for
      67              :      *                 integers and floats.  For strings, see the string
      68              :      *                 representation description in the WriteValue
      69              :      *                 documentation.
      70              :      */
      71              :     virtual CHIP_ERROR ReadValue(const ConcreteAttributePath & aPath, const EmberAfAttributeMetadata * aMetadata,
      72              :                                  MutableByteSpan & aValue) = 0;
      73              : };
      74              : 
      75              : /**
      76              :  * Instance getter for the global AttributePersistenceProvider.
      77              :  *
      78              :  * Callers have to externally synchronize usage of this function.
      79              :  *
      80              :  * @return The global AttributePersistenceProvider.  This must never be null.
      81              :  *
      82              :  * Note: When storing cluster attributes that are managed via AttributeAccessInterface, it is recommended to
      83              :  * use SafeAttributePersistenceProvider. See AttributePersistenceProvider and SafeAttributePersistenceProvider
      84              :  * class documentation for more information.
      85              :  */
      86              : AttributePersistenceProvider * GetAttributePersistenceProvider();
      87              : 
      88              : /**
      89              :  * Instance setter for the global AttributePersistenceProvider.
      90              :  *
      91              :  * Callers have to externally synchronize usage of this function.
      92              :  *
      93              :  * If the `provider` is nullptr, the value is not changed.
      94              :  *
      95              :  * @param[in] aProvider the AttributePersistenceProvider implementation to use.
      96              :  */
      97              : void SetAttributePersistenceProvider(AttributePersistenceProvider * aProvider);
      98              : 
      99              : } // namespace app
     100              : } // namespace chip