EspTypes_NVS.h

Go to the documentation of this file.

 
#pragma once
 
#include "BaseNvs.h" // For hf_nvs_err_t
#include "EspTypes_Base.h"
#include "HardwareTypes.h" // For basic hardware types
#include "McuSelect.h"     // Central MCU platform selection (includes all ESP-IDF)
#include <cstring>
 
//==============================================================================
// ESP32 NVS TYPE MAPPINGS
//==============================================================================
 
// Direct ESP-IDF type usage - no unnecessary aliases
// These types are used internally by EspNvs implementation
 
//==============================================================================
// ESP32 NVS CONSTANTS
//==============================================================================
 
static constexpr size_t HF_NVS_MAX_KEY_LENGTH = 15;
static constexpr size_t HF_NVS_MAX_VALUE_SIZE = 4000;
static constexpr size_t HF_NVS_MAX_NAMESPACE_LENGTH = 15;
static constexpr size_t HF_NVS_MAX_NAMESPACES = 256;
static constexpr size_t HF_NVS_FLASH_SECTOR_SIZE = 4096;
static constexpr size_t HF_NVS_PAGE_SIZE = 4096;
static constexpr size_t HF_NVS_ENTRY_SIZE = 32;
 
// NVS operation timeouts
static constexpr uint32_t HF_NVS_OPERATION_TIMEOUT_MS = 1000; 
static constexpr uint32_t HF_NVS_INIT_TIMEOUT_MS = 5000;      
static constexpr uint32_t HF_NVS_COMMIT_TIMEOUT_MS = 2000;    
 
//==============================================================================
// ESP32 NVS ENUMS
//==============================================================================
 
enum class hf_nvs_type_t : uint8_t {
  HF_NVS_TYPE_U8 = 0,  
  HF_NVS_TYPE_I8 = 1,  
  HF_NVS_TYPE_U16 = 2, 
  HF_NVS_TYPE_I16 = 3, 
  HF_NVS_TYPE_U32 = 4, 
  HF_NVS_TYPE_I32 = 5, 
  HF_NVS_TYPE_U64 = 6, 
  HF_NVS_TYPE_I64 = 7, 
  HF_NVS_TYPE_STR = 8, 
  HF_NVS_TYPE_BLOB = 9 
};
 
enum class hf_nvs_open_mode_t : uint8_t {
  HF_NVS_READONLY = 0, 
  HF_NVS_READWRITE = 1 
};
 
enum class hf_nvs_encryption_mode_t : uint8_t {
  HF_NVS_ENCRYPTION_NONE = 0, 
  HF_NVS_ENCRYPTION_HMAC = 1, 
  HF_NVS_ENCRYPTION_XTS = 2   
};
 
//==============================================================================
// ESP32 NVS CONFIGURATION STRUCTURES
//==============================================================================
 
struct hf_nvs_partition_config_t {
  const char* partition_label;         
  const char* namespace_name;          
  hf_nvs_open_mode_t open_mode;        
  hf_nvs_encryption_mode_t encryption; 
  size_t max_entries;                  
  bool auto_commit;                    
 
  hf_nvs_partition_config_t() noexcept
      : partition_label("nvs"), namespace_name("default"),
        open_mode(hf_nvs_open_mode_t::HF_NVS_READWRITE),
        encryption(hf_nvs_encryption_mode_t::HF_NVS_ENCRYPTION_NONE), max_entries(256),
        auto_commit(true) {}
};
 
struct hf_nvs_capabilities_t {
  size_t max_namespaces;           
  size_t max_keys_per_namespace;   
  size_t max_key_length;           
  size_t max_value_size;           
  size_t flash_sector_size;        
  bool supports_encryption;        
  bool supports_hmac_encryption;   
  bool supports_xts_encryption;    
  bool supports_atomic_operations; 
  bool supports_wear_leveling;     
 
  hf_nvs_capabilities_t() noexcept
      : max_namespaces(HF_NVS_MAX_NAMESPACES), max_keys_per_namespace(256),
        max_key_length(HF_NVS_MAX_KEY_LENGTH), max_value_size(HF_NVS_MAX_VALUE_SIZE),
        flash_sector_size(HF_NVS_FLASH_SECTOR_SIZE), supports_encryption(true),
        supports_hmac_encryption(true), supports_xts_encryption(true),
        supports_atomic_operations(true), supports_wear_leveling(true) {}
};
 
struct hf_nvs_iterator_config_t {
  const char* namespace_name; 
  hf_nvs_type_t type;         
  const char* key_prefix;     
  size_t max_entries;         
 
  hf_nvs_iterator_config_t() noexcept
      : namespace_name(nullptr), type(hf_nvs_type_t::HF_NVS_TYPE_U8), key_prefix(nullptr),
        max_entries(100) {}
};
 
struct hf_nvs_entry_info_t {
  char key[HF_NVS_MAX_KEY_LENGTH + 1]; 
  hf_nvs_type_t type;                  
  size_t size;                         
  uint32_t crc;                        
 
  hf_nvs_entry_info_t() noexcept : type(hf_nvs_type_t::HF_NVS_TYPE_U8), size(0), crc(0) {
    key[0] = '\0';
  }
};
 
//==============================================================================
// ESP32 NVS VALIDATION MACROS
//==============================================================================
 
#define HF_NVS_IS_VALID_KEY_LENGTH(len) ((len) > 0 && (len) <= HF_NVS_MAX_KEY_LENGTH)
#define HF_NVS_IS_VALID_VALUE_SIZE(size) ((size) <= HF_NVS_MAX_VALUE_SIZE)
#define HF_NVS_IS_VALID_NAMESPACE_LENGTH(len) ((len) > 0 && (len) <= HF_NVS_MAX_NAMESPACE_LENGTH)
 
//==============================================================================
// ESP32 NVS UTILITY FUNCTIONS
//==============================================================================
 
inline constexpr bool IsValidNvsKey(const char* key) noexcept {
  if (!key)
    return false;
  size_t len = strlen(key);
  return HF_NVS_IS_VALID_KEY_LENGTH(len);
}
 
inline constexpr bool IsValidNvsNamespace(const char* namespace_name) noexcept {
  if (!namespace_name)
    return false;
  size_t len = strlen(namespace_name);
  return HF_NVS_IS_VALID_NAMESPACE_LENGTH(len);
}
 
inline constexpr bool IsValidNvsValueSize(size_t size) noexcept {
  return HF_NVS_IS_VALID_VALUE_SIZE(size);
}
 
inline constexpr size_t GetMaxValueSizeForType(hf_nvs_type_t type) noexcept {
  switch (type) {
  case hf_nvs_type_t::HF_NVS_TYPE_U8:
  case hf_nvs_type_t::HF_NVS_TYPE_I8:
    return 1;
  case hf_nvs_type_t::HF_NVS_TYPE_U16:
  case hf_nvs_type_t::HF_NVS_TYPE_I16:
    return 2;
  case hf_nvs_type_t::HF_NVS_TYPE_U32:
  case hf_nvs_type_t::HF_NVS_TYPE_I32:
    return 4;
  case hf_nvs_type_t::HF_NVS_TYPE_U64:
  case hf_nvs_type_t::HF_NVS_TYPE_I64:
    return 8;
  case hf_nvs_type_t::HF_NVS_TYPE_STR:
  case hf_nvs_type_t::HF_NVS_TYPE_BLOB:
    return HF_NVS_MAX_VALUE_SIZE;
  default:
    return 0;
  }
}
 
//==============================================================================
// END OF ESPNVS TYPES - MINIMAL AND ESSENTIAL ONLY
//==============================================================================