## gva-db

gva-db — Database Management

## Synopsis

    gboolean            gva_db_init                         (GError **error);
    GvaProcess *        gva_db_build                        (GError **error);
    gboolean            gva_db_reset                        (GError **error);
    gboolean            gva_db_execute                      (const gchar *sql,
                                                             GError **error);
    gboolean            gva_db_get_table                    (const gchar *sql,
                                                             gchar ***result,
                                                             gint *rows,
                                                             gint *columns,
                                                             GError **error);
    gboolean            gva_db_transaction_begin            (GError **error);
    gboolean            gva_db_transaction_commit           (GError **error);
    gboolean            gva_db_transaction_rollback         (GError **error);
    gboolean            gva_db_prepare                      (const gchar *sql,
                                                             sqlite3_stmt **stmt,
                                                             GError **error);
    gboolean            gva_db_get_build                    (gchar **build,
                                                             GError **error);
    const gchar *       gva_db_get_filename                 (void);
    gboolean            gva_db_is_older_than                (const gchar *filename);
    gboolean            gva_db_needs_rebuilt                (void);
    void                gva_db_set_error                    (GError **error,
                                                             gint code,
                                                             const gchar *message);

## Description

These functions help manage the game database.

## Details

### gva_db_init ()

    gboolean            gva_db_init                         (GError **error);

Opens the games database and creates the tables if they do not already exist. If an error occurs, it returns `FALSE` and sets `error`.

This function should be called once when the application starts.

`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` if an error occurred

### gva_db_build ()

    GvaProcess *        gva_db_build                        (GError **error);

Begins the lengthy process of populating the games database and returns a GvaProcess to track it. The database is populated by parsing detailed game information generated by MAME. If an error occurs while starting the parsing process, it returns `NULL` and sets `error`.

`error` : | return location for a GError, or `NULL`
Returns : | a new GvaProcess, or `NULL`

### gva_db_reset ()

    gboolean            gva_db_reset                        (GError **error);

Removes all game information from the database and restores the tables to their initial state. If an error occurs, it returns `FALSE` and sets `error`.

`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` if an error occurred

### gva_db_execute ()

    gboolean            gva_db_execute                      (const gchar *sql,
                                                             GError **error);

Executes the given SQL statement without returning any results. This function is appropriate for one-off operations like "CREATE TABLE" or "BEGIN TRANSACTION". If an error occurs, it returns `FALSE` and sets `error`.

`sql` : | an SQL statement
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` if an error occurred

### gva_db_get_table ()

    gboolean            gva_db_get_table                    (const gchar *sql,
                                                             gchar ***result,
                                                             gint *rows,
                                                             gint *columns,
                                                             GError **error);

Executes the given SQL statement and returns the results as a string array (see `sqlite3_get_table()` for the array layout). This function is appropriate for SELECT statements that return a small result set. If an error occurs, it returns `FALSE` and sets `error`.

Use `g_strfreev()` to free `result`.

`sql` : | an SQL statement
`result` : | return location for the result, or `NULL`
`rows` : | return location for the number of rows in the result, or `NULL`
`columns` : | return location for the number of columns in the result, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` if an error occurred

### gva_db_transaction_begin ()

    gboolean            gva_db_transaction_begin            (GError **error);

Convenience function begins a database transaction. If an error occurs, it returns `FALSE` and sets `error`.

`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` if an error occurred

### gva_db_transaction_commit ()

    gboolean            gva_db_transaction_commit           (GError **error);

Convenience function commits a database transaction. If an error occurs, it returns `FALSE` and sets `error`.

`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` if an error occurred

### gva_db_transaction_rollback ()

    gboolean            gva_db_transaction_rollback         (GError **error);

Convenience function rolls back a database transaction. If an error occurs, it returns `FALSE` and sets `error`.

`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` if an error occurred

### gva_db_prepare ()

    gboolean            gva_db_prepare                      (const gchar *sql,
                                                             sqlite3_stmt **stmt,
                                                             GError **error);

Compiles the given SQL statement and assigns the resulting statement handle to *`stmt`. If an error occurs, it returns `FALSE` and sets `error`.

`sql` : | an SQL statement
`stmt` : | return location for a compiled statement handle
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` if an error occurred

### gva_db_get_build ()

    gboolean            gva_db_get_build                    (gchar **build,
                                                             GError **error);

Returns the build ID of the MAME executable from which the contents of the database was generated. If an error occurs, it returns `FALSE` and sets `error`.

`build` : | return location for the build ID
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` if an error occurred

### gva_db_get_filename ()

    const gchar *       gva_db_get_filename                 (void);

Returns the abolute path of the games database.

Returns : | filename for the games database

### gva_db_is_older_than ()

    gboolean            gva_db_is_older_than                (const gchar *filename);

Returns `TRUE` if `filename`'s creation or modification timestamp is more recent than the games database's modification timestamp. The games database relies in part on external data files that might have been updated since the database was last rebuilt. This function can detect that.

If `filename` does not exist or if the function has trouble comparing timestamps, it returns `FALSE` as a safe fallback.

`filename` : | a file or directory name
Returns : | `TRUE` if `filename` is newer than the games database

### gva_db_needs_rebuilt ()

    gboolean            gva_db_needs_rebuilt                (void);

Runs a series of tests to determine whether the game database is out-of-date and needs to be rebuilt. Examples of conditions that would cause a database rebuild are a new version of GNOME Video Arcade, a new version of MAME, database corruption, or if the user explicitly asked us to rebuild.

Returns : | `TRUE` if a rebuild is needed, `FALSE` if the database seems okay

### gva_db_set_error ()

    void                gva_db_set_error                    (GError **error,
                                                             gint code,
                                                             const gchar *message);

Does nothing if `error` is `NULL`; if `error` is non-`NULL`, then *`error` must be `NULL`. Converts an SQLite error code and error message to a GError and assigns it to *`error` with a domain of `GVA_SQLITE_ERROR`. If `message` is `NULL`, the function calls `sqlite3_errcode()` to obtain the error code and `sqlite3_errmsg()` to obtain the error message.

`error` : | return location for a GError, or `NULL`
`code` : | SQLite error code
`message` : | SQLite error message, or `NULL`