e-dbhash

## e-dbhash e-dbhash — Simple DB-based hash table for strings |

## Synopsis

    struct              EDbHash;
    enum                EDbHashStatus;
    void                (*EDbHashFunc)                      (const gchar *key,
                                                             gpointer user_data);
    EDbHash *           e_dbhash_new                        (const gchar *filename);
    void                e_dbhash_add                        (EDbHash *edbh,
                                                             const gchar *key,
                                                             const gchar *data);
    void                e_dbhash_remove                     (EDbHash *edbh,
                                                             const gchar *key);
    EDbHashStatus       e_dbhash_compare                    (EDbHash *edbh,
                                                             const gchar *key,
                                                             const gchar *compare_data);
    void                e_dbhash_foreach_key                (EDbHash *edbh,
                                                             EDbHashFunc func,
                                                             gpointer user_data);
    void                e_dbhash_write                      (EDbHash *edbh);
    void                e_dbhash_destroy                    (EDbHash *edbh);

## Description

An EDbHash is a simple hash table of strings backed by a Berkeley DB file for permanent storage.

## Details

### struct EDbHash

    struct EDbHash {
    	EDbHashPrivate *priv;
    };

Contains only private data that should be read and manipulated using the functions below.

EDbHashPrivate *`priv`; | private data

### enum EDbHashStatus

    typedef enum {
    	E_DBHASH_STATUS_SAME,
    	E_DBHASH_STATUS_DIFFERENT,
    	E_DBHASH_STATUS_NOT_FOUND
    } EDbHashStatus;

Return codes for `e_dbhash_compare()`.

`E_DBHASH_STATUS_SAME` | The checksums match.
`E_DBHASH_STATUS_DIFFERENT` | The checksums differ.
`E_DBHASH_STATUS_NOT_FOUND` | The given key was not found.

### EDbHashFunc ()

    void                (*EDbHashFunc)                      (const gchar *key,
                                                             gpointer user_data);

Callback function used in `e_dbhash_foreach_key()`.

`key` : | a database key
`user_data` : | user data passed to `e_dbhash_foreach_key()`

### e_dbhash_new ()

    EDbHash *           e_dbhash_new                        (const gchar *filename);

Creates a new EDbHash structure and opens the given Berkeley DB file, creating the DB file if necessary.

`filename` : | path to a Berkeley DB file
Returns : | a new EDbHash

### e_dbhash_add ()

    void                e_dbhash_add                        (EDbHash *edbh,
                                                             const gchar *key,
                                                             const gchar *data);

Adds a database object for `key`.

`edbh` : | an EDbHash
`key` : | a database key
`data` : | a database object for `key`

### e_dbhash_remove ()

    void                e_dbhash_remove                     (EDbHash *edbh,
                                                             const gchar *key);

Removes the database object corresponding to `key`.

`edbh` : | an EDbHash
`key` : | a database key

### e_dbhash_compare ()

    EDbHashStatus       e_dbhash_compare                    (EDbHash *edbh,
                                                             const gchar *key,
                                                             const gchar *compare_data);

Compares `compare_data` to the database object corresponding to `key` using an MD5 checksum. Returns E_DBHASH_STATUS_SAME if the checksums match, E_DBHASH_STATUS_DIFFERENT if the checksums differ, or E_DBHASH_STATUS_NOT_FOUND if `key` is not present in the database.

`edbh` : | an EDbHash
`key` : | a database key
`compare_data` : | data to compare against the database
Returns : | a checksum comparison status

### e_dbhash_foreach_key ()

    void                e_dbhash_foreach_key                (EDbHash *edbh,
                                                             EDbHashFunc func,
                                                             gpointer user_data);

Calls `func` for each database object.

`edbh` : | an EDbHash
`func` : | a callback function
`user_data` : | data to pass to `func`

### e_dbhash_write ()

    void                e_dbhash_write                      (EDbHash *edbh);

Flushes database changes to disk.

`edbh` : | an EDbHash

### e_dbhash_destroy ()

    void                e_dbhash_destroy                    (EDbHash *edbh);

Closes the database file and frees the EDbHash.

`edbh` : | an EDbHash