sample_store.h

/**
 * @file sample_store.h
 * @brief API for the sample_store ESP-IDF component (set-based, user-defined namespaces).
 */
#pragma once

#include <stddef.h>
#include <stdint.h>
#include "esp_err.h"

#ifdef __cplusplus
extern "C" {
#endif

/** Opaque handle for the sample store */
typedef struct sample_store_s *sample_store_handle_t;

/** Opaque handle for the sample iterator */
typedef struct sample_store_iterator_s *sample_store_iterator_handle_t;

/** Event types for sample store retention control */
typedef enum {
    SAMPLE_STORE_EVENT_PRE_OVERWRITE_SAMPLE = 0,  /**< Before overwriting oldest sample in a set */
    SAMPLE_STORE_EVENT_POST_OVERWRITE_SAMPLE,     /**< After overwriting oldest sample in a set */
    SAMPLE_STORE_EVENT_PRE_OVERWRITE_SET,         /**< Before overwriting oldest set */
    SAMPLE_STORE_EVENT_POST_OVERWRITE_SET         /**< After overwriting oldest set */
} sample_store_event_type_t;

/** Event handler callback type */
typedef void (*sample_store_event_handler_t)(sample_store_event_type_t type, const char *set_name, const char *key, void *user_ctx);

/**
 * @brief Initialize the sample store handle.
 *
 * @param[out] handle Pointer to the handle to initialize.
 * @return ESP_OK on success, error code otherwise.
 */
esp_err_t sample_store_init(sample_store_handle_t *handle);

/**
 * @brief Deinitialize the sample store handle.
 *
 * @param[in] handle Handle to deinitialize.
 */
void sample_store_deinit(sample_store_handle_t handle);

/**
 * @brief Write a sample blob to a user-defined set (namespace).
 *
 * @param[in] handle Sample store handle.
 * @param[in] set_name Name of the set (namespace, max 15 chars + null).
 * @param[in] data Pointer to the data blob.
 * @param[in] size Size of the data blob.
 * @return ESP_OK on success, error code otherwise.
 */
esp_err_t sample_store_write_to_set(sample_store_handle_t handle, const char *set_name, const void *data, size_t size);

/**
 * @brief Read a sample blob from a set.
 *
 * @param[in] handle Sample store handle.
 * @param[in] set_name Name of the set (namespace).
 * @param[in] hex_key Key in fixed 6-digit hex format.
 * @param[out] data Buffer to store the blob, or NULL to get required size.
 * @param[inout] size Pointer to buffer size; updated with actual size.
 * @return ESP_OK on success, error code otherwise.
 */
esp_err_t sample_store_read_from_set(sample_store_handle_t handle, const char *set_name, const char *hex_key, void *data, size_t *size);

/**
 * @brief Get metadata for a specific set (oldest and newest sample indices).
 *
 * @param[in] handle Sample store handle.
 * @param[in] set_name Name of the set (namespace).
 * @param[out] min_counter Pointer to store the oldest sample index.
 * @param[out] max_counter Pointer to store the newest sample index.
 * @return ESP_OK on success, ESP_ERR_NOT_FOUND if set doesn't exist, error code otherwise.
 */
esp_err_t sample_store_get_set_range(sample_store_handle_t handle, const char *set_name, uint32_t *min_counter, uint32_t *max_counter);

/**
 * @brief Create a new iterator for a subset of samples in a set.
 *
 * @param[in] handle Sample store handle.
 * @param[in] set_name Name of the set (namespace).
 * @param[in] start_counter Starting sample index (inclusive).
 * @param[in] end_counter Ending sample index (inclusive).
 * @param[out] iterator Pointer to the iterator handle to initialize.
 * @return ESP_OK on success, error code otherwise.
 */
esp_err_t sample_store_iterator_new(sample_store_handle_t handle, const char *set_name, uint32_t start_counter, uint32_t end_counter, sample_store_iterator_handle_t *iterator);

/**
 * @brief Free an iterator and its resources.
 *
 * @param[in] iterator Iterator handle to free.
 */
void sample_store_iterator_free(sample_store_iterator_handle_t iterator);

/**
 * @brief Move iterator to the next sample.
 *
 * @param[in] iterator Iterator handle.
 * @return ESP_OK on success, ESP_ERR_NOT_FOUND if beyond range, error code otherwise.
 */
esp_err_t sample_store_iterator_next(sample_store_iterator_handle_t iterator);

/**
 * @brief Move iterator to the previous sample.
 *
 * @param[in] iterator Iterator handle.
 * @return ESP_OK on success, ESP_ERR_NOT_FOUND if beyond range, error code otherwise.
 */
esp_err_t sample_store_iterator_prev(sample_store_iterator_handle_t iterator);

/**
 * @brief Move iterator to a specific sample index.
 *
 * @param[in] iterator Iterator handle.
 * @param[in] counter Sample index to move to.
 * @return ESP_OK on success, ESP_ERR_NOT_FOUND if beyond range, error code otherwise.
 */
esp_err_t sample_store_iterator_goto(sample_store_iterator_handle_t iterator, uint32_t counter);

/**
 * @brief Get the current sample data from the iterator.
 *
 * @param[in] iterator Iterator handle.
 * @param[out] data Pointer to store the sample data pointer (NULL if not found).
 * @param[out] size Pointer to store the sample size (0 if not found).
 * @return ESP_OK on success, ESP_ERR_NOT_FOUND if current position is invalid, error code otherwise.
 */
esp_err_t sample_store_iterator_get_sample(sample_store_iterator_handle_t iterator, void **data, size_t *size);

/**
 * @brief Get the current counter (index) of the iterator.
 *
 * @param[in] iterator Iterator handle.
 * @param[out] counter Pointer to store the current counter.
 * @return ESP_OK on success, error code otherwise.
 */
esp_err_t sample_store_iterator_get_current_counter(sample_store_iterator_handle_t iterator, uint32_t *counter);

/**
 * @brief Delete the current sample pointed by the iterator.
 * 
 * Only allows deletion of the oldest (first) or newest (last) sample in the set.
 * Updates metadata and frees NVS storage space.
 *
 * @param[in] iterator Iterator handle.
 * @return ESP_OK on success, ESP_ERR_INVALID_STATE if sample is not first/last, error code otherwise.
 */
esp_err_t sample_store_iterator_delete_sample(sample_store_iterator_handle_t iterator);

/**
 * @brief List all sets (namespaces) with stored samples, in order from oldest to newest.
 *
 * @param[in] handle Sample store handle.
 * @param[out] sets Array of set strings (allocated, must be freed).
 * @param[out] count Number of sets returned.
 * @return ESP_OK on success, error code otherwise.
 */
esp_err_t sample_store_list_sets(sample_store_handle_t handle, char ***sets, size_t *count);

/**
 * @brief Register an event handler for retention events.
 *
 * @param[in] handle Sample store handle.
 * @param[in] cb Event handler callback (can be NULL).
 * @param[in] user_ctx User context pointer for callback.
 */
void sample_store_set_event_handler(sample_store_handle_t handle, sample_store_event_handler_t cb, void *user_ctx);

#ifdef __cplusplus
}
#endif