Back to LiteX page
LiteX++ is a simple C++ wrapper around SQLite3 C native
API.
Sources of this library you can find in LiteX_pp
subdirectory of LiteX package (see also
library usage).
To use this library
you must have basic knowledge about C++ language and SQLite3
native C API.
Most of classes methods are inline.
Because
most of class methods are inline compiler can generate really fast
code.
Support for Unicode (UTF-16LE).
LiteX++
uses _T( )
macro and TCHAR
psedo type from
tchar.h
header.
In Unicode version of this library
UTF-16 version of SQLite3 C API routines (eg. sqlite3_open16,
sqlite3_errmsg16) are used whenever possible.
In
non-Unicode (ANSI) version of this library every string is encoded
to UTF-8 string.
This behavior makes that strings in SQLite3
database are stored as UTF-8 or UTF-16 text that makes SQLite3
database more portable. For example database created by this library
can be easly accessed by LiteX
Automation library and vice versa.
LiteX++ uses STL standard library.
STL
library is mainly used to string handling. LiteX++ typedef-s
own string type _tstring as
std::string_base<TCHAR>.
LiteX++ also throws
exceptions derived from std::runtime_class.
Public domain code.
You
may use this library whenever you want without any restrictions!
All classes and helper functions are groupped into litex namespace:
using namespace litex;
This class is used by LiteX++ library to throw exceptions indicating error from SQLite3 library.
Method(s) |
Description |
Sample code / Comments |
---|---|---|
int get_ErrorCode() const |
Gets error code from SQLite3 library. |
try { .... } catch( SQLiteException& e ) { tcerr << _T("Error code: ") << e.get_ErrorCode() << endl; } |
const _tstring& get_Message() const |
Gets error mesage from SQLite3 library. |
try { .... } catch( SQLiteException& e ) { tcerr << _T("Error message: ") << e.get_Message() << endl; } |
static
void
Throw( int
nErrorCode, sqlite3* pDb ) |
Throws SQLiteException when
error code is not equal to SQLITE_OK. |
SQLiteConnection db; ... SQLiteException::Throw( nErrorCode, db ); |
This class is used by LiteX++ library to indicate its
own runtime errors.
Note that not all errors are indicated. For
example parameters validation.
Parameters validation is prformed
only in DEBUG mode by assert macro/function from
<cassert> header.
This enables to produce fast
code without unnessesary validation in RELEASE mode.
Method(s) |
Description |
Sample code / Comments |
---|---|---|
_tstring get_Message() const |
Gets error message. |
try { ... } catch( SQLiteRuntimeException& e ) { tcerr << _T("LiteX++ exception: ") << e.get_Message() << endl; } |
static void Throw( const _tstring& sMsg ) |
Throws SQLiteRuntimeException with specified error message. |
|
This is a wrapper class around sqlite3* handle and represents connection to SQLite database.
Constructor |
Description |
Sample code / Comments |
---|---|---|
SQLiteConnection() |
Default constructor. |
SQLiteConnection db; db.Open( _T("some.db") ); if ( db ) { db.Close(); } |
SQLiteConnection( const _tstring& sDbPath ) |
Initializes object and opens sDbPath database
file. |
|
SQLiteConnection( const TCHAR* pszDbPath ) |
Initializes object and opens pszDbPath database
file. |
SQLiteConnection db( _T("some.db") ); |
SQLiteConnection( SQLiteConnection& db ) |
Copy constructor. Constructing object takes ownership of sqlite3* handle and db object is detached from this handle. |
SQLiteConnection db( _T("some.db") ); if ( db ) tcout << _T("Database is opened.") << endl; SQLiteConnection other_db( db ); if ( !db ) tcout << _T("Database is detached.") << endl; if ( other_db ) tcout << _T("Databasse is attached.") << endl; |
Method(s) |
Description |
Sample code / Comments |
---|---|---|
bool Open( const _tstring& sDbPath ) |
Creates and/or opens sDbPath database file. Returns true if
database is created/opened. |
Wrapper aroud sqlite3_open(16) function. |
bool OpenInMemory() |
Creates and opens empty in-memory
database. |
If you want to create in-memory database in
constructor use MEMORY_DB string: |
void Close() |
Closes previously opened database. |
Wrapper around sqlite3_close function. |
void Interrupt() |
This function causes any pending database operation to abort and return at its earliest opportunity. |
Wrapper around sqlite3_interrupt function. |
sqlite_int64 get_LastInsertRowid() const |
The following routine returns the integer key of the most recent insert in the database. |
Wrapper around sqlite3_last_insert_rowid function. |
int get_Changes() const |
This function returns the number of database rows that were changed (or inserted or deleted) by the most recent executed statement. |
Wrapper around sqlite3_changes function. |
int get_TotalChanges() const |
This function returns the number of database rows
that have been |
Wrapper around sqlite3_total_changes function. |
void
BatchExecute( const
TCHAR* pszSql ) |
Executes many SQL statements at once. |
|
void
ExecuteNonQuery( const
TCHAR* szSql ) |
Executes single SQL statement that doesn't returns any results. |
|
int
ExecuteScalarInt( const
_tstring& sSql ) |
Executes singleton SQL statement (statement that
returs one row with one column) and returns its result. |
In fact statements may returs many rows witch many columns but only first row is fetched and and value from first column is returned.
int nMax = db.ExecuteScalarInt( _T("SELECT max(a) FROM test") ); |
SQLiteStatement
Prepare( const
_tstring& sSql) |
Prepares SQL statement and returns SQLiteStatement object. |
|
void
BeginTransaction() |
Transaction begining, commiting and rollbacking. |
db.BeginTransaction() etc. |
static _tstring get_VersionString() |
SQLite3 library version string. |
tcout << _T("Hello from SQLite3 version ") << SQLiteConnection::get_VersionString() << endl; |
static int get_VersionNumber() |
SQLitte3 library version number. |
tcout << _T("Hello from SQLite3 version ") << SQLiteConnection::get_VersionNumber() << endl; |
Operator |
Description |
Sample code / Comments |
---|---|---|
operator sqlite3*() const |
Access to sqlite3* handle. |
sqlite3* pDb = db; |
operator bool() const |
Test if database is open. |
|
This is a wrapper class around sqlite3_statement* handle and represents prepared SQL statement.
In most cases you do not create this object explicitly but use SQLiteConnection::Prepare method to build this object.
Constructor |
Description |
Sample code / Comments |
---|---|---|
SQLiteStatement( SQLiteConnection& connection ) |
Initializes empty object. |
SQLiteStatement stmt(db); ... stmt.Prepare(_T("SELECT * FROM Test")); |
SQLiteStatement( SQLiteConnection& connection, const TCHAR* pszSql ) |
Initializes object and prepares pszSql
statement. |
SQLiteStatement stmt( db, _T("SELECT * FROM Test") ); |
SQLiteStatement( SQLiteConnection& connection, const _tstring& sSql ) |
nitializes object and prepares sSql
statement. |
|
SQLiteStatement( SQLiteStatement& stmt ) |
Copy constructor. |
SQLiteStatement stmt( db.Prepare(_T("SELECT * FROM Test")) ); |
Method(s) |
Description |
Sample code / Comments |
---|---|---|
SQLiteConnection& get_Connection() const |
Gets SQLiteConnection object reference associated with this object. |
SQliteConnection& stmt_db = stmt.get_Connection(); |
void
Prepare( const
_tstring& sSql ) |
Prepares SQL statement. |
stmt.Prepare(_T("SELECT * FROM Test")); |
void Reset() |
Resets previously prepared statement to its initial state, ready to re-executed. |
stmt.Reset() |
void Finalize() |
Deletes previously prepared statement. |
Destructor also finalizes prepared statement if you do not call this method. |
int get_ParameterCount() const |
Number of statement parameters. |
|
_tstring get_ParameterName( int nParam ) const |
Gets name of nParam-th parameter. |
int nParamCount = stmt.get_ParameterCount(); for( int i=1; i<=nParamCount; i++ ) { tcout << _T("Parameter ") << i << _T(": ") << stmt.get_ParameterName(i) << endl; }
|
void
BindBlob( int
nParam, const
void*
pBlock, int
nSize ) |
Binds BLOB to statement's parameter. |
static const BYTE blob[4] = { 0x01, 0x02, 0x03, 0x04 }; ... stmt.BindBlob( 1, blob, 4 ) stmt.BindBlob( _T(":blob_parameter"), blob, 4 ); |
void
BindDouble( int
nParam, double
val ) |
Binds floating-point value to statement's
parameter. |
stmt.BindDouble( 2, 1.7888888 ); stmt.BindDouble( _T(":double_parameter"), 1.7888888 ); |
void
BindInt( int
nParam, int
val ) |
Binds integer value to statement's parameter. |
stmt.BindInt( 3, 1234 ); stmt.BindInt( _T(":int_parameter"), 1234 ); |
void
BindInt64( int
nParam, sqlite_int64 val ) |
Binds 64-bit integer value to statement's
parameter. |
stmt.BindInt64( 4, 1234123456 ); stmt.BindInt64( _T(":int64_parameter"), 1234123456 ); |
void
BindText( int nParam, const
TCHAR* val ) |
Binds text to statement's parameter. |
tostringstream ss; ss << _T("-=<") << hex << rand() << _T(">=-"); stmt.BindText( 5, ss.str() ); stmt.BindText( _T(":str_parameter"), SQLiteConnection::get_VersionString() ) |
void
BindNull( int
nParam ) |
Binds NULL value to statement's parameter. |
stmt.BindNull( 6 ); stmt.BindNull( _T(":nil_parameter") ); |
int get_ColumnCount() const |
Returns the number of columns in the result set returned by the prepared statement. |
|
_tstring get_ColumnName( int nColIdx ) |
This function returns the column heading for the nColIdx-th column of prepared statement. |
int nColumnCount = stmt.get_ColumnCount(); for( int i=0; i<nColumnCount; i++ ) { tcout << _T("Column ") << 1 << _T(": ") << stmt.get_ColumnName(i) << endl; }
|
_tstring get_ColumnDecltype( int nColIdx ) |
Returns declared type of nColIDx-th column. |
tcout << _T("Declared column type: ") << stmt.get_ColumnDecltype(0) << endl; |
bool Step() |
One step execution of prepared statement. One step return one row. Returns true if new row is fetched and flase when end of record set was reached. |
SQLiteStatement stmt( db, _T("SELECT * FROM TEST") ); while( stmt.Step() ) { // dump data here }
|
void Execute() |
Non-query statement execution. |
SQLiteStatement stmt( db, _T("INSERT INTO Table(a) VALUES(?)") ); for( int i=0; i<100; i++ ) { stmt.BindInt( 1, i ); stmt.Execute(); }
Instead of calling
|
int get_DataCount() const |
Returns the number of values in the current row of
the result set. |
|
const void* get_ColumnBlob( int nColIdx, int& nBlobSize ) const |
Returns BLOB and its size of nColIdx-th column in the current row of the result set. |
int nBlobSize; const void* pBlob = stmt.get_ColumnBlob(0,nBlobSize); tcout << _T("Blob size: ") << nBlobSize << endl; |
double get_ColumnDouble( int nColIdx ) const |
Returns floating-point value of nColIdx-th column in the current row of the result set. |
|
int get_ColumnInt( int nColIdx ) const |
Returns integer value of nColIdx-th column in the current row of the result set. |
|
sqlite_int64 get_ColumnInt64( int nColIdx ) const |
Returns 64-bit integer value of nColIdx-th column in the current row of the result set. |
|
_tstring get_ColumnText( int nColIdx ) const |
Returns text value of nColIdx-th column in the current row of the result set. |
|
int get_ColumnType( int nColIdx ) const |
Returns type of nColIdx-th column in
the current row of the result set. |
switch( stmt.get_ColumnType(n) ) { case SQLITE_INTEGER: tcout << _T("INTEGER: ") << stmt.get_ColumnInt(n) << endl; break; case SQLITE_FLOAT: tcout << _T("FLOAT: ") << stmt.get_ColumnDouble(n) << endl; break; case SQLITE_TEXT: tcout << _T("TEXT: ") << stmt.get_ColumnText(n) << endl; break; case SQLITE_BLOB: tcout << _T("BLOB") << endl; break; case SQLITE_NULL: tcout << _T("NULL") << endl; break; }
|
bool IsNull( int nColIdx ) const |
Tests if nColIdx-th column in the current row of the result set has NULL value. |
if ( stmt.IsNull(n) ) tcout << _T("NULL value") << endl; |
Operator |
Description |
Sample code / Comments |
---|---|---|
operator sqlite3_stmt*() const |
Access to sqlite3_stmt* handle. |
sqlite3_stmt* pStmt = stmt; |
operator bool() const |
Test if object is prepared. |
|
Most of library stuff is included in LiteX.hpp header
file. Few functions are implemented in LiteX.cpp
file.
To use this library in your project simply add these two
files to your project ad use #include "LiteX.hpp"
directive in every module you want to use this library. There's
no LIB nor DLL file. That's because most of class methods are
inline.
All classes and functions are groupped into litex
namespace. Your project also must have access to sqlite3.h
header from SQLite3 package.
All files you can find in LiteX package in LiteX_pp subdirectory. In this directory you can also find simple console application that demonstrates how to use LiteX++ library.
This library works only on Windows platform. Porting to other
platforms is possible and requires text encoding routines change
only.
This library was tested with Visual Stusio C++ 6.0 (project
files included) and Visual Studio C++ .NET 2003/2005 compiler (only
2005 project files included).
When you register LiteX Automation library information about
location of sqlite3.dll
library is stored into registry.
LiteX Automation library exsports all native SQLite3 functions.
If you create application that uses dynamically linked native
SQLite3 API you must put another copy of sqlite3.dll
into the directory where this aplication resides (best solution) or
into directory specified by PATH
enviroment variable.
This second version of DLL is unnessesary but your application must
read LiteX Automation library location from registry. You may by hand
call LoadLibray and then GetProcAddress functions but
writing C++ applications you rather use header file with function
definitions (sqlite3.h
) and static import library
(sqlite3.lib
).
If you specify sqlite3.dll in your C++ project as delay-loaded
library (/DELAYLIB
linker option) you have control how
to load delay-loaded DLLs by own notification hooks. LiteX++ library
currently implements such simple notification hook that reads LiteX
Automation library location and load this DLL if nessesary. This even
works with Unicode version of LiteX Automation (sqlite3u.dll).
There
are 3 functions into litex::delayload
namespace:
Function |
Description |
Sample code |
---|---|---|
|
Installs own delay-load DLL notification hook.When |
|
|
Loads
Warning: Don't call this routine from DllMain function! |
|
|
Unloads previously loaded |
|
These functions are defined only if _LITEX_WITH_DELAYLOAD
macro is defined.
Note that using this functions makes only sense
if you set sqlite3.dll
library as delay-loaded DLL.
Do not use these functions if SQLite3 API is linked statically in
your project.
By using these functions you can still use header
and import library without calling LoadLibrary and
GetProcAddress by hand. All you need is to call set_handler()
or load_library()
function at the beginning of your
application (library) before any call to SQLite3 API. Look into
LiteX_pp
subdirectory to see how this technique works.
Contact: roed@onet.eu