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

rows :

return location for the number of rows in the result

columns :

return location for the number of columns in the result

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