/**
 * GDBM - GNU dbm bindings for Vala
 * 
 * This VAPI provides bindings for the GDBM (GNU dbm) library,
 * a simple key-value database with persistent storage.
 */
[CCode (cprefix = "", lower_case_cprefix = "", cheader_filename = "gdbm.h,Storage/Gdbm/gdbm_wrapper.h")]
namespace Gdbm {

    /**
     * Flags for gdbm_open() - read/write mode
     */
    [CCode (cname = "int", has_type_id = false)]
    public enum OpenFlag {
        [CCode (cname = "GDBM_READER")]
        READER,
        [CCode (cname = "GDBM_WRITER")]
        WRITER,
        [CCode (cname = "GDBM_WRCREAT")]
        WRCREAT,
        [CCode (cname = "GDBM_NEWDB")]
        NEWDB
    }

    /**
     * Additional flags for gdbm_open() - bitwise modifiers
     */
    [CCode (cname = "int", has_type_id = false)]
    [Flags]
    public enum OpenModifier {
        [CCode (cname = "GDBM_SYNC")]
        SYNC,
        [CCode (cname = "GDBM_NOLOCK")]
        NOLOCK,
        [CCode (cname = "GDBM_BSEXACT")]
        BSEXACT,
        [CCode (cname = "GDBM_CLOEXEC")]
        CLOEXEC
    }

    /**
     * Flags for gdbm_store()
     */
    [CCode (cname = "int", has_type_id = false)]
    public enum StoreFlag {
        [CCode (cname = "GDBM_INSERT")]
        INSERT,
        [CCode (cname = "GDBM_REPLACE")]
        REPLACE
    }

    /**
     * Error codes from gdbm_last_error()
     */
    [CCode (cname = "gdbm_error", has_type_id = false)]
    public enum ErrorCode {
        [CCode (cname = "GDBM_NO_ERROR")]
        NO_ERROR,
        [CCode (cname = "GDBM_MALLOC_ERROR")]
        MALLOC_ERROR,
        [CCode (cname = "GDBM_BLOCK_SIZE_ERROR")]
        BLOCK_SIZE_ERROR,
        [CCode (cname = "GDBM_OPEN_ERROR")]
        OPEN_ERROR,
        [CCode (cname = "GDBM_READ_ERROR")]
        READ_ERROR,
        [CCode (cname = "GDBM_WRITE_ERROR")]
        WRITE_ERROR,
        [CCode (cname = "GDBM_SEEK_ERROR")]
        SEEK_ERROR,
        [CCode (cname = "GDBM_REORGANIZE_FAILED")]
        REORGANIZE_FAILED,
        [CCode (cname = "GDBM_ILLEGAL_DATA")]
        ILLEGAL_DATA,
        [CCode (cname = "GDBM_OPT_ALREADY_SET")]
        OPT_ALREADY_SET,
        [CCode (cname = "GDBM_OPT_ILLEGAL")]
        OPT_ILLEGAL,
        [CCode (cname = "GDBM_BYTE_SWAPPED")]
        BYTE_SWAPPED,
        [CCode (cname = "GDBM_BAD_FILE_OFFSET")]
        BAD_FILE_OFFSET,
        [CCode (cname = "GDBM_BAD_OPEN_FLAGS")]
        BAD_OPEN_FLAGS,
        [CCode (cname = "GDBM_FILE_STAT_ERROR")]
        FILE_STAT_ERROR,
        [CCode (cname = "GDBM_FILE_EOF")]
        FILE_EOF,
        [CCode (cname = "GDBM_NO_DBNAME")]
        NO_DBNAME,
        [CCode (cname = "GDBM_ERR_FILE_OWNER")]
        ERR_FILE_OWNER,
        [CCode (cname = "GDBM_ERR_FILE_MODE")]
        ERR_FILE_MODE,
        [CCode (cname = "GDBM_UNKNOWN_ERROR")]
        UNKNOWN_ERROR,
        [CCode (cname = "GDBM_ITEM_NOT_FOUND")]
        ITEM_NOT_FOUND,
        [CCode (cname = "GDBM_MALFORMED_DATA")]
        MALFORMED_DATA,
        [CCode (cname = "GDBM_OPT_BADVAL")]
        OPT_BADVAL,
        [CCode (cname = "GDBM_ERR_SNAPSHOT_CLONE")]
        ERR_SNAPSHOT_CLONE,
        [CCode (cname = "GDBM_ERR_REALPATH")]
        ERR_REALPATH,
        [CCode (cname = "GDBM_ERR_DIR")]
        ERR_DIR,
        [CCode (cname = "GDBM_ERR_DB_FILENAME")]
        ERR_DB_FILENAME,
        [CCode (cname = "GDBM_ERR_OPEN")]
        ERR_OPEN,
        [CCode (cname = "GDBM_ERR_CLOSE")]
        ERR_CLOSE,
        [CCode (cname = "GDBM_ERR_FSTAT")]
        ERR_FSTAT,
        [CCode (cname = "GDBM_ERR_FILE_COUNT")]
        ERR_FILE_COUNT
    }

    /**
     * Database handle - wraps GDBM_FILE pointer.
     * GDBM_FILE is already a pointer type (typedef struct gdbm_file_info *GDBM_FILE).
     */
    [Compact]
    [CCode (cname = "struct gdbm_file_info", free_function = "gdbm_close")]
    public class Database {
        /**
         * Opens a GDBM database file.
         * 
         * @param name Path to the database file
         * @param block_size Size of a block in the database (0 for default)
         * @param flags Open flags (READER, WRITER, WRCREAT, NEWDB) plus optional modifiers
         * @param mode File creation mode (e.g., 0644)
         * @return Database handle, or null on error
         */
        [CCode (cname = "gdbm_open")]
        public static Database? open(string name, int block_size, int flags, int mode, void* fatal_func = null);

        /**
         * Checks if a key exists in the database.
         * 
         * @param key The key to check
         * @return True if the key exists
         */
        [CCode (cname = "gdbm_exists_wrapper")]
        public bool exists(string key);

        /**
         * Retrieves a value by key.
         * 
         * @param key The key to look up
         * @return The value as GBytes, or null if not found
         */
        [CCode (cname = "gdbm_fetch_wrapper")]
        public GLib.Bytes? fetch(string key);

        /**
         * Stores a key-value pair.
         * 
         * @param key The key
         * @param content The value
         * @param flag Store flag (INSERT or REPLACE)
         * @return 0 on success, non-zero on error
         */
        [CCode (cname = "gdbm_store_wrapper")]
        public int store(string key, GLib.Bytes content, StoreFlag flag = StoreFlag.REPLACE);

        /**
         * Deletes a key from the database.
         * 
         * @param key The key to delete
         * @return 0 on success, -1 on error
         */
        [CCode (cname = "gdbm_delete_wrapper")]
        public int delete(string key);

        /**
         * Gets the first key for iteration.
         * 
         * @return First key, or null if database is empty
         */
        [CCode (cname = "gdbm_firstkey_wrapper")]
        public string? first_key();

        /**
         * Gets the next key in iteration.
         * 
         * @param prev_key Previous key
         * @return Next key, or null if no more keys
         */
        [CCode (cname = "gdbm_nextkey_wrapper")]
        public string? next_key(string prev_key);

        /**
         * Synchronizes the database to disk.
         */
        [CCode (cname = "gdbm_sync")]
        public void sync();

        /**
         * Reorganizes the database to reclaim space.
         * 
         * @return 0 on success, -1 on error
         */
        [CCode (cname = "gdbm_reorganize")]
        public int reorganize();

        /**
         * Gets the error code for the last operation.
         * 
         * @return Error code
         */
        [CCode (cname = "gdbm_last_errno")]
        public ErrorCode last_errno();

        /**
         * Gets the error message for the last operation.
         * 
         * @return Error message string
         */
        [CCode (cname = "gdbm_db_strerror")]
        public unowned string db_strerror();

        /**
         * Clears the error status.
         */
        [CCode (cname = "gdbm_clear_error")]
        public void clear_error();

        /**
         * Gets the file name of the database.
         * 
         * @return File name string
         */
        [CCode (cname = "gdbm_dbname")]
        public unowned string? dbname();
    }

    /**
     * Gets a string describing an error code.
     * 
     * @param error Error code
     * @return Error description string
     */
    [CCode (cname = "gdbm_strerror")]
    public unowned string strerror(ErrorCode error);
}