// dvxPrefs.h  -- INI-based preferences system (read/write)
//
// Handle-based API: multiple INI files can be open simultaneously.
// Each prefsOpen/prefsLoad returns a handle that must be passed to
// all subsequent calls and freed with prefsClose when done.

#ifndef DVX_PREFS_H
#define DVX_PREFS_H

#include <stdbool.h>
#include <stdint.h>

// Opaque handle to a loaded preferences file.
typedef struct PrefsHandleT PrefsHandleT;

// Create an empty preferences handle (no file loaded). Useful for
// building a new INI from scratch before saving.
PrefsHandleT *prefsCreate(void);

// Load an INI file into a new handle. Returns NULL on allocation
// failure. If the file doesn't exist, returns a valid empty handle
// (all getters return defaults) with the path stored for prefsSave.
PrefsHandleT *prefsLoad(const char *filename);

// Save the in-memory state back to the file that was loaded.
bool prefsSave(PrefsHandleT *h);

// Save the in-memory state to a specific file.
bool prefsSaveAs(PrefsHandleT *h, const char *filename);

// Release all memory held by the handle.
void prefsClose(PrefsHandleT *h);

// Retrieve a string value. Returns defaultVal if the key is not present.
// The returned pointer is valid until the key is modified or prefsClose.
const char *prefsGetString(PrefsHandleT *h, const char *section, const char *key, const char *defaultVal);

// Retrieve an integer value.
int32_t prefsGetInt(PrefsHandleT *h, const char *section, const char *key, int32_t defaultVal);

// Retrieve a boolean value. Recognises "true"/"yes"/"1" and "false"/"no"/"0".
bool prefsGetBool(PrefsHandleT *h, const char *section, const char *key, bool defaultVal);

// Set a string value. Creates the section and key if they don't exist.
void prefsSetString(PrefsHandleT *h, const char *section, const char *key, const char *value);

// Set an integer value.
void prefsSetInt(PrefsHandleT *h, const char *section, const char *key, int32_t value);

// Set a boolean value (stored as "true"/"false").
void prefsSetBool(PrefsHandleT *h, const char *section, const char *key, bool value);

// Remove a key from a section. No-op if not found.
void prefsRemove(PrefsHandleT *h, const char *section, const char *key);

#endif