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           1 :     virtual ~AttributePersistenceProvider() = default;
      36           1 :     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             : AttributePersistenceProvider * GetAttributePersistenceProvider();
      83             : 
      84             : /**
      85             :  * Instance setter for the global AttributePersistenceProvider.
      86             :  *
      87             :  * Callers have to externally synchronize usage of this function.
      88             :  *
      89             :  * If the `provider` is nullptr, the value is not changed.
      90             :  *
      91             :  * @param[in] aProvider the AttributePersistenceProvider implementation to use.
      92             :  */
      93             : void SetAttributePersistenceProvider(AttributePersistenceProvider * aProvider);
      94             : 
      95             : } // namespace app
      96             : } // namespace chip