/**
 * Simple key-value map for session data storage.
 * Takes care of dynamic allocation and cleanup.
 * 
 * Created on 2019/01/28.
 */

#ifndef SESSION_KVMAP_H
#define SESSION_KVMAP_H

/**
 * Prototype for a free() func to clean up session-held objects
 */
typedef void (*sess_kv_free_func_t)(void *obj);

typedef struct sess_kv_map sess_kv_map_t;

#define SESS_KVMAP_KEY_LEN 16

/**
 * Allocate a new session key-value store
 *
 * @return the store, NULL on error
 */
sess_kv_map_t *sess_kv_map_alloc(void);

/**
 * Free the session kv store.
 *
 * @param head - store head
 */
void sess_kv_map_free(void *head);

/**
 * Get a value from the session kv store.
 *
 * @param head - store head
 * @param key - key to get a value for
 * @return the value, or NULL if not found
 */
void *sess_kv_map_get(sess_kv_map_t *head, const char *key);

/**
 * Get and remove a value from the session store.
 *
 * The free function is not called in this case and the recipient is
 * responsible for cleaning it up correctly.
 *
 * @param head - store head
 * @param key - key to get a value for
 * @return the value, or NULL if not found
 */
void * sess_kv_map_take(sess_kv_map_t *head, const char *key);

/**
 * Remove an entry from the session by its key name.
 * The slot is not free'd yet, but is made available for reuse.
 *
 * @param head - store head
 * @param key - key to remove
 * @return success
 */
esp_err_t sess_kv_map_remove(sess_kv_map_t *head, const char *key);

/**
 * Set a key value. If there is an old value stored, it will be freed by its free function and replaced by the new one.
 * Otherwise a new slot is allocated for it, or a previously released one is reused.
 *
 * @param head - store head
 * @param key - key to assign to
 * @param value - new value
 * @param free_fn - value free func
 * @return success
 */
esp_err_t sess_kv_map_set(sess_kv_map_t *head, const char *key, void *value, sess_kv_free_func_t free_fn);

#endif //SESSION_KVMAP_H