libsqlite3x  2007.10.18
Public Member Functions | Protected Member Functions | Friends | List of all members
sqlite3x::sqlite3_connection Class Reference

Represents a connection to an sqlite3 database. More...

#include <sqlite3x.hpp>

Public Member Functions

sqlite3 * db () const
 Returns a handle to the underlying sqlite3 database. More...
 
 sqlite3_connection ()
 Default ctor. More...
 
 sqlite3_connection (std::string const &dbname)
 Opens a database with the given name. More...
 
 sqlite3_connection (sqlite3 *dbh)
 See take(sqlite3*). More...
 
virtual ~sqlite3_connection ()
 Calls this->close() if close() has not already been called. More...
 
std::string name () const
 Returns this object's name. More...
 
virtual void open (char const *)
 Creates/opens the given db, throwing on error. More...
 
void open (std::string const &dbname)
 Functionally the same as open( char const *).
 
void take (sqlite3 *dbh)
 Transfers control of dbh to this object and makes this object point at dbh. More...
 
sqlite3 * take () throw ()
 Transfers ownership of the returned handle to the caller. More...
 
void close ()
 Closes this database. More...
 
int64_t insertid ()
 Returns the rowid of the most recently inserted row on this db.
 
int changes ()
 Returns the number of database rows that were changed (or inserted or deleted) by the most recently completed INSERT, UPDATE, or DELETE statement. More...
 
void setbusytimeout (int ms)
 See sqlite3_busy_timeout().
 
void executenonquery (const std::string &sql)
 Executes a command which is assumed to have a single step and a void result.
 
void executenonquery (char const *sql)
 Overloaded to avoid an internal copy of sql. More...
 
int executeint (const std::string &sql)
 Executes the query, which is expected to have an integer field as the first result field.
 
int executeint (char const *sql)
 Overloaded to avoid an internal copy of sql. More...
 
int64_t executeint64 (const std::string &sql)
 Executes the query, which is expected to have a (int64_t) field as the first result field.
 
int64_t executeint64 (char const *sql)
 Overloaded to avoid an internal copy of sql. More...
 
double executedouble (const std::string &sql)
 Executes the query, which is expected to have a double field as the first result field.
 
double executedouble (char const *sql)
 Overloaded to avoid an internal copy of sql. More...
 
std::string executestring (const std::string &sql)
 Executes the query, which is expected to have a string or blob field as the first result field. More...
 
std::string executeblob (const std::string &sql)
 Executes the query, which is expected to have a string or blob field as the first result field. More...
 
int executecallback (std::string const &sql, sqlite3_callback callback, void *data, std::string &errmsg)
 Executes the given SQL code, calling callback for each row of the data set. More...
 
int executecallback (std::string const &sql, sqlite3_callback callback, void *data=0)
 Convenience overload which has a default data value of 0 and ignores any error string passed back by sqlite3_exec().
 
std::string errormsg () const
 Returns the equivalent of sqlite3_errmsg(), or an empty string if that function returns null. More...
 

Protected Member Functions

virtual void on_open ()
 This function is called when open() succeeds. More...
 

Friends

class sqlite3_command
 

Detailed Description

Represents a connection to an sqlite3 database.

About the only reason to subclass this type would be to do customizations to the underlying sqlite3 db handle upon construction of each object, e.g. to add custom sqlite functions or load custom modules.

Definition at line 148 of file sqlite3x.hpp.

Constructor & Destructor Documentation

◆ sqlite3_connection() [1/3]

sqlite3x::sqlite3_connection::sqlite3_connection ( )

Default ctor.

DB is unusable until open() is called.

Definition at line 39 of file sqlite3x_connection.cpp.

◆ sqlite3_connection() [2/3]

sqlite3x::sqlite3_connection::sqlite3_connection ( std::string const &  dbname)
explicit

Opens a database with the given name.

Throws if this->open(dbname) fails.

Definition at line 41 of file sqlite3x_connection.cpp.

References open().

◆ sqlite3_connection() [3/3]

sqlite3x::sqlite3_connection::sqlite3_connection ( sqlite3 *  dbh)

See take(sqlite3*).

This ctor is identical except that it throws if passed a null pointer.

Definition at line 51 of file sqlite3x_connection.cpp.

References take().

◆ ~sqlite3_connection()

sqlite3x::sqlite3_connection::~sqlite3_connection ( )
virtual

Calls this->close() if close() has not already been called.

If it calls close() then the exception is silently ignored for the sake of having a no-throw dtor.

Definition at line 61 of file sqlite3x_connection.cpp.

References close().

Member Function Documentation

◆ changes()

int sqlite3x::sqlite3_connection::changes ( )

Returns the number of database rows that were changed (or inserted or deleted) by the most recently completed INSERT, UPDATE, or DELETE statement.

SQLite implements the command "DELETE FROM table" without a WHERE clause by dropping and recreating the table. To get an accurate count of the number of rows deleted, use "DELETE FROM table WHERE 1" instead.

Definition at line 183 of file sqlite3x_connection.cpp.

◆ close()

void sqlite3x::sqlite3_connection::close ( )

Closes this database.

If the db is not opened, this is a no-op.

Definition at line 169 of file sqlite3x_connection.cpp.

Referenced by sqlite3x::settings_db::close(), open(), take(), and ~sqlite3_connection().

◆ db()

sqlite3 * sqlite3x::sqlite3_connection::db ( ) const

Returns a handle to the underlying sqlite3 database.

Friend classes should NEVER call sqlite3_close() on this handle. Doing so will result in undefined behaviour later on (when this class is used or destructs).

This function is only public so that clients can do things like register new sqlite3 functions with the database.

Definition at line 104 of file sqlite3x_connection.cpp.

Referenced by open(), and sqlite3x::sqlite3_command::prepare().

◆ errormsg()

std::string sqlite3x::sqlite3_connection::errormsg ( ) const

Returns the equivalent of sqlite3_errmsg(), or an empty string if that function returns null.

Reminder: the sqlite3 docs say that sqlite3_errmsg() always returns a non-empty string, even if the string is "not an error" (no joke).

Definition at line 114 of file sqlite3x_connection.cpp.

Referenced by sqlite3x::sqlite3_cursor::reset().

◆ executeblob()

std::string sqlite3x::sqlite3_connection::executeblob ( const std::string &  sql)

Executes the query, which is expected to have a string or blob field as the first result field.

Note that numeric results can be returned using this function, but will come back as a string (lexically cast).

Definition at line 285 of file sqlite3x_connection.cpp.

References sqlite3x::sqlite3_command::executeblob().

◆ executecallback()

int sqlite3x::sqlite3_connection::executecallback ( std::string const &  sql,
sqlite3_callback  callback,
void *  data,
std::string &  errmsg 
)

Executes the given SQL code, calling callback for each row of the data set.

The data pointer is passed on as-is to the callback, and may be 0. If execution generates an error message it is stored in errmsg.

If this function intercepts an exception (thrown from the callback) then it propagates that exception back to the caller. If it catches no exception, it returns the result code, with zero being success and non-zero being failure.

See sqlite3_exec() for more details.

Definition at line 297 of file sqlite3x_connection.cpp.

Referenced by executecallback().

◆ executedouble()

double sqlite3x::sqlite3_connection::executedouble ( char const *  sql)

Overloaded to avoid an internal copy of sql.

sql MUST be non-NULL and null-terminated.

Definition at line 243 of file sqlite3x_connection.cpp.

References sqlite3x::sqlite3_command::executedouble().

◆ executeint()

int sqlite3x::sqlite3_connection::executeint ( char const *  sql)

Overloaded to avoid an internal copy of sql.

sql MUST be non-NULL and null-terminated.

Definition at line 212 of file sqlite3x_connection.cpp.

References sqlite3x::sqlite3_command::executeint().

◆ executeint64()

int64_t sqlite3x::sqlite3_connection::executeint64 ( char const *  sql)

Overloaded to avoid an internal copy of sql.

sql MUST be non-NULL and null-terminated.

Definition at line 227 of file sqlite3x_connection.cpp.

References sqlite3x::sqlite3_command::executeint64().

◆ executenonquery()

void sqlite3x::sqlite3_connection::executenonquery ( char const *  sql)

Overloaded to avoid an internal copy of sql.

sql MUST be non-NULL and null-terminated.

Definition at line 200 of file sqlite3x_connection.cpp.

References sqlite3x::sqlite3_command::executenonquery().

◆ executestring()

std::string sqlite3x::sqlite3_connection::executestring ( const std::string &  sql)

Executes the query, which is expected to have a string or blob field as the first result field.

Note that numeric results can be returned using this function, but will come back as a string (lexically cast).

Definition at line 259 of file sqlite3x_connection.cpp.

References sqlite3x::sqlite3_command::executestring().

◆ name()

std::string sqlite3x::sqlite3_connection::name ( ) const

Returns this object's name.

It is only valid if the (char const *) ctor or open(char const *) was used with a non-null name, otherwise it is an empty string.

Definition at line 109 of file sqlite3x_connection.cpp.

◆ on_open()

void sqlite3x::sqlite3_connection::on_open ( )
protectedvirtual

This function is called when open() succeeds.

Subclasses which wish to do custom db initialization or sanity checks may do them here.

Definition at line 120 of file sqlite3x_connection.cpp.

Referenced by open(), and take().

◆ open()

void sqlite3x::sqlite3_connection::open ( char const *  db)
virtual

Creates/opens the given db, throwing on error.

Remember that sqlite3 supports the name ":memory:" as a pseudo-name for an in-memory database.

On success it returns, else it throws.

Note that sqlite3 supports the special db name ":memory:" to represent an in-memory database. Such databases cannot be saved directly to disk and are lost when this object closes the db.

Internal notes:

Once an sqlite3_open() succeeds, the protected member this->on_open() in called. That member should throw on error.

Subclasses which override this and do not want to call the base implementation should call on_open() when done to allow subclasses to initialize the database if they like.

Definition at line 124 of file sqlite3x_connection.cpp.

References close(), db(), and on_open().

Referenced by open(), and sqlite3_connection().

◆ take() [1/2]

void sqlite3x::sqlite3_connection::take ( sqlite3 *  dbh)

Transfers control of dbh to this object and makes this object point at dbh.

dbh is assumed to be a valid, opened sqlite3 db handle.

If this->db() == dbh then this function does nothing.

If this object had an opened db handle then it is closed before dbh is taken. Closing may throw, but this function takes ownership of dbh regardless of whether it throws or not.

If dbh is null, the effect is identical to calling close().

This function triggers the protected on_open() function if dbh is not null.

Definition at line 74 of file sqlite3x_connection.cpp.

References close(), and on_open().

◆ take() [2/2]

sqlite3 * sqlite3x::sqlite3_connection::take ( )
throw (
)

Transfers ownership of the returned handle to the caller.

This object is then considered closed. NULL is returned if this object is closed.

Definition at line 97 of file sqlite3x_connection.cpp.

Referenced by sqlite3_connection().


The documentation for this class was generated from the following files: