|
|
|
MAFW Reference Manual | |
|---|---|---|---|---|
gboolean mafw_db_begin (void); #define mafw_db_bind_blob (stmt, col, val, size) #define mafw_db_bind_int (stmt, col, val) #define mafw_db_bind_int64 (stmt, col, val) #define mafw_db_bind_null (stmt, col) #define mafw_db_bind_text (stmt, col, val) gint mafw_db_change (sqlite3_stmt *stmt, gboolean csint_may_fail); #define mafw_db_column_blob (stmt, col) #define mafw_db_column_int #define mafw_db_column_int64 #define mafw_db_column_null (stmt, col) #define mafw_db_column_text (stmt, col) gboolean mafw_db_commit (void); gint mafw_db_delete (sqlite3_stmt *stmt); gint mafw_db_do (sqlite3_stmt *stmt); gint mafw_db_exec (gchar const *query); sqlite3* mafw_db_get (void); gint mafw_db_nchanges (void); sqlite3_stmt* mafw_db_prepare (gchar const *query); gboolean mafw_db_rollback (void); gint mafw_db_select (sqlite3_stmt *stmt, gboolean expect_row); void mafw_db_trace (void);
This is a set of functions to make like against sqlite a bit easier.
NOTE All binding macros starts counting columns from 0. This is different from the sqlite_bind_*() counterparts, which start indexing from 1, but is consistent with sqlite_column_*().
gboolean mafw_db_begin (void);
Convenience function to begin a new transaction. Returns whether it succeeded; on failure a warning is printed. It is an error to start a new transaction while the previous one is not closed.
| Returns : | TRUE if ok, FALSE otherwise
|
#define mafw_db_bind_blob(stmt, col, val, size)
Binds a byte value to a placeholder with the most commonplace parameters. It relies on the data value remaining valid until the statement is executed.
stmt : |
statement |
col : |
column to set the value |
val : |
new value |
size : |
size of the value |
#define mafw_db_bind_int(stmt, col, val)
Binds an integer value to a placeholder.
stmt : |
statement |
col : |
column to set the value |
val : |
new value |
#define mafw_db_bind_int64(stmt, col, val)
Binds a int64 value to a placeholder.
stmt : |
statement |
col : |
column to set the value |
val : |
new value |
#define mafw_db_bind_null(stmt, col)
Binds a NULL value to a placeholder with the most commonplace parameters.
stmt : |
statement |
col : |
column to set the value |
#define mafw_db_bind_text(stmt, col, val)
Binds a text value to a placeholder with the most commonplace parameters. It relies on the text value remaining valid until the statement is executed.
stmt : |
statement |
col : |
column to set the value |
val : |
new value |
gint mafw_db_change (sqlite3_stmt *stmt,
gboolean csint_may_fail);
Attempts to INSERT or UPDATE a row. On error an error message is printed unless it was an expected constraint violation.
stmt : |
the statement |
csint_may_fail : |
TRUE if operationg can fail
|
| Returns : | a sqlite error code |
#define mafw_db_column_blob(stmt, col)
Calls sqlite3_column_blob. Returns the data at column col.
stmt : |
statement |
col : |
column to get the value |
#define mafw_db_column_int sqlite3_column_int
Calls sqlite3_column_int. Returns the integer value at column col.
#define mafw_db_column_int64 sqlite3_column_int64
Calls sqlite3_column_int64. Returns the integer value at column col.
#define mafw_db_column_null(stmt, col)
Checks, whether the value at col is NULL or not.
stmt : |
statement |
col : |
column to check the value |
#define mafw_db_column_text(stmt, col)
Calls sqlite3_column_text, suppresses gcc's warnings about signed vs. unsigned pointers. Returns the text at column col.
stmt : |
statement |
col : |
column to get the value |
gboolean mafw_db_commit (void);
Like mafw_db_begin but COMMITS the active transaction. If it fails you should ROLLBACK your work.
| Returns : | TRUE if ok, FALSE otherwise.
|
gint mafw_db_delete (sqlite3_stmt *stmt);
Attempts to DELETE a row. On failure a warning is printed.
stmt : |
statement |
| Returns : | a sqlite error code |
gint mafw_db_do (sqlite3_stmt *stmt);
Tries to execute stmt until the database is unlocked.
Between retries SQLite waits for a random amount of time.
Note that you need to sqlite3_reset(stmt) after done
with it.
stmt : |
statement |
| Returns : | a sqlite error code. |
gint mafw_db_exec (gchar const *query);
Executes query, handling busy database errors, and returns the
result code of the operation. This function is mainly intended for
CREATE TABLE statements, so you should not execute any query that
returns any rows (SELECT), unless you are very sure about it.
Please note that any kind of errors are reported, eg. "table
already exist".
query : |
the query to execute |
| Returns : | a sqlite error code |
sqlite3* mafw_db_get (void);
Gets a handle to the framework database, taking care of the database creation and error handling. As this resource is global may not free it.
| Returns : | the handle |
gint mafw_db_nchanges (void);
Convenience function to obtain the number of rows changed due
to the last statement, as defined by sqlite3_changes().
| Returns : | a sqlite error code |
sqlite3_stmt* mafw_db_prepare (gchar const *query);
Gets the prepared statement equivalent of query, which should
contain exactly one SQL statement. Errors (like a syntax errors)
are treated fatal. Take into account that TABLES query refers to
must exist before you compile them with this function.
query : |
the query |
| Returns : | the statement |
gboolean mafw_db_rollback (void);
Like mafw_db_begin but ROLLBACKs the current transaction.
| Returns : | TRUE if ok, FALSE otherwise.
|
gint mafw_db_select (sqlite3_stmt *stmt,
gboolean expect_row);
Attempts to fetch the next row of a SELECT query. On error or if a row was expected but no more found an error message is printed. Returns the same code as sqlite3_exec.
stmt : |
the statement |
expect_row : |
TRUE if a row is expected
|
| Returns : | a sqlite error code |