gva-db

gva-db — Database Management

Functions

Description

These functions help manage the game database.

Functions

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.

Parameters

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 .

Parameters

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 .

Parameters

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 .

Parameters

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 .

Parameters

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 .

Parameters

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 .

Parameters

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 .

Parameters

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 .

Parameters

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 .

Parameters

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_complete ()

gboolean
gva_db_get_complete (gboolean *complete,
                     GError **error);

Returns whether the database contents are complete.

If the application terminated prematurely during the last database rebuild, its "complete" flag won't be set. gva_db_needs_rebuilt() checks this flag as one of its tests.

If an error occurs while querying the database, the function returns FALSE and sets error .

Parameters

complete

return location for the "complete" flag

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE if an error occurred


gva_db_mark_complete ()

gboolean
gva_db_mark_complete (GError **error);

Updates the games database to indicate its contents are complete. Call this after rebuilding the database and performing a ROM analysis.

If the application terminated prematurely during the last database rebuild, its "complete" flag won't be set. gva_db_needs_rebuilt() checks this flag as one of its tests.

Parameters

error

return location for a GError, or NULL

 

Returns

TRUE if the database was successfully updated


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.

Parameters

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 or incomplete 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, the last database rebuild terminated prematurely, 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.

Parameters

error

return location for a GError, or NULL

 

code

SQLite error code

 

message

SQLite error message, or NULL