BaseNvs.h

Go to the documentation of this file.

 
#pragma once
 
#include "HardwareTypes.h"
#include <cstdint>
#include <string_view>
 
//--------------------------------------
//  HardFOC NVS Error Codes (Table)
//--------------------------------------
#define HF_NVS_ERR_LIST(X)                                                                         \
  /* Success codes */                                                                              \
  X(NVS_SUCCESS, 0, "Success")                                                                     \
  /* General errors */                                                                             \
  X(NVS_ERR_FAILURE, 1, "General failure")                                                         \
  X(NVS_ERR_NOT_INITIALIZED, 2, "Not initialized")                                                 \
  X(NVS_ERR_ALREADY_INITIALIZED, 3, "Already initialized")                                         \
  X(NVS_ERR_INVALID_PARAMETER, 4, "Invalid parameter")                                             \
  X(NVS_ERR_NULL_POINTER, 5, "Null pointer")                                                       \
  X(NVS_ERR_OUT_OF_MEMORY, 6, "Out of memory")                                                     \
  /* Storage specific errors */                                                                    \
  X(NVS_ERR_KEY_NOT_FOUND, 7, "Key not found")                                                     \
  X(NVS_ERR_KEY_TOO_LONG, 8, "Key too long")                                                       \
  X(NVS_ERR_VALUE_TOO_LARGE, 9, "Value too large")                                                 \
  X(NVS_ERR_NAMESPACE_NOT_FOUND, 10, "Namespace not found")                                        \
  X(NVS_ERR_STORAGE_FULL, 11, "Storage full")                                                      \
  X(NVS_ERR_INVALID_DATA, 12, "Invalid data")                                                      \
  X(NVS_ERR_READ_ONLY, 13, "Read only mode")                                                       \
  X(NVS_ERR_CORRUPTED, 14, "Data corrupted")                                                       \
  /* ESP32-C6 encryption and advanced feature errors */                                            \
  X(NVS_ERR_ENCRYPTION_FAILED, 15, "Encryption operation failed")                                  \
  X(NVS_ERR_DECRYPTION_FAILED, 16, "Decryption operation failed")                                  \
  X(NVS_ERR_ENCRYPTION_NOT_CONFIGURED, 17, "Encryption not configured")                            \
  X(NVS_ERR_ENCRYPTION_NOT_SUPPORTED, 18, "Encryption not supported")                              \
  X(NVS_ERR_KEY_PARTITION_CORRUPTED, 19, "Key partition corrupted")                                \
  X(NVS_ERR_WRONG_ENCRYPTION_SCHEME, 20, "Wrong encryption scheme")                                \
  X(NVS_ERR_VERSION_MISMATCH, 21, "NVS version mismatch")                                          \
  X(NVS_ERR_NO_FREE_PAGES, 22, "No free pages available")                                          \
  X(NVS_ERR_PARTITION_NOT_FOUND, 23, "NVS partition not found")                                    \
  X(NVS_ERR_ITERATOR_INVALID, 24, "Iterator invalid or expired")                                   \
  X(NVS_ERR_SECURITY_VIOLATION, 25, "Security policy violation")                                   \
  X(NVS_ERR_UNSUPPORTED_OPERATION, 26, "Unsupported operation")                                    \
  X(NVS_ERR_UNKNOWN, 27, "Unknown error")
 
// Generate enum class from X-macro
enum class hf_nvs_err_t : hf_i32_t {
#define X(name, value, desc) name = value,
  HF_NVS_ERR_LIST(X)
#undef X
};
 
constexpr std::string_view HfNvsErrToString(hf_nvs_err_t err) noexcept {
  switch (err) {
#define X(NAME, VALUE, DESC)                                                                       \
  case hf_nvs_err_t::NAME:                                                                         \
    return DESC;
    HF_NVS_ERR_LIST(X)
#undef X
  default:
    return HfNvsErrToString(hf_nvs_err_t::NVS_ERR_UNKNOWN);
  }
}
 
struct hf_nvs_statistics_t {
  hf_u32_t total_operations;
  hf_u32_t total_errors;
  hf_u32_t total_reads;
  hf_u32_t total_writes;
  hf_u32_t total_commits;
  hf_u32_t total_erases;
  hf_nvs_err_t last_error;
  hf_u32_t last_operation_time_us;
  hf_u32_t successful_ops;
  hf_u32_t failed_ops;
  hf_u32_t bytes_written;
  hf_u32_t bytes_read;
};
 
struct hf_nvs_diagnostics_t {
  hf_nvs_err_t last_error;
  hf_u32_t consecutive_errors;
  bool storage_healthy;
  hf_u32_t system_uptime_ms;
};
 
class BaseNvs {
public:
  virtual ~BaseNvs() noexcept = default;
 
  // Disable copy constructor and assignment operator for safety
  BaseNvs(const BaseNvs&) = delete;
  BaseNvs& operator=(const BaseNvs&) = delete;
 
  //==============================================//
  // LAZY-INITIALIZATION PATTERN                  //
  //==============================================//
 
  bool EnsureInitialized() {
    if (!initialized_) {
      initialized_ = (Initialize() == hf_nvs_err_t::NVS_SUCCESS);
    }
    return initialized_;
  }
 
  bool EnsureDeinitialized() {
    if (initialized_) {
      initialized_ = !(Deinitialize() == hf_nvs_err_t::NVS_SUCCESS);
    }
    return !initialized_;
  }
 
  bool IsInitialized() const noexcept {
    return initialized_;
  }
 
  //==============================================//
  // PURE VIRTUAL FUNCTIONS (MUST BE IMPLEMENTED) //
  //==============================================//
 
  virtual hf_nvs_err_t Initialize() noexcept = 0;
 
  virtual hf_nvs_err_t Deinitialize() noexcept = 0;
 
  virtual hf_nvs_err_t SetU32(const char* key, hf_u32_t value) noexcept = 0;
 
  virtual hf_nvs_err_t GetU32(const char* key, hf_u32_t& value) noexcept = 0;
 
  virtual hf_nvs_err_t SetString(const char* key, const char* value) noexcept = 0;
 
  virtual hf_nvs_err_t GetString(const char* key, char* buffer, size_t buffer_size,
                                 size_t* actual_size = nullptr) noexcept = 0;
 
  virtual hf_nvs_err_t SetBlob(const char* key, const void* data, size_t data_size) noexcept = 0;
 
  virtual hf_nvs_err_t GetBlob(const char* key, void* buffer, size_t buffer_size,
                               size_t* actual_size = nullptr) noexcept = 0;
 
  virtual hf_nvs_err_t EraseKey(const char* key) noexcept = 0;
 
  virtual hf_nvs_err_t Commit() noexcept = 0;
 
  virtual bool KeyExists(const char* key) noexcept = 0;
 
  virtual hf_nvs_err_t GetSize(const char* key, size_t& size) noexcept = 0;
 
  //==============================================//
  // PUBLIC INTERFACE (IMPLEMENTED)               //
  //==============================================//
 
  const char* GetNamespace() const noexcept {
    return namespace_name_;
  }
 
  virtual const char* GetDescription() const noexcept = 0;
 
  virtual size_t GetMaxKeyLength() const noexcept = 0;
 
  virtual size_t GetMaxValueSize() const noexcept = 0;
 
  //==============================================//
  // STATISTICS AND DIAGNOSTICS
  //==============================================//
 
  virtual hf_nvs_err_t ResetStatistics() noexcept {
    statistics_ = hf_nvs_statistics_t{}; // Reset statistics to default values
    return hf_nvs_err_t::NVS_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_nvs_err_t ResetDiagnostics() noexcept {
    diagnostics_ = hf_nvs_diagnostics_t{}; // Reset diagnostics to default values
    return hf_nvs_err_t::NVS_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_nvs_err_t GetStatistics(hf_nvs_statistics_t& statistics) const noexcept {
    statistics = statistics_; // Return statistics by default
    return hf_nvs_err_t::NVS_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_nvs_err_t GetDiagnostics(hf_nvs_diagnostics_t& diagnostics) const noexcept {
    diagnostics = diagnostics_; // Return diagnostics by default
    return hf_nvs_err_t::NVS_ERR_UNSUPPORTED_OPERATION;
  }
 
protected:
  explicit BaseNvs(const char* namespace_name) noexcept
      : namespace_name_(namespace_name), initialized_(false), statistics_{}, diagnostics_{} {}
 
  void SetInitialized(bool initialized) noexcept {
    initialized_ = initialized;
  }
 
  const char* namespace_name_;       
  bool initialized_;                 
  hf_nvs_statistics_t statistics_;   
  hf_nvs_diagnostics_t diagnostics_; 
 
private:
};