src/lib/support/LifetimePersistedCounter.h

   1 /*
   2  *
   3  *    Copyright (c) 2021 Project CHIP Authors
   4  *    All rights reserved.
   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  *
  22  * @brief
  23  *   Class declarations for a monotonically-increasing counter that is periodically
  24  *   saved in the platform's persistent storage.
  25  */
  26
  27 #pragma once
  28
  29 #include <platform/PersistedStorage.h>
  30 #include <support/CHIPCounter.h>
  31
  32 namespace chip {
  33
  34 /**
  35  * @class LifetimePersistedCounter
  36  *
  37  * @brief
  38  *   A class for managing a counter as an integer value intended to persist
  39  *   across reboots.
  40  *
  41  * Counter values are always set to start at a multiple of a bootup value
  42  * "epoch".
  43  *
  44  * Example:
  45  *
  46  * - Assuming epoch is 100 via LifetimePersistedCounter::Init(_, 100) and GetValue +
  47  *   AdvanceValue is called, we get the following outputs:
  48  *
  49  *   - Output: 0, 1, 2, 3, 4
  50  *
  51  */
  52 class LifetimePersistedCounter : public MonotonicallyIncreasingCounter
  53 {
  54 public:
  55     LifetimePersistedCounter();
  56     ~LifetimePersistedCounter() override;
  57
  58     /**
  59      *  @brief
  60      *    Initialize a LifetimePersistedCounter object.
  61      *
  62      *  @param[in] aId     The identifier of this LifetimePersistedCounter instance.
  63      *
  64      *  @return CHIP_ERROR_INVALID_ARGUMENT if aId is NULL
  65      *          CHIP_ERROR_INVALID_STRING_LENGTH if aId is longer than
  66      *          CHIP_CONFIG_PERSISTED_STORAGE_MAX_KEY_LENGTH.
  67      *          CHIP_ERROR_INVALID_INTEGER_VALUE if aEpoch is 0.
  68      *          CHIP_NO_ERROR otherwise
  69      */
  70     CHIP_ERROR Init(chip::Platform::PersistedStorage::Key aId);
  71
  72     /**
  73      *  @brief
  74      *  Increment the counter and write to persisted storage if we've completed
  75      *  the current epoch.
  76      *
  77      *  @return Any error returned by a write to persisted storage.
  78      */
  79     CHIP_ERROR Advance() override;
  80
  81 private:
  82     /**
  83      *  @brief
  84      *    Write out the counter value to persistent storage.
  85      *
  86      *  @param[in] aStartValue  The counter value to write out.
  87      *
  88      *  @return Any error returned by a write to persistent storage.
  89      */
  90     CHIP_ERROR PersistNextEpochStart(uint32_t aStartValue);
  91
  92     /**
  93      *  @brief
  94      *    Read our starting counter value (if we have one) in from persistent storage.
  95      *
  96      *  @param[in,out] aStartValue  The value read out.
  97      *
  98      *  @return Any error returned by a read from persistent storage.
  99      */
 100     CHIP_ERROR ReadStartValue(uint32_t & aStartValue);
 101
 102     chip::Platform::PersistedStorage::Key mId; // start value is stored here
 103 };
 104
 105 } // namespace chip