1
///////////////////////////////////////////////////////////////////////////////
3
// Purpose: wxWidgets wrapper around the SQLite3 embedded database library.
4
// Author: Ulrich Telle
7
// Copyright: (c) Ulrich Telle
8
// Licence: wxWindows licence
9
///////////////////////////////////////////////////////////////////////////////
11
/// \file wxsqlite3.h Interface of the wxSQLite3 class
13
#ifndef _WX_SQLITE3_H_
14
#define _WX_SQLITE3_H_
16
#if defined(__GNUG__) && !defined(__APPLE__)
17
#pragma interface "wxsqlite3.h"
21
#include <wx/arrstr.h>
22
#include <wx/datetime.h>
23
#include <wx/buffer.h>
24
#include <wx/hashmap.h>
26
#include <wx/string.h>
28
#include "wxsqlite3def.h"
30
#define WXSQLITE_ERROR 1000
32
#define WXSQLITE_INTEGER 1
33
#define WXSQLITE_FLOAT 2
34
#define WXSQLITE_TEXT 3
35
#define WXSQLITE_BLOB 4
36
#define WXSQLITE_NULL 5
38
#if defined(_MSC_VER) || defined(__BORLANDC__)
39
typedef __int64 wxsqlite_int64;
41
typedef long long int wxsqlite_int64;
44
/// Enumeration of transaction types
45
enum wxSQLite3TransactionType
47
WXSQLITE_TRANSACTION_DEFAULT,
48
WXSQLITE_TRANSACTION_DEFERRED,
49
WXSQLITE_TRANSACTION_IMMEDIATE,
50
WXSQLITE_TRANSACTION_EXCLUSIVE
53
/// Enumeration of SQLite limitation types
54
enum wxSQLite3LimitType
56
WXSQLITE_LIMIT_LENGTH = 0,
57
WXSQLITE_LIMIT_SQL_LENGTH = 1,
58
WXSQLITE_LIMIT_COLUMN = 2,
59
WXSQLITE_LIMIT_EXPR_DEPTH = 3,
60
WXSQLITE_LIMIT_COMPOUND_SELECT = 4,
61
WXSQLITE_LIMIT_VDBE_OP = 5,
62
WXSQLITE_LIMIT_FUNCTION_ARG = 6,
63
WXSQLITE_LIMIT_ATTACHED = 7,
64
WXSQLITE_LIMIT_LIKE_PATTERN_LENGTH = 8,
65
WXSQLITE_LIMIT_VARIABLE_NUMBER = 9,
66
WXSQLITE_LIMIT_TRIGGER_DEPTH = 10
69
/// Enumeration of journal modes
70
enum wxSQLite3JournalMode
72
WXSQLITE_JOURNALMODE_DELETE = 0, // Commit by deleting journal file
73
WXSQLITE_JOURNALMODE_PERSIST = 1, // Commit by zeroing journal header
74
WXSQLITE_JOURNALMODE_OFF = 2, // Journal omitted.
75
WXSQLITE_JOURNALMODE_TRUNCATE = 3, // Commit by truncating journal
76
WXSQLITE_JOURNALMODE_MEMORY = 4, // In-memory journal file
77
WXSQLITE_JOURNALMODE_WAL = 5 // Use write-ahead logging
80
#define WXSQLITE_OPEN_READONLY 0x00000001
81
#define WXSQLITE_OPEN_READWRITE 0x00000002
82
#define WXSQLITE_OPEN_CREATE 0x00000004
83
#define WXSQLITE_OPEN_NOMUTEX 0x00008000
84
#define WXSQLITE_OPEN_FULLMUTEX 0x00010000
85
#define WXSQLITE_OPEN_SHAREDCACHE 0x00020000
86
#define WXSQLITE_OPEN_PRIVATECACHE 0x00040000
88
#define WXSQLITE_CHECKPOINT_PASSIVE 0
89
#define WXSQLITE_CHECKPOINT_FULL 1
90
#define WXSQLITE_CHECKPOINT_RESTART 2
92
inline void operator++(wxSQLite3LimitType& value)
94
value = wxSQLite3LimitType(value+1);
98
class EXTAPI wxSQLite3Exception
102
wxSQLite3Exception(int errorCode, const wxString& errMsg);
105
wxSQLite3Exception(const wxSQLite3Exception& e);
108
virtual ~wxSQLite3Exception();
110
/// Get error code associated with the exception
111
int GetErrorCode() const { return (m_errorCode & 0xff); }
113
/// Get extended error code associated with the exception
114
int GetExtendedErrorCode() const { return m_errorCode; }
116
/// Get error message associated with the exception
117
const wxString GetMessage() const { return m_errorMessage; }
119
/// Convert error code to error message
120
static const wxString ErrorCodeAsString(int errorCode);
123
int m_errorCode; ///< SQLite3 error code associated with this exception
124
wxString m_errorMessage; ///< SQLite3 error message associated with this exception
127
/// SQL statment buffer for use with SQLite3's printf method
128
class EXTAPI wxSQLite3StatementBuffer
132
wxSQLite3StatementBuffer();
135
~wxSQLite3StatementBuffer();
137
/// Format a SQL statement using SQLite3's printf method
139
* This method is a variant of the "sprintf()" from the standard C library.
140
* All of the usual printf formatting options apply. In addition,
141
* there is a "%q" option. %q works like %s in that it substitutes
142
* a null-terminated string from the argument list. But %q also
143
* doubles every '\'' character. %q is designed for use inside a
144
* string literal. By doubling each '\'' character it escapes that
145
* character and allows it to be inserted into the string.
147
* For example, so some string variable contains text as follows:
149
* char *zText = "It's a happy day!";
151
* One can use this text in an SQL statement as follows:
153
* wxSQLite3StatementBuffer stmtBuffer;
154
* stmtBuffer.Format("INSERT INTO table VALUES('%q')", zText);
156
* Because the %q format string is used, the '\'' character in
157
* zText is escaped and the SQL generated is as follows:
159
* INSERT INTO table1 VALUES('It''s a happy day!')
161
* \param format SQL statement string with formatting options
162
* \param ... list of statement parameters
163
* \return const char pointer to the resulting statement buffer
165
const char* Format(const char* format, ...);
167
/// Format a SQL statement using SQLite3's printf method
169
* This method is like method Format but takes a va_list argument
170
* to pass the statement parameters.
172
* \param format SQL statement string with formatting options
173
* \param va va_list of statement parameters
174
* \return const char pointer to the resulting statement buffer
176
const char* FormatV(const char* format, va_list va);
178
/// Dereference the internal buffer
180
* \return const char pointer to the resulting statement buffer
182
operator const char*() const { return m_buffer; }
184
/// Clear the internal buffer
188
char* m_buffer; ///< Internal buffer
191
/// Context for user defined scalar or aggregate functions
193
* A function context gives user defined scalar or aggregate functions
194
* access to function arguments and function results. The "Execute" method
195
* resp. the "Aggregate" and "Finalize" methods receive the current
196
* function context as an argument.
198
class EXTAPI wxSQLite3FunctionContext
201
/// Get the number of function arguments
203
* \return the number of arguments the function was called with
207
/// Get the type of a function argument
209
* \param argIndex index of the function argument. Indices start with 0.
210
* \return argument type as one of the values WXSQLITE_INTEGER, WXSQLITE_FLOAT, WXSQLITE_TEXT, WXSQLITE_BLOB, or WXSQLITE_NULL
212
int GetArgType(int argIndex);
214
/// Check whether a function argument is a NULL value
216
* \param argIndex index of the function argument. Indices start with 0.
217
* \return TRUE if the argument is NULL or the argIndex is out of bounds, FALSE otherwise
219
bool IsNull(int argIndex);
221
/// Get a function argument as an integer value
223
* \param argIndex index of the function argument. Indices start with 0.
224
* \param nullValue value to be returned in case the argument is NULL
225
* \return argument value
227
int GetInt(int argIndex, int nullValue = 0);
229
/// Get a function argument as an 64-bit integer value
231
* \param argIndex index of the function argument. Indices start with 0.
232
* \param nullValue value to be returned in case the argument is NULL
233
* \return argument value
235
wxLongLong GetInt64(int argIndex, wxLongLong nullValue = 0);
237
/// Get a function argument as a double value
239
* \param argIndex index of the function argument. Indices start with 0.
240
* \param nullValue value to be returned in case the argument is NULL
241
* \return argument value
243
double GetDouble(int argIndex, double nullValue = 0);
245
/// Get a function argument as a string value
247
* \param argIndex index of the function argument. Indices start with 0.
248
* \param nullValue value to be returned in case the argument is NULL
249
* \return argument value
251
wxString GetString(int argIndex, const wxString& nullValue = wxEmptyString);
253
/// Get a function argument as a BLOB value
255
* \param argIndex index of the function argument. Indices start with 0.
256
* \param[out] len length of the blob argument in bytes
257
* \return argument value
259
const unsigned char* GetBlob(int argIndex, int& len);
261
/// Get a function argument as a BLOB value
263
* \param argIndex index of the function argument. Indices start with 0.
264
* \param[out] buffer to which the blob argument value is appended
265
* \return reference to argument value
267
wxMemoryBuffer& GetBlob(int argIndex, wxMemoryBuffer& buffer);
269
/// Set the function result as an integer value
271
* \param value function result value
273
void SetResult(int value);
275
/// Set the function result as an 64-bit integer value
277
* \param value function result value
279
void SetResult(wxLongLong value);
281
/// Set the function result as a double value
283
* \param value function result value
285
void SetResult(double value);
287
/// Set the function result as a string value
289
* \param value function result value
291
void SetResult(const wxString& value);
293
/// Set the function result as a BLOB value
295
* \param value function result value
296
* \param len length of the result blob in bytes
298
void SetResult(unsigned char* value, int len);
300
/// Set the function result as a BLOB value
302
* \param buffer containing the function result value
304
void SetResult(const wxMemoryBuffer& buffer);
306
/// Set the function result as a NULL value
307
void SetResultNull();
309
/// Set the function result as a zero BLOB value
311
* \param blobSize size of the zero filled BLOB value
313
void SetResultZeroBlob(int blobSize);
315
/// Set the function result as a exact copy of a function argument
317
* \param argIndex index of the argument which should be copied as the result value
319
void SetResultArg(int argIndex);
321
/// Set an error message as the function result
323
* \param errmsg string containing an error message
325
void SetResultError(const wxString& errmsg);
327
/// Get the number of aggregate steps
329
* \return the number of aggregation steps. The current aggregation step counts so at least 1 is returned.
331
int GetAggregateCount();
333
/// Get a pointer to an aggregate structure of specified length
335
* Usually an aggregation functions needs temporary memory to collect
336
* the information gathered from each invocation of the "Aggregate" method.
337
* On the first invocation of this method the returned memory contains
339
* If this memory is used to store pointers to allocated objects,
340
* it is important to free all allocated objects in the "Finalize" method.
342
* \param len amount of memory needed in bytes
343
* \return pointer to the allocated memory
345
void* GetAggregateStruct(int len);
347
/// Execute a user defined scalar function (internal use only)
348
static void ExecScalarFunction(void* ctx, int argc, void** argv);
350
/// Execute an aggregate step of a user defined aggregate function (internal use only)
351
static void ExecAggregateStep(void* ctx, int argc, void** argv);
353
/// Execute the final step of a user defined aggregate function (internal use only)
354
static void ExecAggregateFinalize(void* ctx);
356
/// Execute the user defined authorizer function (internal use only)
357
static int ExecAuthorizer(void*, int type,
358
const char* arg1, const char* arg2,
359
const char* arg3, const char* arg4);
361
/// Execute the user defined commit hook (internal use only)
362
static int ExecCommitHook(void* hook);
364
/// Execute the user defined rollback hook (internal use only)
365
static void ExecRollbackHook(void* hook);
367
/// Execute the user defined update hook (internal use only)
368
static void ExecUpdateHook(void* hook, int type,
369
const char* database, const char* table,
370
wxsqlite_int64 rowid);
372
/// Execute the user defined Write Ahead Log hook (internal use only)
373
static int ExecWriteAheadLogHook(void* hook, void* dbHandle,
374
const char* database, int numPages);
378
wxSQLite3FunctionContext(void* ctx, bool isAggregate, int argc = 0, void** argv = NULL);
381
wxSQLite3FunctionContext(wxSQLite3FunctionContext& ctx);
383
void* m_ctx; ///< SQLite3 context
384
bool m_isAggregate; ///< Flag whether this is the context of an aggregate function
385
int m_count; ///< Aggregate count
386
int m_argc; ///< Number of arguments
387
void** m_argv; ///< Array of SQLite3 arguments
391
/// Interface for user defined scalar functions
394
class EXTAPI wxSQLite3ScalarFunction
398
wxSQLite3ScalarFunction() {}
400
/// Virtual destructor
401
virtual ~wxSQLite3ScalarFunction() {}
402
/// Execute the scalar function
404
* This method is invoked for each appearance of the scalar function in the SQL query.
405
* \param ctx function context which can be used to access arguments and result value
407
virtual void Execute(wxSQLite3FunctionContext& ctx) = 0;
411
/// Interface for user defined aggregate functions
414
class EXTAPI wxSQLite3AggregateFunction
418
wxSQLite3AggregateFunction() { m_count = 0; }
420
/// Virtual destructor
421
virtual ~wxSQLite3AggregateFunction() {}
422
/// Execute the aggregate of the function
424
* This method is invoked for each row of the result set of the query using the aggregate function.
425
* \param ctx function context which can be used to access arguments and result value
427
virtual void Aggregate(wxSQLite3FunctionContext& ctx) = 0;
429
/// Prepare the result of the aggregate function
431
* This method is invoked after all rows of the result set of the query
432
* using the aggregate function have been processed. Usually the final result
433
* is calculated and returned in this method.
434
* \param ctx function context which can be used to access arguments and result value
436
virtual void Finalize(wxSQLite3FunctionContext& ctx) = 0;
439
int m_count; ///< Aggregate count
440
friend class wxSQLite3FunctionContext;
444
/// Interface for a user defined authorizer function
447
class EXTAPI wxSQLite3Authorizer
450
/// Codes identifying the command for which authorization is requested
451
enum wxAuthorizationCode
453
SQLITE_COPY = 0, // Table Name File Name
454
SQLITE_CREATE_INDEX = 1, // Index Name Table Name
455
SQLITE_CREATE_TABLE = 2, // Table Name NULL
456
SQLITE_CREATE_TEMP_INDEX = 3, // Index Name Table Name
457
SQLITE_CREATE_TEMP_TABLE = 4, // Table Name NULL
458
SQLITE_CREATE_TEMP_TRIGGER = 5, // Trigger Name Table Name
459
SQLITE_CREATE_TEMP_VIEW = 6, // View Name NULL
460
SQLITE_CREATE_TRIGGER = 7, // Trigger Name Table Name
461
SQLITE_CREATE_VIEW = 8, // View Name NULL
462
SQLITE_DELETE = 9, // Table Name NULL
463
SQLITE_DROP_INDEX = 10, // Index Name Table Name
464
SQLITE_DROP_TABLE = 11, // Table Name NULL
465
SQLITE_DROP_TEMP_INDEX = 12, // Index Name Table Name
466
SQLITE_DROP_TEMP_TABLE = 13, // Table Name NULL
467
SQLITE_DROP_TEMP_TRIGGER = 14, // Trigger Name Table Name
468
SQLITE_DROP_TEMP_VIEW = 15, // View Name NULL
469
SQLITE_DROP_TRIGGER = 16, // Trigger Name Table Name
470
SQLITE_DROP_VIEW = 17, // View Name NULL
471
SQLITE_INSERT = 18, // Table Name NULL
472
SQLITE_PRAGMA = 19, // Pragma Name 1st arg or NULL
473
SQLITE_READ = 20, // Table Name Column Name
474
SQLITE_SELECT = 21, // NULL NULL
475
SQLITE_TRANSACTION = 22, // Operation NULL
476
SQLITE_UPDATE = 23, // Table Name Column Name
477
SQLITE_ATTACH = 24, // Filename NULL
478
SQLITE_DETACH = 25, // Database Name NULL
479
SQLITE_ALTER_TABLE = 26, // Database Name Table Name
480
SQLITE_REINDEX = 27, // Index Name NULL
481
SQLITE_ANALYZE = 28, // Table Name NULL
482
SQLITE_CREATE_VTABLE = 29, // Table Name Module Name
483
SQLITE_DROP_VTABLE = 30, // Table Name Module Name
484
SQLITE_FUNCTION = 31, // NULL Function Name
485
SQLITE_SAVEPOINT = 32, // Operation Savepoint Name
486
SQLITE_MAX_CODE = SQLITE_SAVEPOINT
489
/// Return codes of the authorizer
490
enum wxAuthorizationResult
492
SQLITE_OK = 0, // Allow access
493
SQLITE_DENY = 1, // Abort the SQL statement with an error
494
SQLITE_IGNORE = 2 // Don't allow access, but don't generate an error
496
/// Virtual destructor
497
virtual ~wxSQLite3Authorizer() {}
498
/// Execute the authorizer function
500
* Please refer to the SQLite documentation for further information about the
501
* meaning of the parameters.
503
* \param type wxAuthorizationCode. The value signifies what kind of operation is to be authorized.
504
* \param arg1 first argument (value depends on "type")
505
* \param arg2 second argument (value depends on "type")
506
* \param arg3 third argument (name of database if applicable)
507
* \param arg4 fourth argument (name of trigger or view if applicable)
508
* \return a wxAuthorizationResult, i.e. SQLITE_OK, SQLITE_DENY or SQLITE_IGNORE
510
virtual wxAuthorizationResult Authorize(wxAuthorizationCode type,
511
const wxString& arg1, const wxString& arg2,
512
const wxString& arg3, const wxString& arg4) = 0;
513
/// Convert authorization code to string
515
* \param type wxAuthorizationCode. The value signifies what kind of operation is to be authorized.
517
static wxString AuthorizationCodeToString(wxSQLite3Authorizer::wxAuthorizationCode type);
520
class WXDLLIMPEXP_FWD_SQLITE3 wxSQLite3Database;
522
/// Interface for a user defined hook function
525
class EXTAPI wxSQLite3Hook
528
/// Codes identifying the command for which the hook is called
535
/// Default constructor
536
wxSQLite3Hook() : m_db(NULL) {}
538
/// Virtual destructor
539
virtual ~wxSQLite3Hook() {}
541
/// Execute the commit hook callback function
543
* Please refer to the SQLite documentation for further information.
544
* \return true to request rollback of the transaction, false to continue with commit
546
virtual bool CommitCallback() { return false; }
548
/// Execute the rollback hook callback function
550
* Please refer to the SQLite documentation for further information.
552
virtual void RollbackCallback() {}
554
/// Execute the hook callback function
556
* Please refer to the SQLite documentation for further information about the
557
* meaning of the parameters.
559
* \param type wxHookType. The value signifies what kind of operation is to be authorized.
560
* \param database Name of the database
561
* \param table Name of the table
562
* \param rowid The rowid of the affected row
564
virtual void UpdateCallback(wxUpdateType WXUNUSED(type),
565
const wxString& WXUNUSED(database), const wxString& WXUNUSED(table),
566
wxLongLong WXUNUSED(rowid)) {}
568
/// Execute the write-ahead log hook callback function
570
* Please refer to the SQLite documentation for further information about the
571
* meaning of the parameters.
573
* \param database Name of the database
574
* \param numPages the number of pages
576
virtual int WriteAheadLogCallback(const wxString& WXUNUSED(database),
577
int WXUNUSED(numPages)) { return 0; }
579
/// Set the associated database
581
* For the write-ahead log hook the associated database is set internally.
582
* \param db pointer to the associated database instance
584
void SetDatabase(wxSQLite3Database* db) { m_db = db; }
586
/// Get the associated database
588
* For the write-ahead log hook the associated database can be accessed.
590
* \return pointer to the associated database instance
591
* \note Access to the associated database is only provided for write-ahead log hooks.
593
wxSQLite3Database* GetDatabase() const { return m_db; }
596
wxSQLite3Database* m_db;
599
/// Interface for a user defined collation sequence
602
class EXTAPI wxSQLite3Collation
605
/// Virtual destructor
606
virtual ~wxSQLite3Collation() {}
608
/// Execute a comparison using a user-defined collation sequence
610
* Please refer to the SQLite documentation for further information.
611
* \param text1 first text string
612
* \param text2 second text string
613
* \return an integer < 0, = 0, or > 0 depending on whether text1 is less than, equal to, or greater than text2.
615
virtual int Compare(const wxString& text1, const wxString& text2) { return text1.Cmp(text2); }
618
/// Result set of a SQL query
619
class EXTAPI wxSQLite3ResultSet
623
wxSQLite3ResultSet();
626
wxSQLite3ResultSet(const wxSQLite3ResultSet& resultSet);
628
/// Constructor for internal use
629
wxSQLite3ResultSet(void* db, void* stmt,
630
bool eof, bool first = true, bool ownStmt = true);
632
/// Assignment constructor
633
wxSQLite3ResultSet& operator=(const wxSQLite3ResultSet& resultSet);
638
virtual ~wxSQLite3ResultSet();
640
/// Get the number of columns in the result set
642
* \return number of columns in result set
644
int GetColumnCount();
646
/// Find the index of a column by name
648
* \param columnName name of the column
649
* \return index of the column. Indices start with 0.
651
int FindColumnIndex(const wxString& columnName);
653
/// Get the name of a column
655
* \param columnIndex index of the column. Indices start with 0.
656
* \return column name as string
658
wxString GetColumnName(int columnIndex);
660
/// Get the declared type of a column
662
* \param columnIndex index of the column. Indices start with 0.
663
* \return type string as specified in the table definition
665
wxString GetDeclaredColumnType(int columnIndex);
667
/// Get the actual type of a column
669
* \param columnIndex index of the column. Indices start with 0.
670
* \return column type as one of the values WXSQLITE_INTEGER, WXSQLITE_FLOAT, WXSQLITE_TEXT, WXSQLITE_BLOB, or WXSQLITE_NULL
672
int GetColumnType(int columnIndex);
674
/// Get the database name of a column
676
* \param columnIndex index of the column. Indices start with 0.
677
* \return database name the column belongs to or empty string
679
* This method is only available if WXSQLITE3_HAVE_METADATA is defined and SQLite has been compiled with SQLITE_ENABLE_COLUMN_METADATA defined.
681
wxString GetDatabaseName(int columnIndex);
683
/// Get the table name of a column
685
* \param columnIndex index of the column. Indices start with 0.
686
* \return table name the column belongs to or empty string
688
* This method is only available if WXSQLITE3_HAVE_METADATA is defined and SQLite has been compiled with SQLITE_ENABLE_COLUMN_METADATA defined.
690
wxString GetTableName(int columnIndex);
692
/// Get the origin name of a column
694
* \param columnIndex index of the column. Indices start with 0.
695
* \return origin name the column belongs to or empty string
697
* This method is only available if WXSQLITE3_HAVE_METADATA is defined and SQLite has been compiled with SQLITE_ENABLE_COLUMN_METADATA defined.
699
wxString GetOriginName(int columnIndex);
701
/// Get a column as a string using the column index
703
* \param columnIndex index of the column. Indices start with 0.
704
* \return value of the column as string
706
wxString GetAsString(int columnIndex);
708
/// Get a column as a string using the column name
710
* \param columnName name of the column
711
* \return value of the column
713
wxString GetAsString(const wxString& columnName);
715
/// Get a column as an integer using the column index
717
* \param columnIndex index of the column. Indices start with 0.
718
* \param nullValue value to be returned in case the column is NULL
719
* \return value of the column
721
int GetInt(int columnIndex, int nullValue = 0);
723
/// Get a column as an integer using the column name
725
* \param columnName name of the column
726
* \param nullValue value to be returned in case the column is NULL
727
* \return value of the column
729
int GetInt(const wxString& columnName, int nullValue = 0);
731
/// Get a column as a 64-bit integer using the column index
733
* \param columnIndex index of the column. Indices start with 0.
734
* \param nullValue value to be returned in case the column is NULL
735
* \return value of the column
737
wxLongLong GetInt64(int columnIndex, wxLongLong nullValue = 0);
739
/// Get a column as a 64-bit integer using the column name
741
* \param columnName name of the column
742
* \param nullValue value to be returned in case the column is NULL
743
* \return value of the column
745
wxLongLong GetInt64(const wxString& columnName, wxLongLong nullValue = 0);
747
/// Get a column as a double using the column index
749
* \param columnIndex index of the column. Indices start with 0.
750
* \param nullValue value to be returned in case the column is NULL
751
* \return value of the column
753
double GetDouble(int columnIndex, double nullValue = 0.0);
755
/// Get a column as a double using the column name
757
* \param columnName name of the column
758
* \param nullValue value to be returned in case the column is NULL
759
* \return value of the column
761
double GetDouble(const wxString& columnName, double nullValue = 0.0);
763
/// Get a column as a string using the column index
765
* \param columnIndex index of the column. Indices start with 0.
766
* \param nullValue value to be returned in case the column is NULL
767
* \return value of the column
769
wxString GetString(int columnIndex, const wxString& nullValue = wxEmptyString);
771
/// Get a column as a string using the column name
773
* \param columnName name of the column
774
* \param nullValue value to be returned in case the column is NULL
775
* \return value of the column
777
wxString GetString(const wxString& columnName, const wxString& nullValue = wxEmptyString);
779
/// Get a column as a BLOB using the column index
781
* \param columnIndex index of the column. Indices start with 0.
782
* \param[out] len length of the blob in bytes
783
* \return value of the column
785
const unsigned char* GetBlob(int columnIndex, int& len);
787
/// Get a column as a BLOB using the column name
789
* \param columnName name of the column
790
* \param[out] len length of the blob in bytes
791
* \return value of the column
793
const unsigned char* GetBlob(const wxString& columnName, int& len);
795
/// Get a column as a BLOB using the column index and append to memory buffer
797
* \param columnIndex index of the column. Indices start with 0.
798
* \param[out] buffer the memory buffer to which the BLOB value is appended
799
* \return reference to the memory buffer
801
wxMemoryBuffer& GetBlob(int columnIndex, wxMemoryBuffer& buffer);
803
/// Get a column as a BLOB using the column index and append to memory buffer
805
* \param columnName name of the column
806
* \param[out] buffer the memory buffer to which the BLOB value is appended
807
* \return reference to the memory buffer
809
wxMemoryBuffer& GetBlob(const wxString& columnName, wxMemoryBuffer& buffer);
811
/// Get a column as a date value using the column index
813
* \param columnIndex index of the column. Indices start with 0.
814
* \return value of the column
816
wxDateTime GetDate(int columnIndex);
818
/// Get a column as a date value using the column name
820
* \param columnName name of the column
821
* \return value of the column
823
wxDateTime GetDate(const wxString& columnName);
825
/// Get a column as a time value using the column index
827
* \param columnIndex index of the column. Indices start with 0.
828
* \return value of the column
830
wxDateTime GetTime(int columnIndex);
832
/// Get a column as a time value using the column name
834
* \param columnName name of the column
835
* \return value of the column
837
wxDateTime GetTime(const wxString& columnName);
839
/// Get a column as a date and time value using the column index
841
* \param columnIndex index of the column. Indices start with 0.
842
* \return value of the column
844
wxDateTime GetDateTime(int columnIndex);
846
/// Get a column as a date and time value using the column name
848
* \param columnName name of the column
849
* \return value of the column
851
wxDateTime GetDateTime(const wxString& columnName);
853
/// Get a column as a timestamp value using the column index
855
* \param columnIndex index of the column. Indices start with 0.
856
* \return value of the column
858
wxDateTime GetTimestamp(int columnIndex);
860
/// Get a column as a timestamp value using the column name
862
* \param columnName name of the column
863
* \return value of the column
865
wxDateTime GetTimestamp(const wxString& columnName);
867
/// Get a column as a date and time value using the column index
869
* The date/time value is expected to be stored in the database as a numeric value (i.e. int64).
871
* \param columnIndex index of the column. Indices start with 0.
872
* \return value of the column
874
wxDateTime GetNumericDateTime(int columnIndex);
876
/// Get a column as a date and time value using the column name
878
* The date/time value is expected to be stored in the database as a numeric value (i.e. int64).
880
* \param columnName name of the column
881
* \return value of the column
883
wxDateTime GetNumericDateTime(const wxString& columnName);
885
/// Get a column as a date and time value using the column index
887
* The date/time value is expected to be stored in the database as a Julian Day Number (i.e. double).
889
* \param columnIndex index of the column. Indices start with 0.
890
* \return value of the column
892
wxDateTime GetJulianDayNumber(int columnIndex);
894
/// Get a column as a date and time value using the column name
896
* The date/time value is expected to be stored in the database as a Julian Day Number (i.e. double).
898
* \param columnName name of the column
899
* \return value of the column
901
wxDateTime GetJulianDayNumber(const wxString& columnName);
903
/// Get a column as a boolean value using the column index
905
* \param columnIndex index of the column. Indices start with 0.
906
* \return value of the column
908
bool GetBool(int columnIndex);
910
/// Get a column as a boolean value using the column name
912
* \param columnName name of the column
913
* \return value of the column
915
bool GetBool(const wxString& columnName);
917
/// Check whether a column has a NULL value using the column index
919
* \param columnIndex index of the column. Indices start with 0.
920
* \return TRUE if the value is NULL, FALSE otherwise
922
bool IsNull(int columnIndex);
924
/// Check whether a column has a NULL value using the column name
926
* \param columnName name of the column
927
* \return TRUE if the value is NULL, FALSE otherwise
929
bool IsNull(const wxString& columnName);
931
/// Check whether all rows of the result set have been processed
933
* \return TRUE if all rows of the result have been processed, FALSE otherwise
937
/// Retrieve next row of the result set
939
* Advances the cursor to the next row.
940
* On creation of the result set the cursor is positioned BEFORE the first row, i.e.
941
* the first call to this method makes the first row available for processing.
942
* \return TRUE while there are still rows to process, FALSE otherwise
946
/// Finalize the result set
951
/// Get the original SQL string for preparing the query statement
953
* \return the original SQL string used to prepare the query statement
957
/// Validate associated SQLite database and statement
959
* \return TRUE if both, a SQLite database and a SQLite statement, are associated, FALSE otherwise
964
/// Check the validity of the associated statement
967
void* m_db; ///< associated database
968
void* m_stmt; ///< associated statement
969
bool m_eof; ///< Flag for end of result set
970
bool m_first; ///< Flag for first row of the result set
971
int m_cols; ///< Numver of columns in row set
972
bool m_ownStmt; ///< Flag for ownership of the associated statement
976
/// Holds the complete result set of a SQL query
977
class EXTAPI wxSQLite3Table
983
wxSQLite3Table(const wxSQLite3Table& table);
985
wxSQLite3Table(char** results, int rows, int cols);
987
virtual ~wxSQLite3Table();
989
wxSQLite3Table& operator=(const wxSQLite3Table& table);
991
/// Get the number of columns in the result set
993
* \return the number of columns
995
int GetColumnCount();
997
/// Get the number of rows in the result set
999
* \return the number of rows
1003
/// Find the index of a column by name
1005
* \param columnName name of the column
1006
* \return the index of the column
1008
int FindColumnIndex(const wxString& columnName);
1010
/// Get the name of a column
1012
* \param columnIndex index of the column. Indices start with 0.
1013
* \return name of the column
1015
wxString GetColumnName(int columnIndex);
1017
/// Get a column as a string using the column index
1019
* \param columnIndex index of the column. Indices start with 0.
1020
* \return value of the column as a string
1022
* \note This method returns values of type <code>double</code>
1023
* always using the point character as the decimal separator.
1024
* This is SQLite default behaviour. Use method wxSQLite3Table::GetDouble
1025
* to apply correct conversion from <code>string</code> to <code>double</code>.
1027
wxString GetAsString(int columnIndex);
1029
/// Get a column as a string using the column name
1031
* \param columnName name of the column
1032
* \return value of the column as a string
1034
* \note This method returns values of type <code>double</code>
1035
* always using the point character as the decimal separator.
1036
* This is SQLite default behaviour. Use method wxSQLite3Table::GetDouble
1037
* to apply correct conversion from <code>string</code> to <code>double</code>.
1039
wxString GetAsString(const wxString& columnName);
1041
/// Get a column as an integer using the column index
1043
* \param columnIndex index of the column. Indices start with 0.
1044
* \param nullValue value to be returned in case the column is NULL
1045
* \return value of the column
1047
int GetInt(int columnIndex, int nullValue = 0);
1049
/// Get a column as an integer using the column name
1051
* \param columnName name of the column
1052
* \param nullValue value to be returned in case the column is NULL
1053
* \return value of the column
1055
int GetInt(const wxString& columnName, int nullValue = 0);
1057
/// Get a column as a 64-bit integer using the column index
1059
* \param columnIndex index of the column. Indices start with 0.
1060
* \param nullValue value to be returned in case the column is NULL
1061
* \return value of the column
1063
wxLongLong GetInt64(int columnIndex, wxLongLong nullValue = 0);
1065
/// Get a column as an integer using the column name
1067
* \param columnName name of the column
1068
* \param nullValue value to be returned in case the column is NULL
1069
* \return value of the column
1071
wxLongLong GetInt64(const wxString& columnName, wxLongLong nullValue = 0);
1073
/// Get a column as a double using the column index
1075
* \param columnIndex index of the column. Indices start with 0.
1076
* \param nullValue value to be returned in case the column is NULL
1077
* \return value of the column
1079
double GetDouble(int columnIndex, double nullValue = 0.0);
1081
/// Get a column as a double using the column name
1083
* \param columnName name of the column
1084
* \param nullValue value to be returned in case the column is NULL
1085
* \return value of the column
1087
double GetDouble(const wxString& columnName, double nullValue = 0.0);
1089
/// Get a column as a string using the column index
1091
* \param columnIndex index of the column. Indices start with 0.
1092
* \param nullValue value to be returned in case the column is NULL
1093
* \return value of the column
1095
wxString GetString(int columnIndex, const wxString& nullValue = wxEmptyString);
1097
/// Get a column as a string using the column name
1099
* \param columnName name of the column
1100
* \param nullValue value to be returned in case the column is NULL
1101
* \return value of the column
1103
wxString GetString(const wxString& columnName, const wxString& nullValue = wxEmptyString);
1105
/// Get a column as a date value using the column index
1107
* \param columnIndex index of the column. Indices start with 0.
1108
* \return value of the column
1110
wxDateTime GetDate(int columnIndex);
1112
/// Get a column as a date value using the column name
1114
* \param columnName name of the column
1115
* \return value of the column
1117
wxDateTime GetDate(const wxString& columnName);
1119
/// Get a column as a time value using the column index
1121
* \param columnIndex index of the column. Indices start with 0.
1122
* \return value of the column
1124
wxDateTime GetTime(int columnIndex);
1126
/// Get a column as a time value using the column name
1128
* \param columnName name of the column
1129
* \return value of the column
1131
wxDateTime GetTime(const wxString& columnName);
1133
/// Get a column as a date/time value using the column index
1135
* \param columnIndex index of the column. Indices start with 0.
1136
* \return value of the column
1138
wxDateTime GetDateTime(int columnIndex);
1140
/// Get a column as a date/time value using the column name
1142
* \param columnName name of the column
1143
* \return value of the column
1145
wxDateTime GetDateTime(const wxString& columnName);
1147
/// Get a column as a boolean using the column index
1149
* \param columnIndex index of the column. Indices start with 0.
1150
* \return value of the column
1152
bool GetBool(int columnIndex);
1154
/// Get a column as a boolean using the column name
1156
* \param columnName name of the column
1157
* \return value of the column
1159
bool GetBool(const wxString& columnName);
1161
/// Check whether the column selected by index is a NULL value
1163
* \param columnIndex index of the column. Indices start with 0.
1164
* \return TRUE if the value is NULL, FALSE otherwise
1166
bool IsNull(int columnIndex);
1168
/// Check whether the column selected by name is a NULL value
1170
* \param columnName name of the column
1171
* \return TRUE if the value is NULL, FALSE otherwise
1173
bool IsNull(const wxString& columnName);
1175
/// Set the current row
1177
* \param row index of the requested row. Indices start with 0.
1179
void SetRow(int row);
1181
/// Finalize the result set
1186
/// Validate associated SQLite resultset
1188
* \return TRUE if SQLite resultset is associated, FALSE otherwise
1193
/// Check for valid results
1194
void CheckResults();
1196
int m_cols; ///< Number of columns
1197
int m_rows; ///< Number of rows
1198
int m_currentRow; ///< Index of the current row
1199
char** m_results; ///< SQLite3 result buffer
1203
/// Represents a prepared SQL statement
1204
class EXTAPI wxSQLite3Statement
1210
wxSQLite3Statement();
1212
/// Copy constructor
1215
wxSQLite3Statement(const wxSQLite3Statement& statement);
1217
/// Assignement constructor
1220
wxSQLite3Statement& operator=(const wxSQLite3Statement& statement);
1222
/// Constructor (internal use only)
1225
wxSQLite3Statement(void* db, void* stmt);
1230
virtual ~wxSQLite3Statement();
1232
/// Execute the database update represented by this statement
1234
* \return the number of database rows that were changed (or inserted or deleted)
1236
int ExecuteUpdate();
1238
/// Execute the query represented by this statement
1240
* \param transferStatementOwnership if TRUE the ownership of the underlying SQLite
1241
* statement object is transferred to the created result set (default: FALSE)
1242
* \return result set instance
1243
* \note the transfer of ownership of the underlying SQLite statement object can be
1244
* performed only once. If the transfer of ownership has been requested this
1245
* wxSQL3Statement instance isn't usable anymore as soon as the result set is destroyed.
1246
* If the transfer of ownership isn't requested the created result set can be used to
1247
* retrieve the selected data rows only as long as this wxSQLite3Statement instance exists.
1249
wxSQLite3ResultSet ExecuteQuery(bool transferStatementOwnership = false);
1251
/// Execute a scalar SQL query statement given as a wxString
1253
* Allows to easily retrieve the result of queries returning a single integer result
1254
* like SELECT COUNT(*) FROM table WHERE condition.
1255
* \return first column of first row as an int
1257
int ExecuteScalar();
1259
/// Get the number of statement parameters
1261
* \return the number of parameters in the prepared statement
1263
int GetParamCount();
1265
/// Get the index of a parameter with a given name
1268
* \return the index of the parameter with the given name. The name must match exactly.
1269
* If there is no parameter with the given name, return 0.
1271
int GetParamIndex(const wxString& paramName);
1273
/// Get the name of a paramater at the given position
1275
* \param paramIndex index of the parameter. The first parameter has an index of 1.
1276
* \return the name of the paramIndex-th parameter in the precompiled statement.
1277
* Parameters of the form ":AAA" or "$VVV" have a name which is the string ":AAA" or "$VVV".
1278
* Parameters of the form "?" have no name.
1280
wxString GetParamName(int paramIndex);
1282
/// Bind parameter to a string value
1284
* \param paramIndex index of the parameter. The first parameter has an index of 1.
1285
* \param stringValue value of the parameter
1287
void Bind(int paramIndex, const wxString& stringValue);
1289
/// Bind parameter to a integer value
1291
* \param paramIndex index of the parameter. The first parameter has an index of 1.
1292
* \param intValue value of the parameter
1294
void Bind(int paramIndex, int intValue);
1296
/// Bind parameter to a 64-bit integer value
1298
* \param paramIndex index of the parameter. The first parameter has an index of 1.
1299
* \param int64Value value of the parameter
1301
void Bind(int paramIndex, wxLongLong int64Value);
1303
/// Bind parameter to a double value
1305
* \param paramIndex index of the parameter. The first parameter has an index of 1.
1306
* \param doubleValue value of the parameter
1308
void Bind(int paramIndex, double doubleValue);
1310
/// Bind parameter to a utf-8 character string value
1312
* \param paramIndex index of the parameter. The first parameter has an index of 1.
1313
* \param charValue value of the parameter
1315
void Bind(int paramIndex, const char* charValue);
1317
/// Bind parameter to a BLOB value
1319
* \param paramIndex index of the parameter. The first parameter has an index of 1.
1320
* \param blobValue value of the parameter
1321
* \param blobLen length of the blob in bytes
1323
void Bind(int paramIndex, const unsigned char* blobValue, int blobLen);
1325
/// Bind parameter to a BLOB value
1327
* \param paramIndex index of the parameter. The first parameter has an index of 1.
1328
* \param blobValue value of the parameter
1330
void Bind(int paramIndex, const wxMemoryBuffer& blobValue);
1332
/// Bind parameter to a date value
1334
* \param paramIndex index of the parameter. The first parameter has an index of 1.
1335
* \param date value of the parameter
1337
void BindDate(int paramIndex, const wxDateTime& date);
1339
/// Bind parameter to a time value
1341
* \param paramIndex index of the parameter. The first parameter has an index of 1.
1342
* \param time value of the parameter
1344
void BindTime(int paramIndex, const wxDateTime& time);
1346
/// Bind parameter to a date and time value
1348
* \param paramIndex index of the parameter. The first parameter has an index of 1.
1349
* \param datetime value of the parameter
1351
void BindDateTime(int paramIndex, const wxDateTime& datetime);
1353
/// Bind parameter to a timestamp value
1355
* \param paramIndex index of the parameter. The first parameter has an index of 1.
1356
* \param timestamp value of the parameter
1358
void BindTimestamp(int paramIndex, const wxDateTime& timestamp);
1360
/// Bind parameter to a date and time value
1362
* The date/time value is transferred to the database as a numeric value (i.e. int64).
1364
* \param paramIndex index of the parameter. The first parameter has an index of 1.
1365
* \param datetime value of the parameter
1367
void BindNumericDateTime(int paramIndex, const wxDateTime& datetime);
1369
/// Bind parameter to a date and time value
1371
* The date/time value is transferred to the database as a Julian Day Number value (i.e. double).
1373
* \param paramIndex index of the parameter. The first parameter has an index of 1.
1374
* \param datetime value of the parameter
1376
void BindJulianDayNumber(int paramIndex, const wxDateTime& datetime);
1378
/// Bind parameter to a boolean value
1380
* \param paramIndex index of the parameter. The first parameter has an index of 1.
1381
* \param value value of the parameter
1383
void BindBool(int paramIndex, bool value);
1385
/// Bind parameter to a NULL value
1387
* \param paramIndex index of the parameter. The first parameter has an index of 1.
1389
void BindNull(int paramIndex);
1391
/// Bind parameter to a Zero BLOB value
1393
* Space for a BLOB is reserved and filled with binary zeros for later reference
1394
* through a BLOB handle.
1396
* \param paramIndex index of the parameter. The first parameter has an index of 1.
1397
* \param blobSize size of the BLOB
1399
void BindZeroBlob(int paramIndex, int blobSize);
1401
/// Clear all parameter bindings
1403
* Sets all the parameters in the prepared SQL statement back to NULL.
1405
void ClearBindings();
1407
/// Get the original SQL string for the prepared statement
1409
* \return the original SQL string used to prepare the statement
1413
/// Reset the prepared statement
1415
* Resets the statement back to it's initial state, ready to be re-executed.
1416
* Any SQL statement variables that had values bound to them retain their values.
1420
/// Determine whether the statement is read-only
1422
* \return TRUE if the statement is read-only, FALSE otherwise
1423
* \since SQLite3 version 3.7.4
1424
* \note For SQLite3 version before version 3.7.4 this method returns always FALSE.
1428
/// Finalize the prepared statement
1433
/// Validate associated SQLite database and statement
1435
* \return TRUE if both, a SQLite database and a SQLite statement, are associated, FALSE otherwise
1440
/// Check for valid database connection
1441
void CheckDatabase();
1443
/// Check for valid statement
1446
void* m_db; ///< associated SQLite3 database
1447
void* m_stmt; ///< associated SQLite3 statement
1448
bool m_hasOwnership; ///< flag whether the associated SQLite3 statement is owned
1452
/// Represents a SQLite BLOB handle
1453
class EXTAPI wxSQLite3Blob
1461
/// Copy constructor
1464
wxSQLite3Blob(const wxSQLite3Blob& blob);
1466
/// Assignement constructor
1469
wxSQLite3Blob& operator=(const wxSQLite3Blob& blob);
1471
/// Constructor (internal use only)
1474
wxSQLite3Blob(void* m_db, void* blobHandle, bool writable);
1479
virtual ~wxSQLite3Blob();
1481
/// Read partial BLOB value
1483
* \param blobValue memory buffer receiving the partial content of the BLOB
1484
* \param length length of BLOB content to be read
1485
* \param offset offset within BLOB where the read starts
1486
* \return the address of the memory buffer
1488
wxMemoryBuffer& Read(wxMemoryBuffer& blobValue, int length, int offset);
1490
/// Write partial BLOB value
1492
* \param blobValue memory buffer receiving the partial content of the BLOB
1493
* \param offset offset within BLOB where the read starts
1495
void Write(const wxMemoryBuffer& blobValue, int offset);
1497
/// Check whether the BLOB handle is correctly initialized
1499
* \return TRUE if the BLOB handle is correctly initialized, FALSE otherweis
1503
/// Check whether the BLOB handle is read only
1505
* \return TRUE if the BLOB handle is readonly, FALSE otherweis
1509
/// Get the size of the associated BLOB
1511
* \return the BLOB size
1515
/// Rebind the associated BLOB to a new row
1517
* Please refer to the SQLite documentation for further information
1518
* (see function sqlite3_blob_reopen)
1519
* \param rowid id of the row to which the BLOB should be rebound
1520
* \since SQLite3 version 3.7.4
1522
void Rebind(wxLongLong rowid);
1524
/// Finalize the BLOB
1530
/// Check for valid BLOB
1533
void* m_db; ///< associated SQLite3 database handle
1534
void* m_blob; ///< associated SQLite3 BLOB handle
1535
bool m_ok; ///< flag whether the BLOB handle is correctly initialized
1536
bool m_writable; ///< flag whether the BLOB is writable or read only
1539
/// Represents a named collection
1541
* A named collection is designed to facilitate using an array of
1542
* integers or strings as the right-hand side of an IN operator.
1543
* So instead of doing a prepared statement like this:
1545
* SELECT * FROM table WHERE x IN (?,?,?,...,?);
1547
* And then binding indivdual integers to each of ? slots, an application
1548
* can create a named collection object (named "ex1" in the following
1549
* example), prepare a statement like this:
1551
* SELECT * FROM table WHERE x IN ex1;
1553
* Then bind an array of integer or string values to the ex1 object
1554
* to run the statement.
1558
* One or more named collection objects can be created as follows:
1560
* wxSQLite3IntegerCollection p1, p2, p3;
1561
* p1 = db.CreateIntegerCollection("ex1");
1562
* p2 = db.CreateIntegerCollection("ex2");
1563
* p3 = db.CreateIntegerCollection("ex3");
1565
* Each call to CreateIntegerCollection generates a new virtual table
1566
* module and a singleton of that virtual table module in the TEMP
1567
* database. Both the module and the virtual table instance use the
1568
* name given by the second parameter. The virtual tables can then be
1569
* used in prepared statements:
1571
* SELECT * FROM t1, t2, t3
1576
* Each integer array is initially empty. New arrays can be bound to
1577
* an integer array as follows:
1579
* int a1[] = { 1, 2, 3, 4 };
1580
* int a2[] = { 5, 6, 7, 8, 9, 10, 11 };
1587
* A single named collection object can be rebound multiple times. But do not
1588
* attempt to change the bindings of a named collection while it is in the middle
1591
* The array that holds the integer or string values is automatically allocated
1592
* by the Bind method.
1594
* The named collection object is automatically destroyed when its corresponding
1595
* virtual table is dropped. Since the virtual tables are created in the
1596
* TEMP database, they are automatically dropped when the database connection
1597
* closes so the application does not normally need to take any special
1598
* action to free the named collection objects.
1600
class EXTAPI wxSQLite3NamedCollection
1604
wxSQLite3NamedCollection();
1606
/// Copy constructor
1607
wxSQLite3NamedCollection(const wxSQLite3NamedCollection& collection);
1609
/// Assignement constructor
1610
wxSQLite3NamedCollection& operator=(const wxSQLite3NamedCollection& collection);
1612
/// Constructor (internal use only)
1613
wxSQLite3NamedCollection(const wxString& collectionName, void* collectionData);
1616
virtual ~wxSQLite3NamedCollection();
1618
/// Get the name of the collection
1620
* \return the name of the collection
1622
const wxString& GetName() { return m_name; }
1625
wxString m_name; ///< Name of the collection
1626
void* m_data; ///< Reference to the actual array of values representing the collection
1628
friend class wxSQLite3Database;
1631
/// Represents a named integer value collection
1632
class EXTAPI wxSQLite3IntegerCollection : public wxSQLite3NamedCollection
1636
wxSQLite3IntegerCollection();
1638
/// Copy constructor
1639
wxSQLite3IntegerCollection(const wxSQLite3IntegerCollection& collection);
1641
/// Assignement constructor
1642
wxSQLite3IntegerCollection& operator=(const wxSQLite3IntegerCollection& collection);
1644
/// Constructor (internal use only)
1645
wxSQLite3IntegerCollection(const wxString& collectionName, void* collectionData);
1648
virtual ~wxSQLite3IntegerCollection();
1650
/// Bind a new array of integer values
1652
* Bind a new array of integer values to this named collection object.
1653
* \param integerCollection array of integer values to be bound
1654
* \note Binding values to a named collection after closing the corresponding
1655
* database results in undefined behaviour, i.e. the application is likely to crash.
1657
void Bind(const wxArrayInt& integerCollection);
1659
/// Bind a new array of integer values
1661
* Bind a new array of integer values to this named collection object.
1662
* \param n number of elements in the array
1663
* \param integerCollection array of integer values to be bound
1664
* \note Binding values to a named collection after closing the corresponding
1665
* database results in undefined behaviour, i.e. the application is likely to crash.
1667
void Bind(int n, int* integerCollection);
1670
friend class wxSQLite3Database;
1673
/// Represents a named string value collection
1674
class EXTAPI wxSQLite3StringCollection : public wxSQLite3NamedCollection
1678
wxSQLite3StringCollection();
1680
/// Copy constructor
1681
wxSQLite3StringCollection(const wxSQLite3StringCollection& collection);
1683
/// Assignement constructor
1684
wxSQLite3StringCollection& operator=(const wxSQLite3StringCollection& collection);
1686
/// Constructor (internal use only)
1687
wxSQLite3StringCollection(const wxString& collectionName, void* collectionData);
1690
virtual ~wxSQLite3StringCollection();
1692
/// Bind a new array of integer values
1694
* Bind a new array of integer values to this named collection object.
1695
* \param stringCollection array of integer values to be bound
1696
* \note Binding values to a named collection after closing the corresponding
1697
* database results in undefined behaviour, i.e. the application is likely to crash.
1699
void Bind(const wxArrayString& stringCollection);
1702
friend class wxSQLite3Database;
1705
/// Represents a SQLite3 database object
1706
class EXTAPI wxSQLite3Database
1709
/// Default constructor
1711
* Initializes a SQLite database object.
1712
* The SQLite database object can only be used in the same thread in which it was created.
1714
wxSQLite3Database();
1718
* Destructs a SQLite database object.
1719
* The database will be closed implicitly if it is still open.
1721
virtual ~wxSQLite3Database();
1723
/// Open a SQLite3 database
1725
* Opens the sqlite database file "filename". The "filename" is UTF-8 encoded.
1726
* If the database could not be opened (or created) successfully, then an exception is thrown.
1727
* If the database file does not exist, then a new database will be created as needed.
1728
* \param[in] fileName Name of the database file.
1729
* \param[in] key Database encryption key.
1730
* \param[in] flags Control over the database connection (see http://www.sqlite.org/c3ref/open.html for further information).
1731
* Flag values are prefixed by WX to distinguish them from the original SQLite flag values.
1733
void Open(const wxString& fileName, const wxString& key = wxEmptyString,
1734
int flags = WXSQLITE_OPEN_READWRITE | WXSQLITE_OPEN_CREATE);
1736
/// Open a SQLite3 database using a binary key
1738
* Opens the sqlite database file "filename". The "filename" is UTF-8 encoded.
1739
* If the database could not be opened (or created) successfully, then an exception is thrown.
1740
* If the database file does not exist, then a new database will be created as needed.
1741
* \param[in] fileName Name of the database file.
1742
* \param[in] key Database encryption key.
1743
* \param[in] flags Control over the database connection (see http://www.sqlite.org/c3ref/open.html for further information).
1744
* Flag values are prefixed by WX to distinguish them from the original SQLite flag values.
1746
void Open(const wxString& fileName, const wxMemoryBuffer& key,
1747
int flags = WXSQLITE_OPEN_READWRITE | WXSQLITE_OPEN_CREATE);
1749
/// Check whether the database has been opened
1751
* \return TRUE if database has been opened, FALSE otherwise
1753
bool IsOpen() const;
1755
/// Close a SQLite3 database
1757
* Take care that all prepared statements have been finalized!
1758
* Starting with version 3.6.0 SQLite has support to finialize all unfinalized
1759
* prepared statements. The Close method has been changed to take advantage of
1760
* this feature. Nevertheless it is recommended to explicitly finalize all
1761
* wxSQLite3Statement instances before closing a database.
1763
* NOTE: Finalizing all wxSQLite3Blob instances before closing a database is still required!
1768
/// Backup a SQLite3 database
1770
* This method is used to overwrite the contents of a database with the contents
1771
* of this database. This is useful either for creating backups of the database or
1772
* for copying an in-memory database to persistent files.
1774
* NOTE: Exclusive access is required to the target database for the
1775
* duration of the operation. However the source database is only
1776
* read-locked while it is actually being read, it is not locked
1777
* continuously for the entire operation. Thus, the backup may be
1778
* performed on a live database without preventing other users from
1779
* writing to the database for an extended period of time.
1781
* NOTE: If the target database file already exists it must be a valid
1782
* SQLite database, in case of an encrypted database the key used for
1783
* backup must be the same as the key used for creation.
1784
* If this does not hold true, the file should be deleted prior to
1785
* performing the backup.
1787
* \param[in] targetFileName Name of the target database file.
1788
* \param[in] key Optional database encryption key for the target database.
1789
* \param[in] sourceDatabaseName Optional name of the source database (default: 'main').
1791
void Backup(const wxString& targetFileName, const wxString& key = wxEmptyString, const wxString& sourceDatabaseName = wxT("main"));
1793
/// Backup a SQLite3 database
1795
* This method is used to overwrite the contents of a database with the contents
1796
* of this database. This is useful either for creating backups of the database or
1797
* for copying an in-memory database to persistent files.
1799
* NOTE: Exclusive access is required to the target database for the
1800
* duration of the operation. However the source database is only
1801
* read-locked while it is actually being read, it is not locked
1802
* continuously for the entire operation. Thus, the backup may be
1803
* performed on a live database without preventing other users from
1804
* writing to the database for an extended period of time.
1806
* NOTE: If the target database file already exists it must be a valid
1807
* SQLite database, in case of an encrypted database the key used for
1808
* backup must be the same as the key used for creation.
1809
* If this does not hold true, the file should be deleted prior to
1810
* performing the backup.
1812
* \param[in] targetFileName Name of the target database file.
1813
* \param[in] key Binary database encryption key for the target database.
1814
* \param[in] sourceDatabaseName Optional name of the source database (default: 'main').
1816
void Backup(const wxString& targetFileName, const wxMemoryBuffer& key, const wxString& sourceDatabaseName = wxT("main"));
1818
/// Restore a SQLite3 database
1820
* This method is used to restore the contents of this database with the contents
1821
* of another database. This is useful either for restoring a backup of the database or
1822
* for copying a persistent file to an in-memory database.
1824
* NOTE: Exclusive access is required to the target database for the
1825
* duration of the operation. However the source database is only
1826
* read-locked while it is actually being read, it is not locked
1827
* continuously for the entire operation. Thus, the backup may be
1828
* performed on a live database without preventing other users from
1829
* writing to the database for an extended period of time.
1831
* \param[in] sourceFileName Name of the source database file.
1832
* \param[in] key Optional database encryption key for the source database.
1833
* \param[in] targetDatabaseName Optional name of the target database (default: 'main').
1835
void Restore(const wxString& sourceFileName, const wxString& key = wxEmptyString, const wxString& targetDatabaseName = wxT("main"));
1837
/// Restore a SQLite3 database
1839
* This method is used to restore the contents of this database with the contents
1840
* of another database. This is useful either for restoring a backup of the database or
1841
* for copying a persistent file to an in-memory database.
1843
* NOTE: Exclusive access is required to the target database for the
1844
* duration of the operation. However the source database is only
1845
* read-locked while it is actually being read, it is not locked
1846
* continuously for the entire operation. Thus, the backup may be
1847
* performed on a live database without preventing other users from
1848
* writing to the database for an extended period of time.
1850
* \param[in] sourceFileName Name of the source database file.
1851
* \param[in] key Optional binary database encryption key for the source database.
1852
* \param[in] targetDatabaseName Optional name of the target database (default: 'main').
1854
void Restore(const wxString& sourceFileName, const wxMemoryBuffer& key, const wxString& targetDatabaseName = wxT("main"));
1856
/// Begin transaction
1858
* In SQLite transactions can be deferred, immediate, or exclusive.
1859
* Deferred means that no locks are acquired on the database until the database is first accessed.
1860
* Thus with a deferred transaction, the BEGIN statement itself does nothing. Locks are not
1861
* acquired until the first read or write operation. The first read operation against a database
1862
* creates a SHARED lock and the first write operation creates a RESERVED lock. Because the
1863
* acquisition of locks is deferred until they are needed, it is possible that another thread or
1864
* process could create a separate transaction and write to the database after the BEGIN on the
1865
* current thread has executed. If the transaction is immediate, then RESERVED locks are acquired
1866
* on all databases as soon as the BEGIN command is executed, without waiting for the database to
1867
* be used. After a BEGIN IMMEDIATE, it is guaranteed that no other thread or process will be able
1868
* to write to the database or do a BEGIN IMMEDIATE or BEGIN EXCLUSIVE. Other processes can continue
1869
* to read from the database, however. An exclusive transaction causes EXCLUSIVE locks to be acquired
1870
* on all databases. After a BEGIN EXCLUSIVE, it is guaranteed that no other thread or process will
1871
* be able to read or write the database until the transaction is complete.
1873
* \param[in] transactionType type of transaction (default: DEFERRED).
1875
void Begin(wxSQLite3TransactionType transactionType = WXSQLITE_TRANSACTION_DEFAULT);
1877
/// Commit transaction
1882
/// Rollback transaction
1884
* Rolls back a transaction or optionally to a previously set savepoint
1886
* \param savepointName optional name of a previously set savepoint
1888
void Rollback(const wxString& savepointName = wxEmptyString);
1890
/// Get the auto commit state
1892
* Test to see whether or not the database connection is in autocommit mode.
1893
* \return TRUE if it is and FALSE if not.
1894
* Autocommit mode is on by default. Autocommit is disabled by a BEGIN statement
1895
* and reenabled by the next COMMIT or ROLLBACK.
1897
bool GetAutoCommit();
1901
* Sets a savepoint with a given name
1903
* \param savepointName the name of the savepoint
1905
void Savepoint(const wxString& savepointName);
1907
/// Release savepoint
1909
* Releases a savepoint with a given name
1911
* \param savepointName the name of the savepoint
1913
void ReleaseSavepoint(const wxString& savepointName);
1915
/// Check whether a table with the given name exists
1917
* Checks the main database or a specific attached database for existence of a table
1918
* with a given name.
1920
* \param tableName name of the table
1921
* \param databaseName optional name of an attached database
1922
* \return TRUE if the table exists, FALSE otherwise
1924
bool TableExists(const wxString& tableName, const wxString& databaseName = wxEmptyString);
1926
/// Check whether a table with the given name exists in the main database or any attached database
1928
* \param tableName name of the table
1929
* \param databaseNames list of the names of those databases in which the table exists
1930
* \return TRUE if the table exists at least in one database, FALSE otherwise
1932
bool TableExists(const wxString& tableName, wxArrayString& databaseNames);
1934
/// Get a list containing the names of all attached databases including the main database
1936
* \param databaseNames contains on return the list of the database names
1938
void GetDatabaseList(wxArrayString& databaseNames);
1940
/// Get a list containing the names of all attached databases including the main database
1942
* \param databaseNames contains on return the list of the database names
1943
* \param databaseFiles contains on return the list of the database file names
1945
void GetDatabaseList(wxArrayString& databaseNames, wxArrayString& databaseFiles);
1947
/// Enable or disable foreign key support
1949
* Starting with SQLite version 3.6.19 foreign key constraints can be enforced.
1950
* Foreign key constraints are disabled by default (for backwards compatibility),
1951
* so they must be enabled separately for each database connection.
1952
* \note Future releases of SQLite might change so that foreign key constraints
1953
* are enabled by default. No assumptions should be made about whether or not
1954
* foreign keys are enabled by default
1955
* \return TRUE if the requested action succeeded, FALSE otherwise
1957
bool EnableForeignKeySupport(bool enable);
1959
/// Check whether foreign key support is enabled for this database
1961
* \return TRUE if foreign key support is enabled, FALSE otherwise
1963
bool IsForeignKeySupportEnabled();
1965
/// Set SQLite journal mode
1967
* \param mode the journal mode to be set
1968
* \param database the attached database for which the journal mode should be set. If not given then
1969
* the journal mode of all attached databases is set.
1970
* \return the active journal mode
1971
* \note The journal mode for an in-memory database is either MEMORY or OFF and can not be changed
1972
* to a different value. An attempt to change the journal mode of an in-memory database to any setting
1973
* other than MEMORY or OFF is ignored. Note also that the journal mode cannot be changed while a
1974
* transaction is active.
1975
* The WAL journaling mode uses a write-ahead log instead of a rollback journal to implement transactions.
1976
* The WAL journaling mode is persistent; after being set it stays in effect across multiple database
1977
* connections and after closing and reopening the database. A database in WAL journaling mode can only be
1978
* accessed by SQLite version 3.7.0 or later.
1980
wxSQLite3JournalMode SetJournalMode(wxSQLite3JournalMode mode, const wxString& database = wxEmptyString);
1982
/// Get the active SQLite journal mode
1984
* \param database the attached database for which the journal mode should be queried (default: main)
1985
* \return active journal mode
1987
wxSQLite3JournalMode GetJournalMode(const wxString& database = wxEmptyString);
1989
/// Check the syntax of an SQL statement given as a wxString
1991
* \param sql query string
1992
* \return TRUE if the syntax is correct, FALSE otherwise
1994
bool CheckSyntax(const wxString& sql);
1996
/// Check the syntax of an SQL statement given as a statement buffer
1998
* \param sql query string
1999
* \return TRUE if the syntax is correct, FALSE otherwise
2001
bool CheckSyntax(const wxSQLite3StatementBuffer& sql);
2003
/// Check the syntax of an SQL statement given as a utf-8 character string
2005
* \param sql query string
2006
* \return TRUE if the syntax is correct, FALSE otherwise
2008
bool CheckSyntax(const char* sql);
2010
/// Execute a insert, update or delete SQL statement given as a wxString
2012
* \param sql query string
2013
* \return the number of database rows that were changed (or inserted or deleted)
2015
int ExecuteUpdate(const wxString& sql);
2017
/// Execute a insert, update or delete SQL statement given as a statement buffer
2019
* \param sql query string
2020
* \return the number of database rows that were changed (or inserted or deleted)
2022
int ExecuteUpdate(const wxSQLite3StatementBuffer& sql);
2024
/// Execute a insert, update or delete SQL statement given as a utf-8 character string
2026
* \param sql query string
2027
* \return the number of database rows that were changed (or inserted or deleted)
2029
int ExecuteUpdate(const char* sql);
2031
/// Execute a SQL query statement given as a wxString
2033
* \param sql query string
2034
* \return result set instance
2036
wxSQLite3ResultSet ExecuteQuery(const wxString& sql);
2038
/// Execute a SQL query statement given as a statement buffer
2040
* \param sql query string
2041
* \return result set instance
2043
wxSQLite3ResultSet ExecuteQuery(const wxSQLite3StatementBuffer& sql);
2045
/// Execute a SQL query statement given as a utf-8 character string
2047
* \param sql query string
2048
* \return result set instance
2050
wxSQLite3ResultSet ExecuteQuery(const char* sql);
2052
/// Execute a scalar SQL query statement given as a wxString
2054
* Allows to easily retrieve the result of queries returning a single integer result
2055
* like SELECT COUNT(*) FROM table WHERE condition.
2056
* \param sql query string
2057
* \return first column of first row as an int
2059
int ExecuteScalar(const wxString& sql);
2061
/// Execute a scalar SQL query statement given as a statement buffer
2063
* Allows to easily retrieve the result of queries returning a single integer result
2064
* like SELECT COUNT(*) FROM table WHERE condition.
2065
* \param sql query string
2066
* \return first column of first row as an int
2068
int ExecuteScalar(const wxSQLite3StatementBuffer& sql);
2070
/// Execute a scalar SQL query statement given as a utf-8 character string
2072
* Allows to easily retrieve the result of queries returning a single integer result
2073
* like SELECT COUNT(*) FROM table WHERE condition.
2074
* \param sql query string
2075
* \return first column of first row as an int
2077
int ExecuteScalar(const char* sql);
2079
/// Get the result table for a SQL query statement given as a wxString
2081
* Returns all resulting rows of the query for later processing.
2082
* \param sql query string
2083
* \return table instance
2085
wxSQLite3Table GetTable(const wxString& sql);
2087
/// Get the result table for a SQL query statement given as a statement buffer
2089
* Returns all resulting rows of the query for later processing.
2090
* \param sql query string
2091
* \return table instance
2093
wxSQLite3Table GetTable(const wxSQLite3StatementBuffer& sql);
2095
/// Get the result table for a SQL query statement given as a utf-8 character string
2097
* Returns all resulting rows of the query for later processing.
2098
* \param sql query string
2099
* \return table instance
2101
wxSQLite3Table GetTable(const char* sql);
2103
/// Prepare a SQL query statement given as a wxString for parameter binding
2105
* \param sql query string
2106
* \return statement instance
2108
wxSQLite3Statement PrepareStatement(const wxString& sql);
2110
/// Prepare a SQL query statement given as a statement buffer for parameter binding
2112
* \param sql query string
2113
* \return statement instance
2115
wxSQLite3Statement PrepareStatement(const wxSQLite3StatementBuffer& sql);
2117
/// Prepare a SQL query statement given as a utf-8 character string for parameter binding
2119
* \param sql query string
2120
* \return statement instance
2122
wxSQLite3Statement PrepareStatement(const char* sql);
2124
/// Get the row id of last inserted row
2126
* Each entry in an SQLite table has a unique integer key.
2127
* (The key is the value of the INTEGER PRIMARY KEY column if there is such a column,
2128
* otherwise the key is generated at random. The unique key is always available as the
2129
* ROWID, OID, or _ROWID_ column.)
2130
* \return the integer key of the most recent insert in the database.
2132
wxLongLong GetLastRowId();
2134
/// Get handle to a read only BLOB
2141
wxSQLite3Blob GetReadOnlyBlob(wxLongLong rowId,
2142
const wxString& columnName,
2143
const wxString& tableName,
2144
const wxString& dbName = wxEmptyString);
2146
/// Get handle to a writable BLOB
2153
wxSQLite3Blob GetWritableBlob(wxLongLong rowId,
2154
const wxString& columnName,
2155
const wxString& tableName,
2156
const wxString& dbName = wxEmptyString);
2158
/// Get handle to a BLOB
2166
wxSQLite3Blob GetBlob(wxLongLong rowId,
2167
const wxString& columnName,
2168
const wxString& tableName,
2169
const wxString& dbName = wxEmptyString,
2170
bool writable = true);
2172
/// Create a named integer value collection
2174
* Invoke this method to create a specific instance of an integer collection object.
2175
* Initially the created collection is empty. Use it's Bind method to actually bind
2176
* an array of values to the collection.
2177
* \param collectionName name of the collection
2178
* \return the new integer collection object.
2180
* Each integer value collection object corresponds to a virtual table in the TEMP table
2181
* with a name of collectionName.
2183
* The virtual table will be dropped implicitly when the database connection is closed.
2185
wxSQLite3IntegerCollection CreateIntegerCollection(const wxString& collectionName);
2187
/// Create a named string value collection
2189
* Invoke this method to create a specific instance of a string collection object.
2190
* Initially the created collection is empty. Use it's Bind method to actually bind
2191
* an array of values to the collection.
2192
* \param collectionName name of the collection
2193
* \return the new string collection object.
2195
* Each integer value collection object corresponds to a virtual table in the TEMP table
2196
* with a name of collectionName.
2198
* The virtual table will be dropped implicitly when the database connection is closed.
2200
wxSQLite3StringCollection CreateStringCollection(const wxString& collectionName);
2202
/// Interrupt a long running query
2204
* Causes any pending database operation to abort and return at its earliest opportunity.
2205
* This method is typically called in response to a user action such as pressing "Cancel"
2206
* or Ctrl-C where the user wants a long query operation to halt immediately.
2210
/// Set the busy timeout
2212
* This method sets a busy handler that sleeps for a while when a table is locked.
2213
* The handler will sleep multiple times until at least "ms" milliseconds of sleeping
2215
* Calling this routine with an argument less than or equal to zero turns off all busy handlers.
2216
* \param milliSeconds timeout in milliseconds
2218
void SetBusyTimeout(int milliSeconds);
2220
/// Create a user-defined scalar function
2222
* Registers a SQL scalar function with the database.
2224
* \param argCount number of arguments the scalar function takes.
2225
* If this argument is -1 then the scalar function may take any number of arguments.
2226
* \param function instance of an scalar function
2227
* \return TRUE on successful registration, FALSE otherwise
2229
bool CreateFunction(const wxString& name, int argCount, wxSQLite3ScalarFunction& function);
2231
/// Create a user-defined aggregate function
2233
* Registers a SQL aggregate function with the database.
2235
* \param argCount number of arguments the aggregate function takes.
2236
* If this argument is -1 then the aggregate function may take any number of arguments.
2237
* \param function instance of an aggregate function
2238
* \return TRUE on successful registration, FALSE otherwise
2240
bool CreateFunction(const wxString& name, int argCount, wxSQLite3AggregateFunction& function);
2242
/// Create a user-defined authorizer function
2244
* Registers an authorizer object with the SQLite library. The authorizer is invoked
2245
* (at compile-time, not at run-time) for each attempt to access a column of a table in the database.
2246
* The authorizer should return SQLITE_OK if access is allowed, SQLITE_DENY if the entire SQL statement
2247
* should be aborted with an error and SQLITE_IGNORE if the column should be treated as a NULL value.
2248
* \param authorizer instance of an authorizer function
2249
* \return TRUE on successful registration, FALSE otherwise
2251
bool SetAuthorizer(wxSQLite3Authorizer& authorizer);
2253
/// Create a user-defined commit callback function
2255
* Registers a callback function object to be invoked whenever a new transaction is committed.
2256
* If the callback function returns non-zero, then the commit is converted into a rollback.
2257
* Registering a NULL function object disables the callback. Only a single commit hook callback
2258
* can be registered at a time.
2259
* \param commitHook address of an instance of a commit callback function
2261
void SetCommitHook(wxSQLite3Hook* commitHook);
2263
/// Create a user-defined rollback callback function
2265
* Registers a callback function object to be invoked whenever a transaction is rolled back.
2266
* Registering a NULL function object disables the callback. Only a single rollback hook callback
2267
* can be registered at a time.
2269
* For the purposes of this API, a transaction is said to have been rolled back if an explicit
2270
* "ROLLBACK" statement is executed, or an error or constraint causes an implicit rollback to occur.
2271
* The callback is not invoked if a transaction is automatically rolled back because the database
2272
* connection is closed.
2273
* \param rollbackHook address of an instance of a rollback callback function
2275
void SetRollbackHook(wxSQLite3Hook* rollbackHook);
2277
/// Create a user-defined update callback function
2279
* Registers a callback function object to be invoked whenever a row is updated, inserted or deleted.
2280
* Registering a NULL function object disables the callback. Only a single commit hook callback
2281
* can be registered at a time.
2282
* The update hook is not invoked when internal system tables are modified (i.e. sqlite_master and sqlite_sequence).
2283
* \param updateHook address of an instance of an update callback function
2285
void SetUpdateHook(wxSQLite3Hook* updateHook);
2287
/// Create a user-defined Write Ahead Log callback function
2289
* Registers a callback function object to be invoked whenever a commit has taken place in WAL journal mode.
2290
* Registering a NULL function object disables the callback. Only a single Write Ahead Log hook callback
2291
* can be registered at a time.
2292
* \param walHook address of an instance of a Write Ahead Log callback function
2294
void SetWriteAheadLogHook(wxSQLite3Hook* walHook);
2296
/// Checkpoint database in write-ahead log mode
2298
* Causes an optionally named database to be checkpointed.
2299
* If no database name is given, then a checkpoint is run on all databases associated with this
2300
* database instance. If the database instance is not in write-ahead log mode then this method
2301
* is a harmless no-op.
2302
* \param database name of a database to be checkpointed
2303
* \param mode checkpoint mode, allowed values: WXSQLITE_CHECKPOINT_PASSIVE (default),
2304
* WXSQLITE_CHECKPOINT_FULL, WXSQLITE_CHECKPOINT_RESTART
2305
* (see http://www.sqlite.org/c3ref/wal_checkpoint_v2.html)
2306
* \param logFrameCount size of write-ahead log in frames
2307
* \param ckptFrameCount number of frames actually checkpointed
2308
* \note The frame counts are set to zero if the SQLite version is below 3.7.6.
2310
void WriteAheadLogCheckpoint(const wxString& database, int mode = WXSQLITE_CHECKPOINT_PASSIVE,
2311
int* logFrameCount = NULL, int* ckptFrameCount = NULL);
2313
/// Automatically checkpoint database in write-ahead log mode
2315
* Causes any database associated with this database instance to automatically checkpoint after
2316
* committing a transaction if there are N or more frames in the write-ahead log file.
2317
* Passing zero or a negative value as the nFrame parameter disables automatic checkpoints entirely.
2318
* \param frameCount frame threshold
2320
void AutoWriteAheadLogCheckpoint(int frameCount);
2322
/// Create a user-defined collation sequence
2324
* Registers a callback function object to be invoked whenever this collation is needed
2325
* in comparing strings.
2326
* Registering a NULL function object disables the specified collation sequence.
2327
* \param name name of a user-defined collation sequence
2328
* \param collation address of an instance of a user-defined collation sequence
2330
void SetCollation(const wxString& name, wxSQLite3Collation* collation);
2332
/// Return meta information about a specific column of a specific database table
2334
* \param dbName is either the name of the database (i.e. "main", "temp" or an attached database) or an empty string. If it is an empty string all attached databases are searched for the table.
2335
* \param tableName name of the database table
2336
* \param columnName name of the database column
2337
* \param dataType declared data type of the column. Pass NULL if information not needed.
2338
* \param collation name of the collation sequence. Pass NULL if information is not needed.
2339
* \param notNull output flag whether the column has a not null constraint. Pass NULL if information not needed.
2340
* \param primaryKey output flag whether the column is part of the primary key. Pass NULL if information not needed.
2341
* \param autoIncrement output flag whether the column is an auto increment column. Pass NULL if information not needed.
2343
* This method is only available if WXSQLITE3_HAVE_METADATA is defined and SQLite has been compiled with SQLITE_ENABLE_COLUMN_METADATA defined.
2345
void GetMetaData(const wxString& dbName, const wxString& tableName, const wxString& columnName,
2346
wxString* dataType = NULL, wxString* collation = NULL,
2347
bool* notNull = NULL, bool* primaryKey = NULL, bool* autoIncrement = NULL);
2349
/// Load a database extension
2351
* \param fileName Name of the shared library containing extension.
2352
* \param entryPoint Name of the entry point.
2354
void LoadExtension(const wxString& fileName, const wxString& entryPoint = wxT("sqlite3_extension_init"));
2356
/// Enable or disable loading of database extensions
2358
* \param enable Flag whether to enable (TRUE) or disable (FALSE) loadable extensions
2360
void EnableLoadExtension(bool enable);
2362
/// Change the encryption key of the database
2364
* If the database is currently not encrypted, this method will encrypt it.
2365
* If an empty key (with key length == 0) is given, the database is decrypted.
2367
* \param newKey The new encryption key (will be converted to UTF-8)
2369
void ReKey(const wxString& newKey);
2371
/// Change the encryption key of the database
2373
* If the database is currently not encrypted, this method will encrypt it.
2374
* If an empty key (with key length == 0) is given, the database is decrypted.
2376
* \param newKey The new encryption key
2378
void ReKey(const wxMemoryBuffer& newKey);
2380
/// Check whether the database is encrypted
2382
* Check whether the database has been opened using an encryption key.
2384
* \return TRUE if database is encrypted, FALSE otherwise
2386
bool IsEncrypted() const { return m_isEncrypted; }
2388
/// Query the value of a database limit
2390
* This method allows to query several database limits. Consult the SQLite
2391
* documentation for further explanation.
2393
* \param id The identifier of the limit to be queried
2394
* \return the current value of the queried limit
2396
int GetLimit(wxSQLite3LimitType id);
2398
/// Change a database limit to a new value
2400
* This method allows to change several database limits. Consult the SQLite
2401
* documentation for further explanation.
2403
* \param id The identifier of the limit to be queried
2404
* \param newValue The new value of the limit to be set
2405
* \return the previous value of the specified limit
2407
int SetLimit(wxSQLite3LimitType id, int newValue);
2409
/// Convert database limit type to string
2411
* \param type The database limit type to be converted to string representation.
2413
static wxString LimitTypeToString(wxSQLite3LimitType type);
2415
/// Initialize the SQLite library
2417
* Starting with SQLite version 3.6.0 there is a new method to initialize
2418
* the SQLite library. Currently an explicit call to this method is not
2419
* required, but this behaviour might change in the future of SQLite.
2420
* Therefore it is recommended to call this method once before accessing
2421
* any SQLite databases.
2423
static void InitializeSQLite();
2425
/// Shutdown the SQLite library
2427
* Starting with SQLite version 3.6.0 there is a new method to shutdown
2428
* the SQLite library. Currently an explicit call to this method is not
2429
* required, but this behaviour might change in the future of SQLite.
2430
* Therefore it is recommended to call this method once when no further
2431
* access to any SQLite databases is required.
2433
static void ShutdownSQLite();
2435
/// Get random bytes
2437
* SQLite contains a high-quality pseudo-random number generator.
2438
* This method allows to access it for application specofoc purposes.
2440
* \param n The amount of random bytes to be created
2441
* \param random A memory buffer containing the random bytes on return
2443
static bool Randomness(int n, wxMemoryBuffer& random);
2445
/// Enable or disable SQLite shared cache
2447
* The cache sharing mode set effects all subsequent database connections.
2448
* Existing database connections continue use the sharing mode that was in effect
2449
* at the time they were opened.
2451
* Virtual tables cannot be used with a shared cache.
2453
static void SetSharedCache(bool enable);
2455
/// Check whether SQLite shared cache is enabled
2457
* \return TRUE if the SQLite shared cache is enabled, FALSE otherwise
2459
static bool IsSharedCacheEnabled() { return ms_sharedCacheEnabled; }
2461
/// Get the version of the underlying SQLite3 library
2463
* \return a string which contains the version number of the library
2465
static wxString GetVersion();
2467
/// Get the source id of the underlying SQLite3 library
2469
* \return a string which contains the source id of the library
2471
static wxString GetSourceId();
2473
/// Check SQLite compile option
2475
* Check whether the compile option with a given name has been used on building SQLite.
2476
* The SQLITE_ prefix may be omitted from the option name passed to this method.
2478
* \param optionName name of the compile option to be queried
2479
* \return TRUE if the compile option was in use, FALSE otherwise
2481
* \note If the option name is unknown or if the SQLite version is lower than 3.6.23
2482
* this method returns FALSE.
2484
static bool CompileOptionUsed(const wxString& optionName);
2486
/// Get SQLite compile option name
2488
* Get the name of a SQLite compile option at a given index.
2489
* This method allows interating over the list of options that were defined
2490
* at compile time. If the option index is out of range, an empty string is returned.
2491
* The SQLITE_ prefix is omitted from any strings returned by this method.
2493
* \param optionIndex Index of the compile option
2494
* \return a string containing the name of the n-th
2496
static wxString GetCompileOptionName(int optionIndex);
2498
/// Convert journal mode to/from string
2500
* \param mode the wxSQLite3JournalMode enum value signifying the desired journal mode.
2501
* \return the string representation of the journal mode
2503
static wxString ConvertJournalMode(wxSQLite3JournalMode mode);
2505
/// Convert journal mode to/from string
2507
* \param mode the string representation of the desired journal mode.
2508
* \return the enum representation of the journal mode
2510
static wxSQLite3JournalMode ConvertJournalMode(const wxString& mode);
2512
/// Check whether wxSQLite3 has been compiled with encryption support
2514
* \return TRUE if encryption support is enabled, FALSE otherwise
2516
static bool HasEncryptionSupport();
2518
/// Check whether wxSQLite3 has been compiled with meta data support
2520
* \return TRUE if meta data support is enabled, FALSE otherwise
2522
static bool HasMetaDataSupport();
2524
/// Check whether wxSQLite3 has been compiled with loadable extension support
2526
* \return TRUE if loadable extension support is enabled, FALSE otherwise
2528
static bool HasLoadExtSupport();
2530
/// Check whether wxSQLite3 has been compiled with support for named collections
2532
* \return TRUE if named collection support is enabled, FALSE otherwise
2534
static bool HasNamedCollectionSupport();
2536
/// Check whether wxSQLite3 has support for incremental BLOBs
2538
* \return TRUE if incremental BLOB support is available, FALSE otherwise
2540
static bool HasIncrementalBlobSupport();
2542
/// Check whether wxSQLite3 has support for SQLite savepoints
2544
* \return TRUE if SQLite savepoints are supported, FALSE otherwise
2546
static bool HasSavepointSupport();
2548
/// Check whether wxSQLite3 has support for SQLite backup/restore
2550
* \return TRUE if SQLite backup/restore is supported, FALSE otherwise
2552
static bool HasBackupSupport();
2554
/// Check whether wxSQLite3 has support for SQLite write-ahead log
2556
* \return TRUE if SQLite write-ahead log is supported, FALSE otherwise
2558
static bool HasWriteAheadLogSupport();
2561
/// Access SQLite's internal database handle
2562
void* GetDatabaseHandle() { return m_db; }
2564
/// Activate the callback for needed collations for this database
2566
* To avoid having to register all collation sequences before a database can be used,
2567
* a single callback function may be registered with the database handle to be called
2568
* whenever an undefined collation sequence is required.
2570
void SetCollationNeededCallback();
2572
/// Request the instantiation of a user defined collation sequence
2574
* This method is called for every undefined collation sequence.
2575
* In a derived database class this method should call SetCollation registering an
2576
* appropriate collation class instance.
2577
* \param collationName name of the collation which is needed for string comparison
2579
virtual void SetNeededCollation(const wxString& WXUNUSED(collationName)) {}
2581
/// Execute a comparison using a user-defined collation
2582
static int ExecComparisonWithCollation(void* collation, int len1, const void* txt1, int len2, const void* txt2);
2584
/// Execute callback for needed collation sequences
2585
static void ExecCollationNeeded(void* db, void* internalDb, int eTextRep, const char* name);
2588
/// Private copy constructor
2589
wxSQLite3Database(const wxSQLite3Database& db);
2591
/// Private assignment constructor
2592
wxSQLite3Database& operator=(const wxSQLite3Database& db);
2594
/// Prepare a SQL statement (internal use only)
2595
void* Prepare(const char* sql);
2597
/// Check for valid database connection
2598
void CheckDatabase();
2600
void* m_db; ///< associated SQLite3 database
2601
int m_busyTimeoutMs; ///< Timeout in milli seconds
2602
bool m_isEncrypted; ///< Flag whether the database is encrypted or not
2604
static bool ms_sharedCacheEnabled; ///< Flag whether SQLite shared cache is enabled
2605
static bool ms_hasEncryptionSupport; ///< Flag whether wxSQLite3 has been compiled with encryption support
2606
static bool ms_hasMetaDataSupport; ///< Flag whether wxSQLite3 has been compiled with meta data support
2607
static bool ms_hasLoadExtSupport; ///< Flag whether wxSQLite3 has been compiled with loadable extension support
2608
static bool ms_hasNamedCollectionSupport; ///< Flag whether wxSQLite3 has been compiled with support for named collections
2609
static bool ms_hasIncrementalBlobSupport; ///< Flag whether wxSQLite3 has support for incremental BLOBs
2610
static bool ms_hasSavepointSupport; ///< Flag whether wxSQLite3 has support for SQLite savepoints
2611
static bool ms_hasBackupSupport; ///< Flag whether wxSQLite3 has support for SQLite backup/restore
2612
static bool ms_hasWriteAheadLogSupport; ///< Flag whether wxSQLite3 has support for SQLite write-ahead log
2615
/// RAII class for managing transactions
2617
* This object allows easy managment of transaction. It con only be
2618
* created on the stack. This guarantees that the destructor is called
2619
* at the moment it goes out of scope. Usage:
2621
* void doDB(wxSQLite3Database *db)
2623
* wxSQLite3Transaction t(db);
2624
* doDatabaseOperations();
2628
* In case doDatabseOperations() fails by throwing an exception,
2629
* the transaction is automatically rolled back. If it succedes,
2630
* Commit() commits the changes to the db and the destructor
2631
* of Transaction does nothing.
2633
class EXTAPI wxSQLite3Transaction
2636
/// Constructor. Start the Transaction.
2638
* The constructor starts the transaction.
2639
* \param db Pointer to the open Database. The pointer to the database
2640
* is NOT freed on destruction!
2641
* \param transactionType Type of the transaction to be opened.
2643
explicit wxSQLite3Transaction(wxSQLite3Database* db, wxSQLite3TransactionType transactionType = WXSQLITE_TRANSACTION_DEFAULT);
2647
* The destructor does nothing if the changes were already commited (see commit()).
2648
* In case the changes were not commited, a call to the destructor rolls back the
2651
~wxSQLite3Transaction();
2653
/// Commits the transaction
2655
* Commits the transaction if active. If not, it does nothing.
2656
* After the commit, the transaction is not active.
2660
/// Rolls back the transaction
2662
* Rolls back the transaction if active. If not, it does nothing.
2663
* After the rollback, the transaction is not active.
2667
/// Determins wether the transaction is open or not
2669
* \return TRUE if the constructor successfully opend the transaction, false otherwise.
2670
* After committing the transaction, active returns false.
2672
inline bool IsActive()
2674
return m_database != NULL;
2678
/// New operator (May only be created on the stack)
2679
static void *operator new(size_t size);
2681
/// Delete operator (May not be deleted (for symmetry))
2682
static void operator delete(void *ptr);
2684
/// Copy constructor (Must not be copied)
2685
wxSQLite3Transaction(const wxSQLite3Transaction&);
2687
/// Assignment operator (Must not be assigned)
2688
wxSQLite3Transaction& operator=(const wxSQLite3Transaction&);
2690
wxSQLite3Database* m_database; ///< Pointer to the associated database (no ownership)
2695
/// User defined function for REGEXP operator
2698
class EXTAPI wxSQLite3RegExpOperator : public wxSQLite3ScalarFunction
2702
wxSQLite3RegExpOperator(int flags = wxRE_DEFAULT);
2704
/// Virtual destructor
2705
virtual ~wxSQLite3RegExpOperator();
2707
/// Execute the scalar function
2709
* This method is invoked for each appearance of the scalar function in the SQL query.
2710
* \param ctx function context which can be used to access arguments and result value
2712
virtual void Execute(wxSQLite3FunctionContext& ctx);
2715
wxString m_exprStr; ///< Last regular expression string
2716
wxRegEx m_regEx; ///< Regular expression cache (currently only 1 instance)
2717
int m_flags; ///< Flags for regular expression
2720
#endif // wxUSE_REGEX
added
removed
src/cadxcore/wx/wxsqlite3/wxsqlite3.h
