|
0
|
1 ///////////////////////////////////////////////////////////////////////////////
|
|
|
2 // Name: wxsqlite3.h
|
|
|
3 // Purpose: wxWidgets wrapper around the SQLite3 embedded database library.
|
|
|
4 // Author: Ulrich Telle
|
|
|
5 // Modified by:
|
|
|
6 // Created: 2005-07-14
|
|
|
7 // Copyright: (c) Ulrich Telle
|
|
|
8 // Licence: wxWindows licence
|
|
|
9 ///////////////////////////////////////////////////////////////////////////////
|
|
|
10
|
|
|
11 /// \file wxsqlite3.h Interface of the wxSQLite3 class
|
|
|
12
|
|
|
13 #ifndef _WX_SQLITE3_H_
|
|
|
14 #define _WX_SQLITE3_H_
|
|
|
15
|
|
|
16 #if defined(__GNUG__) && !defined(__APPLE__)
|
|
|
17 #pragma interface "wxsqlite3.h"
|
|
|
18 #endif
|
|
|
19
|
|
|
20 #include <wx/arrstr.h>
|
|
|
21 #include <wx/datetime.h>
|
|
|
22 #include <wx/buffer.h>
|
|
|
23 #include <wx/hashmap.h>
|
|
|
24 #include <wx/regex.h>
|
|
|
25 #include <wx/string.h>
|
|
|
26
|
|
|
27 #include "wx/wxsqlite3def.h"
|
|
|
28
|
|
|
29 #define WXSQLITE_ERROR 1000
|
|
|
30
|
|
|
31 #define WXSQLITE_INTEGER 1
|
|
|
32 #define WXSQLITE_FLOAT 2
|
|
|
33 #define WXSQLITE_TEXT 3
|
|
|
34 #define WXSQLITE_BLOB 4
|
|
|
35 #define WXSQLITE_NULL 5
|
|
|
36
|
|
|
37 #if defined(_MSC_VER) || defined(__BORLANDC__)
|
|
|
38 typedef __int64 wxsqlite_int64;
|
|
|
39 #else
|
|
|
40 typedef long long int wxsqlite_int64;
|
|
|
41 #endif
|
|
|
42
|
|
|
43 /// Enumeration of transaction types
|
|
|
44 enum wxSQLite3TransactionType
|
|
|
45 {
|
|
|
46 WXSQLITE_TRANSACTION_DEFAULT,
|
|
|
47 WXSQLITE_TRANSACTION_DEFERRED,
|
|
|
48 WXSQLITE_TRANSACTION_IMMEDIATE,
|
|
|
49 WXSQLITE_TRANSACTION_EXCLUSIVE
|
|
|
50 };
|
|
|
51
|
|
|
52 /// Enumeration of SQLite limitation types
|
|
|
53 enum wxSQLite3LimitType
|
|
|
54 {
|
|
|
55 WXSQLITE_LIMIT_LENGTH = 0,
|
|
|
56 WXSQLITE_LIMIT_SQL_LENGTH = 1,
|
|
|
57 WXSQLITE_LIMIT_COLUMN = 2,
|
|
|
58 WXSQLITE_LIMIT_EXPR_DEPTH = 3,
|
|
|
59 WXSQLITE_LIMIT_COMPOUND_SELECT = 4,
|
|
|
60 WXSQLITE_LIMIT_VDBE_OP = 5,
|
|
|
61 WXSQLITE_LIMIT_FUNCTION_ARG = 6,
|
|
|
62 WXSQLITE_LIMIT_ATTACHED = 7,
|
|
|
63 WXSQLITE_LIMIT_LIKE_PATTERN_LENGTH = 8,
|
|
|
64 WXSQLITE_LIMIT_VARIABLE_NUMBER = 9,
|
|
|
65 WXSQLITE_LIMIT_TRIGGER_DEPTH = 10
|
|
|
66 };
|
|
|
67
|
|
|
68 /// Enumeration of journal modes
|
|
|
69 enum wxSQLite3JournalMode
|
|
|
70 {
|
|
|
71 WXSQLITE_JOURNALMODE_DELETE = 0, // Commit by deleting journal file
|
|
|
72 WXSQLITE_JOURNALMODE_PERSIST = 1, // Commit by zeroing journal header
|
|
|
73 WXSQLITE_JOURNALMODE_OFF = 2, // Journal omitted.
|
|
|
74 WXSQLITE_JOURNALMODE_TRUNCATE = 3, // Commit by truncating journal
|
|
|
75 WXSQLITE_JOURNALMODE_MEMORY = 4, // In-memory journal file
|
|
|
76 WXSQLITE_JOURNALMODE_WAL = 5 // Use write-ahead logging
|
|
|
77 };
|
|
|
78
|
|
|
79 #define WXSQLITE_OPEN_READONLY 0x00000001
|
|
|
80 #define WXSQLITE_OPEN_READWRITE 0x00000002
|
|
|
81 #define WXSQLITE_OPEN_CREATE 0x00000004
|
|
|
82 #define WXSQLITE_OPEN_NOMUTEX 0x00008000
|
|
|
83 #define WXSQLITE_OPEN_FULLMUTEX 0x00010000
|
|
|
84 #define WXSQLITE_OPEN_SHAREDCACHE 0x00020000
|
|
|
85 #define WXSQLITE_OPEN_PRIVATECACHE 0x00040000
|
|
|
86
|
|
|
87 inline void operator++(wxSQLite3LimitType& value)
|
|
|
88 {
|
|
|
89 value = wxSQLite3LimitType(value+1);
|
|
|
90 }
|
|
|
91
|
|
|
92 /// SQL exception
|
|
|
93 class WXDLLIMPEXP_SQLITE3 wxSQLite3Exception
|
|
|
94 {
|
|
|
95 public:
|
|
|
96 /// Constructor
|
|
|
97 wxSQLite3Exception(int errorCode, const wxString& errMsg);
|
|
|
98
|
|
|
99 /// Copy constructor
|
|
|
100 wxSQLite3Exception(const wxSQLite3Exception& e);
|
|
|
101
|
|
|
102 /// Destructor
|
|
|
103 virtual ~wxSQLite3Exception();
|
|
|
104
|
|
|
105 /// Get error code associated with the exception
|
|
|
106 int GetErrorCode() const { return (m_errorCode & 0xff); }
|
|
|
107
|
|
|
108 /// Get extended error code associated with the exception
|
|
|
109 int GetExtendedErrorCode() const { return m_errorCode; }
|
|
|
110
|
|
|
111 /// Get error message associated with the exception
|
|
|
112 const wxString GetMessage() const { return m_errorMessage; }
|
|
|
113
|
|
|
114 /// Convert error code to error message
|
|
|
115 static const wxString ErrorCodeAsString(int errorCode);
|
|
|
116
|
|
|
117 private:
|
|
|
118 int m_errorCode; ///< SQLite3 error code associated with this exception
|
|
|
119 wxString m_errorMessage; ///< SQLite3 error message associated with this exception
|
|
|
120 };
|
|
|
121
|
|
|
122 /// SQL statment buffer for use with SQLite3's printf method
|
|
|
123 class WXDLLIMPEXP_SQLITE3 wxSQLite3StatementBuffer
|
|
|
124 {
|
|
|
125 public:
|
|
|
126 /// Constructor
|
|
|
127 wxSQLite3StatementBuffer();
|
|
|
128
|
|
|
129 /// Destructor
|
|
|
130 ~wxSQLite3StatementBuffer();
|
|
|
131
|
|
|
132 /// Format a SQL statement using SQLite3's printf method
|
|
|
133 /**
|
|
|
134 * This method is a variant of the "sprintf()" from the standard C library.
|
|
|
135 * All of the usual printf formatting options apply. In addition,
|
|
|
136 * there is a "%q" option. %q works like %s in that it substitutes
|
|
|
137 * a null-terminated string from the argument list. But %q also
|
|
|
138 * doubles every '\'' character. %q is designed for use inside a
|
|
|
139 * string literal. By doubling each '\'' character it escapes that
|
|
|
140 * character and allows it to be inserted into the string.
|
|
|
141 *
|
|
|
142 * For example, so some string variable contains text as follows:
|
|
|
143 *
|
|
|
144 * char *zText = "It's a happy day!";
|
|
|
145 *
|
|
|
146 * One can use this text in an SQL statement as follows:
|
|
|
147 *
|
|
|
148 * wxSQLite3StatementBuffer stmtBuffer;
|
|
|
149 * stmtBuffer.Format("INSERT INTO table VALUES('%q')", zText);
|
|
|
150 *
|
|
|
151 * Because the %q format string is used, the '\'' character in
|
|
|
152 * zText is escaped and the SQL generated is as follows:
|
|
|
153 *
|
|
|
154 * INSERT INTO table1 VALUES('It''s a happy day!')
|
|
|
155 *
|
|
|
156 * \param format SQL statement string with formatting options
|
|
|
157 * \param ... list of statement parameters
|
|
|
158 * \return const char pointer to the resulting statement buffer
|
|
|
159 */
|
|
|
160 const char* Format(const char* format, ...);
|
|
|
161
|
|
|
162 /// Format a SQL statement using SQLite3's printf method
|
|
|
163 /**
|
|
|
164 * This method is like method Format but takes a va_list argument
|
|
|
165 * to pass the statement parameters.
|
|
|
166 *
|
|
|
167 * \param format SQL statement string with formatting options
|
|
|
168 * \param va va_list of statement parameters
|
|
|
169 * \return const char pointer to the resulting statement buffer
|
|
|
170 */
|
|
|
171 const char* FormatV(const char* format, va_list va);
|
|
|
172
|
|
|
173 /// Dereference the internal buffer
|
|
|
174 /**
|
|
|
175 * \return const char pointer to the resulting statement buffer
|
|
|
176 */
|
|
|
177 operator const char*() const { return m_buffer; }
|
|
|
178
|
|
|
179 /// Clear the internal buffer
|
|
|
180 void Clear();
|
|
|
181
|
|
|
182 private:
|
|
|
183 char* m_buffer; ///< Internal buffer
|
|
|
184 };
|
|
|
185
|
|
|
186 /// Context for user defined scalar or aggregate functions
|
|
|
187 /**
|
|
|
188 * A function context gives user defined scalar or aggregate functions
|
|
|
189 * access to function arguments and function results. The "Execute" method
|
|
|
190 * resp. the "Aggregate" and "Finalize" methods receive the current
|
|
|
191 * function context as an argument.
|
|
|
192 */
|
|
|
193 class WXDLLIMPEXP_SQLITE3 wxSQLite3FunctionContext
|
|
|
194 {
|
|
|
195 public:
|
|
|
196 /// Get the number of function arguments
|
|
|
197 /**
|
|
|
198 * \return the number of arguments the function was called with
|
|
|
199 */
|
|
|
200 int GetArgCount();
|
|
|
201
|
|
|
202 /// Get the type of a function argument
|
|
|
203 /**
|
|
|
204 * \param argIndex index of the function argument. Indices start with 0.
|
|
|
205 * \return argument type as one of the values WXSQLITE_INTEGER, WXSQLITE_FLOAT, WXSQLITE_TEXT, WXSQLITE_BLOB, or WXSQLITE_NULL
|
|
|
206 */
|
|
|
207 int GetArgType(int argIndex);
|
|
|
208
|
|
|
209 /// Check whether a function argument is a NULL value
|
|
|
210 /**
|
|
|
211 * \param argIndex index of the function argument. Indices start with 0.
|
|
|
212 * \return TRUE if the argument is NULL or the argIndex is out of bounds, FALSE otherwise
|
|
|
213 */
|
|
|
214 bool IsNull(int argIndex);
|
|
|
215
|
|
|
216 /// Get a function argument as an integer value
|
|
|
217 /**
|
|
|
218 * \param argIndex index of the function argument. Indices start with 0.
|
|
|
219 * \param nullValue value to be returned in case the argument is NULL
|
|
|
220 * \return argument value
|
|
|
221 */
|
|
|
222 int GetInt(int argIndex, int nullValue = 0);
|
|
|
223
|
|
|
224 /// Get a function argument as an 64-bit integer value
|
|
|
225 /**
|
|
|
226 * \param argIndex index of the function argument. Indices start with 0.
|
|
|
227 * \param nullValue value to be returned in case the argument is NULL
|
|
|
228 * \return argument value
|
|
|
229 */
|
|
|
230 wxLongLong GetInt64(int argIndex, wxLongLong nullValue = 0);
|
|
|
231
|
|
|
232 /// Get a function argument as a double value
|
|
|
233 /**
|
|
|
234 * \param argIndex index of the function argument. Indices start with 0.
|
|
|
235 * \param nullValue value to be returned in case the argument is NULL
|
|
|
236 * \return argument value
|
|
|
237 */
|
|
|
238 double GetDouble(int argIndex, double nullValue = 0);
|
|
|
239
|
|
|
240 /// Get a function argument as a string value
|
|
|
241 /**
|
|
|
242 * \param argIndex index of the function argument. Indices start with 0.
|
|
|
243 * \param nullValue value to be returned in case the argument is NULL
|
|
|
244 * \return argument value
|
|
|
245 */
|
|
|
246 wxString GetString(int argIndex, const wxString& nullValue = wxEmptyString);
|
|
|
247
|
|
|
248 /// Get a function argument as a BLOB value
|
|
|
249 /**
|
|
|
250 * \param argIndex index of the function argument. Indices start with 0.
|
|
|
251 * \param[out] len length of the blob argument in bytes
|
|
|
252 * \return argument value
|
|
|
253 */
|
|
|
254 const unsigned char* GetBlob(int argIndex, int& len);
|
|
|
255
|
|
|
256 /// Get a function argument as a BLOB value
|
|
|
257 /**
|
|
|
258 * \param argIndex index of the function argument. Indices start with 0.
|
|
|
259 * \param[out] buffer to which the blob argument value is appended
|
|
|
260 * \return reference to argument value
|
|
|
261 */
|
|
|
262 wxMemoryBuffer& GetBlob(int argIndex, wxMemoryBuffer& buffer);
|
|
|
263
|
|
|
264 /// Set the function result as an integer value
|
|
|
265 /**
|
|
|
266 * \param value function result value
|
|
|
267 */
|
|
|
268 void SetResult(int value);
|
|
|
269
|
|
|
270 /// Set the function result as an 64-bit integer value
|
|
|
271 /**
|
|
|
272 * \param value function result value
|
|
|
273 */
|
|
|
274 void SetResult(wxLongLong value);
|
|
|
275
|
|
|
276 /// Set the function result as a double value
|
|
|
277 /**
|
|
|
278 * \param value function result value
|
|
|
279 */
|
|
|
280 void SetResult(double value);
|
|
|
281
|
|
|
282 /// Set the function result as a string value
|
|
|
283 /**
|
|
|
284 * \param value function result value
|
|
|
285 */
|
|
|
286 void SetResult(const wxString& value);
|
|
|
287
|
|
|
288 /// Set the function result as a BLOB value
|
|
|
289 /**
|
|
|
290 * \param value function result value
|
|
|
291 * \param len length of the result blob in bytes
|
|
|
292 */
|
|
|
293 void SetResult(unsigned char* value, int len);
|
|
|
294
|
|
|
295 /// Set the function result as a BLOB value
|
|
|
296 /**
|
|
|
297 * \param buffer containing the function result value
|
|
|
298 */
|
|
|
299 void SetResult(const wxMemoryBuffer& buffer);
|
|
|
300
|
|
|
301 /// Set the function result as a NULL value
|
|
|
302 void SetResultNull();
|
|
|
303
|
|
|
304 /// Set the function result as a zero BLOB value
|
|
|
305 /**
|
|
|
306 * \param blobSize size of the zero filled BLOB value
|
|
|
307 */
|
|
|
308 void SetResultZeroBlob(int blobSize);
|
|
|
309
|
|
|
310 /// Set the function result as a exact copy of a function argument
|
|
|
311 /**
|
|
|
312 * \param argIndex index of the argument which should be copied as the result value
|
|
|
313 */
|
|
|
314 void SetResultArg(int argIndex);
|
|
|
315
|
|
|
316 /// Set an error message as the function result
|
|
|
317 /**
|
|
|
318 * \param errmsg string containing an error message
|
|
|
319 */
|
|
|
320 void SetResultError(const wxString& errmsg);
|
|
|
321
|
|
|
322 /// Get the number of aggregate steps
|
|
|
323 /**
|
|
|
324 * \return the number of aggregation steps. The current aggregation step counts so at least 1 is returned.
|
|
|
325 */
|
|
|
326 int GetAggregateCount();
|
|
|
327
|
|
|
328 /// Get a pointer to an aggregate structure of specified length
|
|
|
329 /**
|
|
|
330 * Usually an aggregation functions needs temporary memory to collect
|
|
|
331 * the information gathered from each invocation of the "Aggregate" method.
|
|
|
332 * On the first invocation of this method the returned memory contains
|
|
|
333 * binary zeros.
|
|
|
334 * If this memory is used to store pointers to allocated objects,
|
|
|
335 * it is important to free all allocated objects in the "Finalize" method.
|
|
|
336 *
|
|
|
337 * \param len amount of memory needed in bytes
|
|
|
338 * \return pointer to the allocated memory
|
|
|
339 */
|
|
|
340 void* GetAggregateStruct(int len);
|
|
|
341
|
|
|
342 /// Execute a user defined scalar function (internal use only)
|
|
|
343 static void ExecScalarFunction(void* ctx, int argc, void** argv);
|
|
|
344
|
|
|
345 /// Execute an aggregate step of a user defined aggregate function (internal use only)
|
|
|
346 static void ExecAggregateStep(void* ctx, int argc, void** argv);
|
|
|
347
|
|
|
348 /// Execute the final step of a user defined aggregate function (internal use only)
|
|
|
349 static void ExecAggregateFinalize(void* ctx);
|
|
|
350
|
|
|
351 /// Execute the user defined authorizer function (internal use only)
|
|
|
352 static int ExecAuthorizer(void*, int type,
|
|
|
353 const char* arg1, const char* arg2,
|
|
|
354 const char* arg3, const char* arg4);
|
|
|
355
|
|
|
356 /// Execute the user defined commit hook (internal use only)
|
|
|
357 static int ExecCommitHook(void* hook);
|
|
|
358
|
|
|
359 /// Execute the user defined rollback hook (internal use only)
|
|
|
360 static void ExecRollbackHook(void* hook);
|
|
|
361
|
|
|
362 /// Execute the user defined update hook (internal use only)
|
|
|
363 static void ExecUpdateHook(void* hook, int type,
|
|
|
364 const char* database, const char* table,
|
|
|
365 wxsqlite_int64 rowid);
|
|
|
366
|
|
|
367 /// Execute the user defined Write Ahead Log hook (internal use only)
|
|
|
368 static int ExecWriteAheadLogHook(void* hook, void* dbHandle,
|
|
|
369 const char* database, int numPages);
|
|
|
370
|
|
|
371 private:
|
|
|
372 /// Constructor
|
|
|
373 wxSQLite3FunctionContext(void* ctx, bool isAggregate, int argc = 0, void** argv = NULL);
|
|
|
374
|
|
|
375 /// Copy constructor
|
|
|
376 wxSQLite3FunctionContext(wxSQLite3FunctionContext& ctx);
|
|
|
377
|
|
|
378 void* m_ctx; ///< SQLite3 context
|
|
|
379 bool m_isAggregate; ///< Flag whether this is the context of an aggregate function
|
|
|
380 int m_count; ///< Aggregate count
|
|
|
381 int m_argc; ///< Number of arguments
|
|
|
382 void** m_argv; ///< Array of SQLite3 arguments
|
|
|
383 };
|
|
|
384
|
|
|
385
|
|
|
386 /// Interface for user defined scalar functions
|
|
|
387 /**
|
|
|
388 */
|
|
|
389 class WXDLLIMPEXP_SQLITE3 wxSQLite3ScalarFunction
|
|
|
390 {
|
|
|
391 public:
|
|
|
392 /// Constructor
|
|
|
393 wxSQLite3ScalarFunction() {}
|
|
|
394
|
|
|
395 /// Virtual destructor
|
|
|
396 virtual ~wxSQLite3ScalarFunction() {}
|
|
|
397 /// Execute the scalar function
|
|
|
398 /**
|
|
|
399 * This method is invoked for each appearance of the scalar function in the SQL query.
|
|
|
400 * \param ctx function context which can be used to access arguments and result value
|
|
|
401 */
|
|
|
402 virtual void Execute(wxSQLite3FunctionContext& ctx) = 0;
|
|
|
403 };
|
|
|
404
|
|
|
405
|
|
|
406 /// Interface for user defined aggregate functions
|
|
|
407 /**
|
|
|
408 */
|
|
|
409 class WXDLLIMPEXP_SQLITE3 wxSQLite3AggregateFunction
|
|
|
410 {
|
|
|
411 public:
|
|
|
412 /// Constructor
|
|
|
413 wxSQLite3AggregateFunction() { m_count = 0; }
|
|
|
414
|
|
|
415 /// Virtual destructor
|
|
|
416 virtual ~wxSQLite3AggregateFunction() {}
|
|
|
417 /// Execute the aggregate of the function
|
|
|
418 /**
|
|
|
419 * This method is invoked for each row of the result set of the query using the aggregate function.
|
|
|
420 * \param ctx function context which can be used to access arguments and result value
|
|
|
421 */
|
|
|
422 virtual void Aggregate(wxSQLite3FunctionContext& ctx) = 0;
|
|
|
423
|
|
|
424 /// Prepare the result of the aggregate function
|
|
|
425 /**
|
|
|
426 * This method is invoked after all rows of the result set of the query
|
|
|
427 * using the aggregate function have been processed. Usually the final result
|
|
|
428 * is calculated and returned in this method.
|
|
|
429 * \param ctx function context which can be used to access arguments and result value
|
|
|
430 */
|
|
|
431 virtual void Finalize(wxSQLite3FunctionContext& ctx) = 0;
|
|
|
432
|
|
|
433 private:
|
|
|
434 int m_count; ///< Aggregate count
|
|
|
435 friend class wxSQLite3FunctionContext;
|
|
|
436 };
|
|
|
437
|
|
|
438
|
|
|
439 /// Interface for a user defined authorizer function
|
|
|
440 /**
|
|
|
441 */
|
|
|
442 class WXDLLIMPEXP_SQLITE3 wxSQLite3Authorizer
|
|
|
443 {
|
|
|
444 public:
|
|
|
445 /// Codes identifying the command for which authorization is requested
|
|
|
446 enum wxAuthorizationCode
|
|
|
447 { // arg1 = arg2 =
|
|
|
448 SQLITE_COPY = 0, // Table Name File Name
|
|
|
449 SQLITE_CREATE_INDEX = 1, // Index Name Table Name
|
|
|
450 SQLITE_CREATE_TABLE = 2, // Table Name NULL
|
|
|
451 SQLITE_CREATE_TEMP_INDEX = 3, // Index Name Table Name
|
|
|
452 SQLITE_CREATE_TEMP_TABLE = 4, // Table Name NULL
|
|
|
453 SQLITE_CREATE_TEMP_TRIGGER = 5, // Trigger Name Table Name
|
|
|
454 SQLITE_CREATE_TEMP_VIEW = 6, // View Name NULL
|
|
|
455 SQLITE_CREATE_TRIGGER = 7, // Trigger Name Table Name
|
|
|
456 SQLITE_CREATE_VIEW = 8, // View Name NULL
|
|
|
457 SQLITE_DELETE = 9, // Table Name NULL
|
|
|
458 SQLITE_DROP_INDEX = 10, // Index Name Table Name
|
|
|
459 SQLITE_DROP_TABLE = 11, // Table Name NULL
|
|
|
460 SQLITE_DROP_TEMP_INDEX = 12, // Index Name Table Name
|
|
|
461 SQLITE_DROP_TEMP_TABLE = 13, // Table Name NULL
|
|
|
462 SQLITE_DROP_TEMP_TRIGGER = 14, // Trigger Name Table Name
|
|
|
463 SQLITE_DROP_TEMP_VIEW = 15, // View Name NULL
|
|
|
464 SQLITE_DROP_TRIGGER = 16, // Trigger Name Table Name
|
|
|
465 SQLITE_DROP_VIEW = 17, // View Name NULL
|
|
|
466 SQLITE_INSERT = 18, // Table Name NULL
|
|
|
467 SQLITE_PRAGMA = 19, // Pragma Name 1st arg or NULL
|
|
|
468 SQLITE_READ = 20, // Table Name Column Name
|
|
|
469 SQLITE_SELECT = 21, // NULL NULL
|
|
|
470 SQLITE_TRANSACTION = 22, // Operation NULL
|
|
|
471 SQLITE_UPDATE = 23, // Table Name Column Name
|
|
|
472 SQLITE_ATTACH = 24, // Filename NULL
|
|
|
473 SQLITE_DETACH = 25, // Database Name NULL
|
|
|
474 SQLITE_ALTER_TABLE = 26, // Database Name Table Name
|
|
|
475 SQLITE_REINDEX = 27, // Index Name NULL
|
|
|
476 SQLITE_ANALYZE = 28, // Table Name NULL
|
|
|
477 SQLITE_CREATE_VTABLE = 29, // Table Name Module Name
|
|
|
478 SQLITE_DROP_VTABLE = 30, // Table Name Module Name
|
|
|
479 SQLITE_FUNCTION = 31, // NULL Function Name
|
|
|
480 SQLITE_SAVEPOINT = 32, // Operation Savepoint Name
|
|
|
481 SQLITE_MAX_CODE = SQLITE_SAVEPOINT
|
|
|
482 };
|
|
|
483
|
|
|
484 /// Return codes of the authorizer
|
|
|
485 enum wxAuthorizationResult
|
|
|
486 {
|
|
|
487 SQLITE_OK = 0, // Allow access
|
|
|
488 SQLITE_DENY = 1, // Abort the SQL statement with an error
|
|
|
489 SQLITE_IGNORE = 2 // Don't allow access, but don't generate an error
|
|
|
490 };
|
|
|
491 /// Virtual destructor
|
|
|
492 virtual ~wxSQLite3Authorizer() {}
|
|
|
493 /// Execute the authorizer function
|
|
|
494 /**
|
|
|
495 * Please refer to the SQLite documentation for further information about the
|
|
|
496 * meaning of the parameters.
|
|
|
497 *
|
|
|
498 * \param type wxAuthorizationCode. The value signifies what kind of operation is to be authorized.
|
|
|
499 * \param arg1 first argument (value depends on "type")
|
|
|
500 * \param arg2 second argument (value depends on "type")
|
|
|
501 * \param arg3 third argument (name of database if applicable)
|
|
|
502 * \param arg4 fourth argument (name of trigger or view if applicable)
|
|
|
503 * \return a wxAuthorizationResult, i.e. SQLITE_OK, SQLITE_DENY or SQLITE_IGNORE
|
|
|
504 */
|
|
|
505 virtual wxAuthorizationResult Authorize(wxAuthorizationCode type,
|
|
|
506 const wxString& arg1, const wxString& arg2,
|
|
|
507 const wxString& arg3, const wxString& arg4) = 0;
|
|
|
508 /// Convert authorization code to string
|
|
|
509 /**
|
|
|
510 * \param type wxAuthorizationCode. The value signifies what kind of operation is to be authorized.
|
|
|
511 */
|
|
|
512 static wxString AuthorizationCodeToString(wxSQLite3Authorizer::wxAuthorizationCode type);
|
|
|
513 };
|
|
|
514
|
|
|
515 class WXDLLIMPEXP_FWD_SQLITE3 wxSQLite3Database;
|
|
|
516
|
|
|
517 /// Interface for a user defined hook function
|
|
|
518 /**
|
|
|
519 */
|
|
|
520 class WXDLLIMPEXP_SQLITE3 wxSQLite3Hook
|
|
|
521 {
|
|
|
522 public:
|
|
|
523 /// Codes identifying the command for which the hook is called
|
|
|
524 enum wxUpdateType
|
|
|
525 {
|
|
|
526 SQLITE_DELETE = 9,
|
|
|
527 SQLITE_INSERT = 18,
|
|
|
528 SQLITE_UPDATE = 23
|
|
|
529 };
|
|
|
530 /// Default constructor
|
|
|
531 wxSQLite3Hook() : m_db(NULL) {}
|
|
|
532
|
|
|
533 /// Virtual destructor
|
|
|
534 virtual ~wxSQLite3Hook() {}
|
|
|
535
|
|
|
536 /// Execute the commit hook callback function
|
|
|
537 /**
|
|
|
538 * Please refer to the SQLite documentation for further information.
|
|
|
539 * \return true to request rollback of the transaction, false to continue with commit
|
|
|
540 */
|
|
|
541 virtual bool CommitCallback() { return false; }
|
|
|
542
|
|
|
543 /// Execute the rollback hook callback function
|
|
|
544 /**
|
|
|
545 * Please refer to the SQLite documentation for further information.
|
|
|
546 */
|
|
|
547 virtual void RollbackCallback() {}
|
|
|
548
|
|
|
549 /// Execute the hook callback function
|
|
|
550 /**
|
|
|
551 * Please refer to the SQLite documentation for further information about the
|
|
|
552 * meaning of the parameters.
|
|
|
553 *
|
|
|
554 * \param type wxHookType. The value signifies what kind of operation is to be authorized.
|
|
|
555 * \param database Name of the database
|
|
|
556 * \param table Name of the table
|
|
|
557 * \param rowid The rowid of the affected row
|
|
|
558 */
|
|
|
559 virtual void UpdateCallback(wxUpdateType WXUNUSED(type),
|
|
|
560 const wxString& WXUNUSED(database), const wxString& WXUNUSED(table),
|
|
|
561 wxLongLong WXUNUSED(rowid)) {}
|
|
|
562
|
|
|
563 /// Execute the write-ahead log hook callback function
|
|
|
564 /**
|
|
|
565 * Please refer to the SQLite documentation for further information about the
|
|
|
566 * meaning of the parameters.
|
|
|
567 *
|
|
|
568 * \param database Name of the database
|
|
|
569 * \param numPages the number of pages
|
|
|
570 */
|
|
|
571 virtual int WriteAheadLogCallback(const wxString& WXUNUSED(database),
|
|
|
572 int WXUNUSED(numPages)) { return 0; }
|
|
|
573
|
|
|
574 /// Set the associated database
|
|
|
575 /**
|
|
|
576 * For the write-ahead log hook the associated database is set internally.
|
|
|
577 * \param db pointer to the associated database instance
|
|
|
578 */
|
|
|
579 void SetDatabase(wxSQLite3Database* db) { m_db = db; }
|
|
|
580
|
|
|
581 /// Get the associated database
|
|
|
582 /**
|
|
|
583 * For the write-ahead log hook the associated database can be accessed.
|
|
|
584 *
|
|
|
585 * \return pointer to the associated database instance
|
|
|
586 * \note Access to the associated database is only provided for write-ahead log hooks.
|
|
|
587 */
|
|
|
588 wxSQLite3Database* GetDatabase() const { return m_db; }
|
|
|
589
|
|
|
590 private:
|
|
|
591 wxSQLite3Database* m_db;
|
|
|
592 };
|
|
|
593
|
|
|
594 /// Interface for a user defined collation sequence
|
|
|
595 /**
|
|
|
596 */
|
|
|
597 class WXDLLIMPEXP_SQLITE3 wxSQLite3Collation
|
|
|
598 {
|
|
|
599 public:
|
|
|
600 /// Virtual destructor
|
|
|
601 virtual ~wxSQLite3Collation() {}
|
|
|
602
|
|
|
603 /// Execute a comparison using a user-defined collation sequence
|
|
|
604 /**
|
|
|
605 * Please refer to the SQLite documentation for further information.
|
|
|
606 * \param text1 first text string
|
|
|
607 * \param text2 second text string
|
|
|
608 * \return an integer < 0, = 0, or > 0 depending on whether text1 is less than, equal to, or greater than text2.
|
|
|
609 */
|
|
|
610 virtual int Compare(const wxString& text1, const wxString& text2) { return text1.Cmp(text2); }
|
|
|
611 };
|
|
|
612
|
|
|
613 /// Result set of a SQL query
|
|
|
614 class WXDLLIMPEXP_SQLITE3 wxSQLite3ResultSet
|
|
|
615 {
|
|
|
616 public:
|
|
|
617 /// Constructor
|
|
|
618 wxSQLite3ResultSet();
|
|
|
619
|
|
|
620 /// Copy constructor
|
|
|
621 wxSQLite3ResultSet(const wxSQLite3ResultSet& resultSet);
|
|
|
622
|
|
|
623 /// Constructor for internal use
|
|
|
624 wxSQLite3ResultSet(void* db, void* stmt,
|
|
|
625 bool eof, bool first = true, bool ownStmt = true);
|
|
|
626
|
|
|
627 /// Assignment constructor
|
|
|
628 wxSQLite3ResultSet& operator=(const wxSQLite3ResultSet& resultSet);
|
|
|
629
|
|
|
630 /// Destructor
|
|
|
631 /**
|
|
|
632 */
|
|
|
633 virtual ~wxSQLite3ResultSet();
|
|
|
634
|
|
|
635 /// Get the number of columns in the result set
|
|
|
636 /**
|
|
|
637 * \return number of columns in result set
|
|
|
638 */
|
|
|
639 int GetColumnCount();
|
|
|
640
|
|
|
641 /// Find the index of a column by name
|
|
|
642 /**
|
|
|
643 * \param columnName name of the column
|
|
|
644 * \return index of the column. Indices start with 0.
|
|
|
645 */
|
|
|
646 int FindColumnIndex(const wxString& columnName);
|
|
|
647
|
|
|
648 /// Get the name of a column
|
|
|
649 /**
|
|
|
650 * \param columnIndex index of the column. Indices start with 0.
|
|
|
651 * \return column name as string
|
|
|
652 */
|
|
|
653 wxString GetColumnName(int columnIndex);
|
|
|
654
|
|
|
655 /// Get the declared type of a column
|
|
|
656 /**
|
|
|
657 * \param columnIndex index of the column. Indices start with 0.
|
|
|
658 * \return type string as specified in the table definition
|
|
|
659 */
|
|
|
660 wxString GetDeclaredColumnType(int columnIndex);
|
|
|
661
|
|
|
662 /// Get the actual type of a column
|
|
|
663 /**
|
|
|
664 * \param columnIndex index of the column. Indices start with 0.
|
|
|
665 * \return column type as one of the values WXSQLITE_INTEGER, WXSQLITE_FLOAT, WXSQLITE_TEXT, WXSQLITE_BLOB, or WXSQLITE_NULL
|
|
|
666 */
|
|
|
667 int GetColumnType(int columnIndex);
|
|
|
668
|
|
|
669 /// Get the database name of a column
|
|
|
670 /**
|
|
|
671 * \param columnIndex index of the column. Indices start with 0.
|
|
|
672 * \return database name the column belongs to or empty string
|
|
|
673 *
|
|
|
674 * This method is only available if WXSQLITE3_HAVE_METADATA is defined and SQLite has been compiled with SQLITE_ENABLE_COLUMN_METADATA defined.
|
|
|
675 */
|
|
|
676 wxString GetDatabaseName(int columnIndex);
|
|
|
677
|
|
|
678 /// Get the table name of a column
|
|
|
679 /**
|
|
|
680 * \param columnIndex index of the column. Indices start with 0.
|
|
|
681 * \return table name the column belongs to or empty string
|
|
|
682 *
|
|
|
683 * This method is only available if WXSQLITE3_HAVE_METADATA is defined and SQLite has been compiled with SQLITE_ENABLE_COLUMN_METADATA defined.
|
|
|
684 */
|
|
|
685 wxString GetTableName(int columnIndex);
|
|
|
686
|
|
|
687 /// Get the origin name of a column
|
|
|
688 /**
|
|
|
689 * \param columnIndex index of the column. Indices start with 0.
|
|
|
690 * \return origin name the column belongs to or empty string
|
|
|
691 *
|
|
|
692 * This method is only available if WXSQLITE3_HAVE_METADATA is defined and SQLite has been compiled with SQLITE_ENABLE_COLUMN_METADATA defined.
|
|
|
693 */
|
|
|
694 wxString GetOriginName(int columnIndex);
|
|
|
695
|
|
|
696 /// Get a column as a string using the column index
|
|
|
697 /**
|
|
|
698 * \param columnIndex index of the column. Indices start with 0.
|
|
|
699 * \return value of the column as string
|
|
|
700 */
|
|
|
701 wxString GetAsString(int columnIndex);
|
|
|
702
|
|
|
703 /// Get a column as a string using the column name
|
|
|
704 /**
|
|
|
705 * \param columnName name of the column
|
|
|
706 * \return value of the column
|
|
|
707 */
|
|
|
708 wxString GetAsString(const wxString& columnName);
|
|
|
709
|
|
|
710 /// Get a column as an integer using the column index
|
|
|
711 /**
|
|
|
712 * \param columnIndex index of the column. Indices start with 0.
|
|
|
713 * \param nullValue value to be returned in case the column is NULL
|
|
|
714 * \return value of the column
|
|
|
715 */
|
|
|
716 int GetInt(int columnIndex, int nullValue = 0);
|
|
|
717
|
|
|
718 /// Get a column as an integer using the column name
|
|
|
719 /**
|
|
|
720 * \param columnName name of the column
|
|
|
721 * \param nullValue value to be returned in case the column is NULL
|
|
|
722 * \return value of the column
|
|
|
723 */
|
|
|
724 int GetInt(const wxString& columnName, int nullValue = 0);
|
|
|
725
|
|
|
726 /// Get a column as a 64-bit integer using the column index
|
|
|
727 /**
|
|
|
728 * \param columnIndex index of the column. Indices start with 0.
|
|
|
729 * \param nullValue value to be returned in case the column is NULL
|
|
|
730 * \return value of the column
|
|
|
731 */
|
|
|
732 wxLongLong GetInt64(int columnIndex, wxLongLong nullValue = 0);
|
|
|
733
|
|
|
734 /// Get a column as a 64-bit integer using the column name
|
|
|
735 /**
|
|
|
736 * \param columnName name of the column
|
|
|
737 * \param nullValue value to be returned in case the column is NULL
|
|
|
738 * \return value of the column
|
|
|
739 */
|
|
|
740 wxLongLong GetInt64(const wxString& columnName, wxLongLong nullValue = 0);
|
|
|
741
|
|
|
742 /// Get a column as a double using the column index
|
|
|
743 /**
|
|
|
744 * \param columnIndex index of the column. Indices start with 0.
|
|
|
745 * \param nullValue value to be returned in case the column is NULL
|
|
|
746 * \return value of the column
|
|
|
747 */
|
|
|
748 double GetDouble(int columnIndex, double nullValue = 0.0);
|
|
|
749
|
|
|
750 /// Get a column as a double using the column name
|
|
|
751 /**
|
|
|
752 * \param columnName name of the column
|
|
|
753 * \param nullValue value to be returned in case the column is NULL
|
|
|
754 * \return value of the column
|
|
|
755 */
|
|
|
756 double GetDouble(const wxString& columnName, double nullValue = 0.0);
|
|
|
757
|
|
|
758 /// Get a column as a string using the column index
|
|
|
759 /**
|
|
|
760 * \param columnIndex index of the column. Indices start with 0.
|
|
|
761 * \param nullValue value to be returned in case the column is NULL
|
|
|
762 * \return value of the column
|
|
|
763 */
|
|
|
764 wxString GetString(int columnIndex, const wxString& nullValue = wxEmptyString);
|
|
|
765
|
|
|
766 /// Get a column as a string using the column name
|
|
|
767 /**
|
|
|
768 * \param columnName name of the column
|
|
|
769 * \param nullValue value to be returned in case the column is NULL
|
|
|
770 * \return value of the column
|
|
|
771 */
|
|
|
772 wxString GetString(const wxString& columnName, const wxString& nullValue = wxEmptyString);
|
|
|
773
|
|
|
774 /// Get a column as a BLOB using the column index
|
|
|
775 /**
|
|
|
776 * \param columnIndex index of the column. Indices start with 0.
|
|
|
777 * \param[out] len length of the blob in bytes
|
|
|
778 * \return value of the column
|
|
|
779 */
|
|
|
780 const unsigned char* GetBlob(int columnIndex, int& len);
|
|
|
781
|
|
|
782 /// Get a column as a BLOB using the column name
|
|
|
783 /**
|
|
|
784 * \param columnName name of the column
|
|
|
785 * \param[out] len length of the blob in bytes
|
|
|
786 * \return value of the column
|
|
|
787 */
|
|
|
788 const unsigned char* GetBlob(const wxString& columnName, int& len);
|
|
|
789
|
|
|
790 /// Get a column as a BLOB using the column index and append to memory buffer
|
|
|
791 /**
|
|
|
792 * \param columnIndex index of the column. Indices start with 0.
|
|
|
793 * \param[out] buffer the memory buffer to which the BLOB value is appended
|
|
|
794 * \return reference to the memory buffer
|
|
|
795 */
|
|
|
796 wxMemoryBuffer& GetBlob(int columnIndex, wxMemoryBuffer& buffer);
|
|
|
797
|
|
|
798 /// Get a column as a BLOB using the column index and append to memory buffer
|
|
|
799 /**
|
|
|
800 * \param columnName name of the column
|
|
|
801 * \param[out] buffer the memory buffer to which the BLOB value is appended
|
|
|
802 * \return reference to the memory buffer
|
|
|
803 */
|
|
|
804 wxMemoryBuffer& GetBlob(const wxString& columnName, wxMemoryBuffer& buffer);
|
|
|
805
|
|
|
806 /// Get a column as a date value using the column index
|
|
|
807 /**
|
|
|
808 * \param columnIndex index of the column. Indices start with 0.
|
|
|
809 * \return value of the column
|
|
|
810 */
|
|
|
811 wxDateTime GetDate(int columnIndex);
|
|
|
812
|
|
|
813 /// Get a column as a date value using the column name
|
|
|
814 /**
|
|
|
815 * \param columnName name of the column
|
|
|
816 * \return value of the column
|
|
|
817 */
|
|
|
818 wxDateTime GetDate(const wxString& columnName);
|
|
|
819
|
|
|
820 /// Get a column as a time value using the column index
|
|
|
821 /**
|
|
|
822 * \param columnIndex index of the column. Indices start with 0.
|
|
|
823 * \return value of the column
|
|
|
824 */
|
|
|
825 wxDateTime GetTime(int columnIndex);
|
|
|
826
|
|
|
827 /// Get a column as a time value using the column name
|
|
|
828 /**
|
|
|
829 * \param columnName name of the column
|
|
|
830 * \return value of the column
|
|
|
831 */
|
|
|
832 wxDateTime GetTime(const wxString& columnName);
|
|
|
833
|
|
|
834 /// Get a column as a date and time value using the column index
|
|
|
835 /**
|
|
|
836 * \param columnIndex index of the column. Indices start with 0.
|
|
|
837 * \return value of the column
|
|
|
838 */
|
|
|
839 wxDateTime GetDateTime(int columnIndex);
|
|
|
840
|
|
|
841 /// Get a column as a date and time value using the column name
|
|
|
842 /**
|
|
|
843 * \param columnName name of the column
|
|
|
844 * \return value of the column
|
|
|
845 */
|
|
|
846 wxDateTime GetDateTime(const wxString& columnName);
|
|
|
847
|
|
|
848 /// Get a column as a timestamp value using the column index
|
|
|
849 /**
|
|
|
850 * \param columnIndex index of the column. Indices start with 0.
|
|
|
851 * \return value of the column
|
|
|
852 */
|
|
|
853 wxDateTime GetTimestamp(int columnIndex);
|
|
|
854
|
|
|
855 /// Get a column as a timestamp value using the column name
|
|
|
856 /**
|
|
|
857 * \param columnName name of the column
|
|
|
858 * \return value of the column
|
|
|
859 */
|
|
|
860 wxDateTime GetTimestamp(const wxString& columnName);
|
|
|
861
|
|
|
862 /// Get a column as a date and time value using the column index
|
|
|
863 /**
|
|
|
864 * The date/time value is expected to be stored in the database as a numeric value (i.e. int64).
|
|
|
865 *
|
|
|
866 * \param columnIndex index of the column. Indices start with 0.
|
|
|
867 * \return value of the column
|
|
|
868 */
|
|
|
869 wxDateTime GetNumericDateTime(int columnIndex);
|
|
|
870
|
|
|
871 /// Get a column as a date and time value using the column name
|
|
|
872 /**
|
|
|
873 * The date/time value is expected to be stored in the database as a numeric value (i.e. int64).
|
|
|
874 *
|
|
|
875 * \param columnName name of the column
|
|
|
876 * \return value of the column
|
|
|
877 */
|
|
|
878 wxDateTime GetNumericDateTime(const wxString& columnName);
|
|
|
879
|
|
|
880 /// Get a column as a date and time value using the column index
|
|
|
881 /**
|
|
|
882 * The date/time value is expected to be stored in the database as a Julian Day Number (i.e. double).
|
|
|
883 *
|
|
|
884 * \param columnIndex index of the column. Indices start with 0.
|
|
|
885 * \return value of the column
|
|
|
886 */
|
|
|
887 wxDateTime GetJulianDayNumber(int columnIndex);
|
|
|
888
|
|
|
889 /// Get a column as a date and time value using the column name
|
|
|
890 /**
|
|
|
891 * The date/time value is expected to be stored in the database as a Julian Day Number (i.e. double).
|
|
|
892 *
|
|
|
893 * \param columnName name of the column
|
|
|
894 * \return value of the column
|
|
|
895 */
|
|
|
896 wxDateTime GetJulianDayNumber(const wxString& columnName);
|
|
|
897
|
|
|
898 /// Get a column as a boolean value using the column index
|
|
|
899 /**
|
|
|
900 * \param columnIndex index of the column. Indices start with 0.
|
|
|
901 * \return value of the column
|
|
|
902 */
|
|
|
903 bool GetBool(int columnIndex);
|
|
|
904
|
|
|
905 /// Get a column as a boolean value using the column name
|
|
|
906 /**
|
|
|
907 * \param columnName name of the column
|
|
|
908 * \return value of the column
|
|
|
909 */
|
|
|
910 bool GetBool(const wxString& columnName);
|
|
|
911
|
|
|
912 /// Check whether a column has a NULL value using the column index
|
|
|
913 /**
|
|
|
914 * \param columnIndex index of the column. Indices start with 0.
|
|
|
915 * \return TRUE if the value is NULL, FALSE otherwise
|
|
|
916 */
|
|
|
917 bool IsNull(int columnIndex);
|
|
|
918
|
|
|
919 /// Check whether a column has a NULL value using the column name
|
|
|
920 /**
|
|
|
921 * \param columnName name of the column
|
|
|
922 * \return TRUE if the value is NULL, FALSE otherwise
|
|
|
923 */
|
|
|
924 bool IsNull(const wxString& columnName);
|
|
|
925
|
|
|
926 /// Check whether all rows of the result set have been processed
|
|
|
927 /**
|
|
|
928 * \return TRUE if all rows of the result have been processed, FALSE otherwise
|
|
|
929 */
|
|
|
930 bool Eof();
|
|
|
931
|
|
|
932 /// Retrieve next row of the result set
|
|
|
933 /**
|
|
|
934 * Advances the cursor to the next row.
|
|
|
935 * On creation of the result set the cursor is positioned BEFORE the first row, i.e.
|
|
|
936 * the first call to this method makes the first row available for processing.
|
|
|
937 * \return TRUE while there are still rows to process, FALSE otherwise
|
|
|
938 */
|
|
|
939 bool NextRow();
|
|
|
940
|
|
|
941 /// Finalize the result set
|
|
|
942 /**
|
|
|
943 */
|
|
|
944 void Finalize();
|
|
|
945
|
|
|
946 /// Get the original SQL string for preparing the query statement
|
|
|
947 /**
|
|
|
948 * \return the original SQL string used to prepare the query statement
|
|
|
949 */
|
|
|
950 wxString GetSQL();
|
|
|
951
|
|
|
952 /// Validate associated SQLite database and statement
|
|
|
953 /**
|
|
|
954 * \return TRUE if both, a SQLite database and a SQLite statement, are associated, FALSE otherwise
|
|
|
955 */
|
|
|
956 bool IsOk();
|
|
|
957
|
|
|
958 private:
|
|
|
959 /// Check the validity of the associated statement
|
|
|
960 void CheckStmt();
|
|
|
961
|
|
|
962 void* m_db; ///< associated database
|
|
|
963 void* m_stmt; ///< associated statement
|
|
|
964 bool m_eof; ///< Flag for end of result set
|
|
|
965 bool m_first; ///< Flag for first row of the result set
|
|
|
966 int m_cols; ///< Numver of columns in row set
|
|
|
967 bool m_ownStmt; ///< Flag for ownership of the associated statement
|
|
|
968 };
|
|
|
969
|
|
|
970
|
|
|
971 /// Holds the complete result set of a SQL query
|
|
|
972 class WXDLLIMPEXP_SQLITE3 wxSQLite3Table
|
|
|
973 {
|
|
|
974 public:
|
|
|
975 /// Constructor
|
|
|
976 wxSQLite3Table();
|
|
|
977
|
|
|
978 wxSQLite3Table(const wxSQLite3Table& table);
|
|
|
979
|
|
|
980 wxSQLite3Table(char** results, int rows, int cols);
|
|
|
981
|
|
|
982 virtual ~wxSQLite3Table();
|
|
|
983
|
|
|
984 wxSQLite3Table& operator=(const wxSQLite3Table& table);
|
|
|
985
|
|
|
986 /// Get the number of columns in the result set
|
|
|
987 /**
|
|
|
988 * \return the number of columns
|
|
|
989 */
|
|
|
990 int GetColumnCount();
|
|
|
991
|
|
|
992 /// Get the number of rows in the result set
|
|
|
993 /**
|
|
|
994 * \return the number of rows
|
|
|
995 */
|
|
|
996 int GetRowCount();
|
|
|
997
|
|
|
998 /// Find the index of a column by name
|
|
|
999 /**
|
|
|
1000 * \param columnName name of the column
|
|
|
1001 * \return the index of the column
|
|
|
1002 */
|
|
|
1003 int FindColumnIndex(const wxString& columnName);
|
|
|
1004
|
|
|
1005 /// Get the name of a column
|
|
|
1006 /**
|
|
|
1007 * \param columnIndex index of the column. Indices start with 0.
|
|
|
1008 * \return name of the column
|
|
|
1009 */
|
|
|
1010 wxString GetColumnName(int columnIndex);
|
|
|
1011
|
|
|
1012 /// Get a column as a string using the column index
|
|
|
1013 /**
|
|
|
1014 * \param columnIndex index of the column. Indices start with 0.
|
|
|
1015 * \return value of the column as a string
|
|
|
1016 *
|
|
|
1017 * \note This method returns values of type <code>double</code>
|
|
|
1018 * always using the point character as the decimal separator.
|
|
|
1019 * This is SQLite default behaviour. Use method wxSQLite3Table::GetDouble
|
|
|
1020 * to apply correct conversion from <code>string</code> to <code>double</code>.
|
|
|
1021 */
|
|
|
1022 wxString GetAsString(int columnIndex);
|
|
|
1023
|
|
|
1024 /// Get a column as a string using the column name
|
|
|
1025 /**
|
|
|
1026 * \param columnName name of the column
|
|
|
1027 * \return value of the column as a string
|
|
|
1028 *
|
|
|
1029 * \note This method returns values of type <code>double</code>
|
|
|
1030 * always using the point character as the decimal separator.
|
|
|
1031 * This is SQLite default behaviour. Use method wxSQLite3Table::GetDouble
|
|
|
1032 * to apply correct conversion from <code>string</code> to <code>double</code>.
|
|
|
1033 */
|
|
|
1034 wxString GetAsString(const wxString& columnName);
|
|
|
1035
|
|
|
1036 /// Get a column as an integer using the column index
|
|
|
1037 /**
|
|
|
1038 * \param columnIndex index of the column. Indices start with 0.
|
|
|
1039 * \param nullValue value to be returned in case the column is NULL
|
|
|
1040 * \return value of the column
|
|
|
1041 */
|
|
|
1042 int GetInt(int columnIndex, int nullValue = 0);
|
|
|
1043
|
|
|
1044 /// Get a column as an integer using the column name
|
|
|
1045 /**
|
|
|
1046 * \param columnName name of the column
|
|
|
1047 * \param nullValue value to be returned in case the column is NULL
|
|
|
1048 * \return value of the column
|
|
|
1049 */
|
|
|
1050 int GetInt(const wxString& columnName, int nullValue = 0);
|
|
|
1051
|
|
|
1052 /// Get a column as a 64-bit integer using the column index
|
|
|
1053 /**
|
|
|
1054 * \param columnIndex index of the column. Indices start with 0.
|
|
|
1055 * \param nullValue value to be returned in case the column is NULL
|
|
|
1056 * \return value of the column
|
|
|
1057 */
|
|
|
1058 wxLongLong GetInt64(int columnIndex, wxLongLong nullValue = 0);
|
|
|
1059
|
|
|
1060 /// Get a column as an integer using the column name
|
|
|
1061 /**
|
|
|
1062 * \param columnName name of the column
|
|
|
1063 * \param nullValue value to be returned in case the column is NULL
|
|
|
1064 * \return value of the column
|
|
|
1065 */
|
|
|
1066 wxLongLong GetInt64(const wxString& columnName, wxLongLong nullValue = 0);
|
|
|
1067
|
|
|
1068 /// Get a column as a double using the column index
|
|
|
1069 /**
|
|
|
1070 * \param columnIndex index of the column. Indices start with 0.
|
|
|
1071 * \param nullValue value to be returned in case the column is NULL
|
|
|
1072 * \return value of the column
|
|
|
1073 */
|
|
|
1074 double GetDouble(int columnIndex, double nullValue = 0.0);
|
|
|
1075
|
|
|
1076 /// Get a column as a double using the column name
|
|
|
1077 /**
|
|
|
1078 * \param columnName name of the column
|
|
|
1079 * \param nullValue value to be returned in case the column is NULL
|
|
|
1080 * \return value of the column
|
|
|
1081 */
|
|
|
1082 double GetDouble(const wxString& columnName, double nullValue = 0.0);
|
|
|
1083
|
|
|
1084 /// Get a column as a string using the column index
|
|
|
1085 /**
|
|
|
1086 * \param columnIndex index of the column. Indices start with 0.
|
|
|
1087 * \param nullValue value to be returned in case the column is NULL
|
|
|
1088 * \return value of the column
|
|
|
1089 */
|
|
|
1090 wxString GetString(int columnIndex, const wxString& nullValue = wxEmptyString);
|
|
|
1091
|
|
|
1092 /// Get a column as a string using the column name
|
|
|
1093 /**
|
|
|
1094 * \param columnName name of the column
|
|
|
1095 * \param nullValue value to be returned in case the column is NULL
|
|
|
1096 * \return value of the column
|
|
|
1097 */
|
|
|
1098 wxString GetString(const wxString& columnName, const wxString& nullValue = wxEmptyString);
|
|
|
1099
|
|
|
1100 /// Get a column as a date value using the column index
|
|
|
1101 /**
|
|
|
1102 * \param columnIndex index of the column. Indices start with 0.
|
|
|
1103 * \return value of the column
|
|
|
1104 */
|
|
|
1105 wxDateTime GetDate(int columnIndex);
|
|
|
1106
|
|
|
1107 /// Get a column as a date value using the column name
|
|
|
1108 /**
|
|
|
1109 * \param columnName name of the column
|
|
|
1110 * \return value of the column
|
|
|
1111 */
|
|
|
1112 wxDateTime GetDate(const wxString& columnName);
|
|
|
1113
|
|
|
1114 /// Get a column as a time value using the column index
|
|
|
1115 /**
|
|
|
1116 * \param columnIndex index of the column. Indices start with 0.
|
|
|
1117 * \return value of the column
|
|
|
1118 */
|
|
|
1119 wxDateTime GetTime(int columnIndex);
|
|
|
1120
|
|
|
1121 /// Get a column as a time value using the column name
|
|
|
1122 /**
|
|
|
1123 * \param columnName name of the column
|
|
|
1124 * \return value of the column
|
|
|
1125 */
|
|
|
1126 wxDateTime GetTime(const wxString& columnName);
|
|
|
1127
|
|
|
1128 /// Get a column as a date/time value using the column index
|
|
|
1129 /**
|
|
|
1130 * \param columnIndex index of the column. Indices start with 0.
|
|
|
1131 * \return value of the column
|
|
|
1132 */
|
|
|
1133 wxDateTime GetDateTime(int columnIndex);
|
|
|
1134
|
|
|
1135 /// Get a column as a date/time value using the column name
|
|
|
1136 /**
|
|
|
1137 * \param columnName name of the column
|
|
|
1138 * \return value of the column
|
|
|
1139 */
|
|
|
1140 wxDateTime GetDateTime(const wxString& columnName);
|
|
|
1141
|
|
|
1142 /// Get a column as a boolean using the column index
|
|
|
1143 /**
|
|
|
1144 * \param columnIndex index of the column. Indices start with 0.
|
|
|
1145 * \return value of the column
|
|
|
1146 */
|
|
|
1147 bool GetBool(int columnIndex);
|
|
|
1148
|
|
|
1149 /// Get a column as a boolean using the column name
|
|
|
1150 /**
|
|
|
1151 * \param columnName name of the column
|
|
|
1152 * \return value of the column
|
|
|
1153 */
|
|
|
1154 bool GetBool(const wxString& columnName);
|
|
|
1155
|
|
|
1156 /// Check whether the column selected by index is a NULL value
|
|
|
1157 /**
|
|
|
1158 * \param columnIndex index of the column. Indices start with 0.
|
|
|
1159 * \return TRUE if the value is NULL, FALSE otherwise
|
|
|
1160 */
|
|
|
1161 bool IsNull(int columnIndex);
|
|
|
1162
|
|
|
1163 /// Check whether the column selected by name is a NULL value
|
|
|
1164 /**
|
|
|
1165 * \param columnName name of the column
|
|
|
1166 * \return TRUE if the value is NULL, FALSE otherwise
|
|
|
1167 */
|
|
|
1168 bool IsNull(const wxString& columnName);
|
|
|
1169
|
|
|
1170 /// Set the current row
|
|
|
1171 /**
|
|
|
1172 * \param row index of the requested row. Indices start with 0.
|
|
|
1173 */
|
|
|
1174 void SetRow(int row);
|
|
|
1175
|
|
|
1176 /// Finalize the result set
|
|
|
1177 /**
|
|
|
1178 */
|
|
|
1179 void Finalize();
|
|
|
1180
|
|
|
1181 /// Validate associated SQLite resultset
|
|
|
1182 /**
|
|
|
1183 * \return TRUE if SQLite resultset is associated, FALSE otherwise
|
|
|
1184 */
|
|
|
1185 bool IsOk();
|
|
|
1186
|
|
|
1187 private:
|
|
|
1188 /// Check for valid results
|
|
|
1189 void CheckResults();
|
|
|
1190
|
|
|
1191 int m_cols; ///< Number of columns
|
|
|
1192 int m_rows; ///< Number of rows
|
|
|
1193 int m_currentRow; ///< Index of the current row
|
|
|
1194 char** m_results; ///< SQLite3 result buffer
|
|
|
1195 };
|
|
|
1196
|
|
|
1197
|
|
|
1198 /// Represents a prepared SQL statement
|
|
|
1199 class WXDLLIMPEXP_SQLITE3 wxSQLite3Statement
|
|
|
1200 {
|
|
|
1201 public:
|
|
|
1202 /// Constructor
|
|
|
1203 /**
|
|
|
1204 */
|
|
|
1205 wxSQLite3Statement();
|
|
|
1206
|
|
|
1207 /// Copy constructor
|
|
|
1208 /**
|
|
|
1209 */
|
|
|
1210 wxSQLite3Statement(const wxSQLite3Statement& statement);
|
|
|
1211
|
|
|
1212 /// Assignement constructor
|
|
|
1213 /**
|
|
|
1214 */
|
|
|
1215 wxSQLite3Statement& operator=(const wxSQLite3Statement& statement);
|
|
|
1216
|
|
|
1217 /// Constructor (internal use only)
|
|
|
1218 /**
|
|
|
1219 */
|
|
|
1220 wxSQLite3Statement(void* db, void* stmt);
|
|
|
1221
|
|
|
1222 /// Destructor
|
|
|
1223 /**
|
|
|
1224 */
|
|
|
1225 virtual ~wxSQLite3Statement();
|
|
|
1226
|
|
|
1227 /// Execute the database update represented by this statement
|
|
|
1228 /**
|
|
|
1229 * \return the number of database rows that were changed (or inserted or deleted)
|
|
|
1230 */
|
|
|
1231 int ExecuteUpdate();
|
|
|
1232
|
|
|
1233 /// Execute the query represented by this statement
|
|
|
1234 /**
|
|
|
1235 * \param transferStatementOwnership if TRUE the ownership of the underlying SQLite
|
|
|
1236 * statement object is transferred to the created result set (default: FALSE)
|
|
|
1237 * \return result set instance
|
|
|
1238 * \note the transfer of ownership of the underlying SQLite statement object can be
|
|
|
1239 * performed only once. If the transfer of ownership has been requested this
|
|
|
1240 * wxSQL3Statement instance isn't usable anymore as soon as the result set is destroyed.
|
|
|
1241 * If the transfer of ownership isn't requested the created result set can be used to
|
|
|
1242 * retrieve the selected data rows only as long as this wxSQLite3Statement instance exists.
|
|
|
1243 */
|
|
|
1244 wxSQLite3ResultSet ExecuteQuery(bool transferStatementOwnership = false);
|
|
|
1245
|
|
|
1246 /// Get the number of statement parameters
|
|
|
1247 /**
|
|
|
1248 * \return the number of parameters in the prepared statement
|
|
|
1249 */
|
|
|
1250 int GetParamCount();
|
|
|
1251
|
|
|
1252 /// Get the index of a parameter with a given name
|
|
|
1253 /**
|
|
|
1254 * \param paramName
|
|
|
1255 * \return the index of the parameter with the given name. The name must match exactly.
|
|
|
1256 * If there is no parameter with the given name, return 0.
|
|
|
1257 */
|
|
|
1258 int GetParamIndex(const wxString& paramName);
|
|
|
1259
|
|
|
1260 /// Get the name of a paramater at the given position
|
|
|
1261 /**
|
|
|
1262 * \param paramIndex index of the parameter. The first parameter has an index of 1.
|
|
|
1263 * \return the name of the paramIndex-th parameter in the precompiled statement.
|
|
|
1264 * Parameters of the form ":AAA" or "$VVV" have a name which is the string ":AAA" or "$VVV".
|
|
|
1265 * Parameters of the form "?" have no name.
|
|
|
1266 */
|
|
|
1267 wxString GetParamName(int paramIndex);
|
|
|
1268
|
|
|
1269 /// Bind parameter to a string value
|
|
|
1270 /**
|
|
|
1271 * \param paramIndex index of the parameter. The first parameter has an index of 1.
|
|
|
1272 * \param stringValue value of the parameter
|
|
|
1273 */
|
|
|
1274 void Bind(int paramIndex, const wxString& stringValue);
|
|
|
1275
|
|
|
1276 /// Bind parameter to a integer value
|
|
|
1277 /**
|
|
|
1278 * \param paramIndex index of the parameter. The first parameter has an index of 1.
|
|
|
1279 * \param intValue value of the parameter
|
|
|
1280 */
|
|
|
1281 void Bind(int paramIndex, int intValue);
|
|
|
1282
|
|
|
1283 /// Bind parameter to a 64-bit integer value
|
|
|
1284 /**
|
|
|
1285 * \param paramIndex index of the parameter. The first parameter has an index of 1.
|
|
|
1286 * \param int64Value value of the parameter
|
|
|
1287 */
|
|
|
1288 void Bind(int paramIndex, wxLongLong int64Value);
|
|
|
1289
|
|
|
1290 /// Bind parameter to a double value
|
|
|
1291 /**
|
|
|
1292 * \param paramIndex index of the parameter. The first parameter has an index of 1.
|
|
|
1293 * \param doubleValue value of the parameter
|
|
|
1294 */
|
|
|
1295 void Bind(int paramIndex, double doubleValue);
|
|
|
1296
|
|
|
1297 /// Bind parameter to a utf-8 character string value
|
|
|
1298 /**
|
|
|
1299 * \param paramIndex index of the parameter. The first parameter has an index of 1.
|
|
|
1300 * \param charValue value of the parameter
|
|
|
1301 */
|
|
|
1302 void Bind(int paramIndex, const char* charValue);
|
|
|
1303
|
|
|
1304 /// Bind parameter to a BLOB value
|
|
|
1305 /**
|
|
|
1306 * \param paramIndex index of the parameter. The first parameter has an index of 1.
|
|
|
1307 * \param blobValue value of the parameter
|
|
|
1308 * \param blobLen length of the blob in bytes
|
|
|
1309 */
|
|
|
1310 void Bind(int paramIndex, const unsigned char* blobValue, int blobLen);
|
|
|
1311
|
|
|
1312 /// Bind parameter to a BLOB value
|
|
|
1313 /**
|
|
|
1314 * \param paramIndex index of the parameter. The first parameter has an index of 1.
|
|
|
1315 * \param blobValue value of the parameter
|
|
|
1316 */
|
|
|
1317 void Bind(int paramIndex, const wxMemoryBuffer& blobValue);
|
|
|
1318
|
|
|
1319 /// Bind parameter to a date value
|
|
|
1320 /**
|
|
|
1321 * \param paramIndex index of the parameter. The first parameter has an index of 1.
|
|
|
1322 * \param date value of the parameter
|
|
|
1323 */
|
|
|
1324 void BindDate(int paramIndex, const wxDateTime& date);
|
|
|
1325
|
|
|
1326 /// Bind parameter to a time value
|
|
|
1327 /**
|
|
|
1328 * \param paramIndex index of the parameter. The first parameter has an index of 1.
|
|
|
1329 * \param time value of the parameter
|
|
|
1330 */
|
|
|
1331 void BindTime(int paramIndex, const wxDateTime& time);
|
|
|
1332
|
|
|
1333 /// Bind parameter to a date and time value
|
|
|
1334 /**
|
|
|
1335 * \param paramIndex index of the parameter. The first parameter has an index of 1.
|
|
|
1336 * \param datetime value of the parameter
|
|
|
1337 */
|
|
|
1338 void BindDateTime(int paramIndex, const wxDateTime& datetime);
|
|
|
1339
|
|
|
1340 /// Bind parameter to a timestamp value
|
|
|
1341 /**
|
|
|
1342 * \param paramIndex index of the parameter. The first parameter has an index of 1.
|
|
|
1343 * \param timestamp value of the parameter
|
|
|
1344 */
|
|
|
1345 void BindTimestamp(int paramIndex, const wxDateTime& timestamp);
|
|
|
1346
|
|
|
1347 /// Bind parameter to a date and time value
|
|
|
1348 /**
|
|
|
1349 * The date/time value is transferred to the database as a numeric value (i.e. int64).
|
|
|
1350 *
|
|
|
1351 * \param paramIndex index of the parameter. The first parameter has an index of 1.
|
|
|
1352 * \param datetime value of the parameter
|
|
|
1353 */
|
|
|
1354 void BindNumericDateTime(int paramIndex, const wxDateTime& datetime);
|
|
|
1355
|
|
|
1356 /// Bind parameter to a date and time value
|
|
|
1357 /**
|
|
|
1358 * The date/time value is transferred to the database as a Julian Day Number value (i.e. double).
|
|
|
1359 *
|
|
|
1360 * \param paramIndex index of the parameter. The first parameter has an index of 1.
|
|
|
1361 * \param datetime value of the parameter
|
|
|
1362 */
|
|
|
1363 void BindJulianDayNumber(int paramIndex, const wxDateTime& datetime);
|
|
|
1364
|
|
|
1365 /// Bind parameter to a boolean value
|
|
|
1366 /**
|
|
|
1367 * \param paramIndex index of the parameter. The first parameter has an index of 1.
|
|
|
1368 * \param value value of the parameter
|
|
|
1369 */
|
|
|
1370 void BindBool(int paramIndex, bool value);
|
|
|
1371
|
|
|
1372 /// Bind parameter to a NULL value
|
|
|
1373 /**
|
|
|
1374 * \param paramIndex index of the parameter. The first parameter has an index of 1.
|
|
|
1375 */
|
|
|
1376 void BindNull(int paramIndex);
|
|
|
1377
|
|
|
1378 /// Bind parameter to a Zero BLOB value
|
|
|
1379 /**
|
|
|
1380 * Space for a BLOB is reserved and filled with binary zeros for later reference
|
|
|
1381 * through a BLOB handle.
|
|
|
1382 *
|
|
|
1383 * \param paramIndex index of the parameter. The first parameter has an index of 1.
|
|
|
1384 * \param blobSize size of the BLOB
|
|
|
1385 */
|
|
|
1386 void BindZeroBlob(int paramIndex, int blobSize);
|
|
|
1387
|
|
|
1388 /// Clear all parameter bindings
|
|
|
1389 /**
|
|
|
1390 * Sets all the parameters in the prepared SQL statement back to NULL.
|
|
|
1391 */
|
|
|
1392 void ClearBindings();
|
|
|
1393
|
|
|
1394 /// Get the original SQL string for the prepared statement
|
|
|
1395 /**
|
|
|
1396 * \return the original SQL string used to prepare the statement
|
|
|
1397 */
|
|
|
1398 wxString GetSQL();
|
|
|
1399
|
|
|
1400 /// Reset the prepared statement
|
|
|
1401 /**
|
|
|
1402 * Resets the statement back to it's initial state, ready to be re-executed.
|
|
|
1403 * Any SQL statement variables that had values bound to them retain their values.
|
|
|
1404 */
|
|
|
1405 void Reset();
|
|
|
1406
|
|
|
1407 /// Determine whether the statement is read-only
|
|
|
1408 /**
|
|
|
1409 * \return TRUE if the statement is read-only, FALSE otherwise
|
|
|
1410 * \since SQLite3 version 3.7.4
|
|
|
1411 * \note For SQLite3 version before version 3.7.4 this method returns always FALSE.
|
|
|
1412 */
|
|
|
1413 bool IsReadOnly();
|
|
|
1414
|
|
|
1415 /// Finalize the prepared statement
|
|
|
1416 /**
|
|
|
1417 */
|
|
|
1418 void Finalize();
|
|
|
1419
|
|
|
1420 /// Validate associated SQLite database and statement
|
|
|
1421 /**
|
|
|
1422 * \return TRUE if both, a SQLite database and a SQLite statement, are associated, FALSE otherwise
|
|
|
1423 */
|
|
|
1424 bool IsOk();
|
|
|
1425
|
|
|
1426 private:
|
|
|
1427 /// Check for valid database connection
|
|
|
1428 void CheckDatabase();
|
|
|
1429
|
|
|
1430 /// Check for valid statement
|
|
|
1431 void CheckStmt();
|
|
|
1432
|
|
|
1433 void* m_db; ///< associated SQLite3 database
|
|
|
1434 void* m_stmt; ///< associated SQLite3 statement
|
|
|
1435 bool m_hasOwnership; ///< flag whether the associated SQLite3 statement is owned
|
|
|
1436 };
|
|
|
1437
|
|
|
1438
|
|
|
1439 /// Represents a SQLite BLOB handle
|
|
|
1440 class WXDLLIMPEXP_SQLITE3 wxSQLite3Blob
|
|
|
1441 {
|
|
|
1442 public:
|
|
|
1443 /// Constructor
|
|
|
1444 /**
|
|
|
1445 */
|
|
|
1446 wxSQLite3Blob();
|
|
|
1447
|
|
|
1448 /// Copy constructor
|
|
|
1449 /**
|
|
|
1450 */
|
|
|
1451 wxSQLite3Blob(const wxSQLite3Blob& blob);
|
|
|
1452
|
|
|
1453 /// Assignement constructor
|
|
|
1454 /**
|
|
|
1455 */
|
|
|
1456 wxSQLite3Blob& operator=(const wxSQLite3Blob& blob);
|
|
|
1457
|
|
|
1458 /// Constructor (internal use only)
|
|
|
1459 /**
|
|
|
1460 */
|
|
|
1461 wxSQLite3Blob(void* m_db, void* blobHandle, bool writable);
|
|
|
1462
|
|
|
1463 /// Destructor
|
|
|
1464 /**
|
|
|
1465 */
|
|
|
1466 virtual ~wxSQLite3Blob();
|
|
|
1467
|
|
|
1468 /// Read partial BLOB value
|
|
|
1469 /**
|
|
|
1470 * \param blobValue memory buffer receiving the partial content of the BLOB
|
|
|
1471 * \param length length of BLOB content to be read
|
|
|
1472 * \param offset offset within BLOB where the read starts
|
|
|
1473 * \return the address of the memory buffer
|
|
|
1474 */
|
|
|
1475 wxMemoryBuffer& Read(wxMemoryBuffer& blobValue, int length, int offset);
|
|
|
1476
|
|
|
1477 /// Write partial BLOB value
|
|
|
1478 /**
|
|
|
1479 * \param blobValue memory buffer receiving the partial content of the BLOB
|
|
|
1480 * \param offset offset within BLOB where the read starts
|
|
|
1481 */
|
|
|
1482 void Write(const wxMemoryBuffer& blobValue, int offset);
|
|
|
1483
|
|
|
1484 /// Check whether the BLOB handle is correctly initialized
|
|
|
1485 /**
|
|
|
1486 * \return TRUE if the BLOB handle is correctly initialized, FALSE otherweis
|
|
|
1487 */
|
|
|
1488 bool IsOk();
|
|
|
1489
|
|
|
1490 /// Check whether the BLOB handle is read only
|
|
|
1491 /**
|
|
|
1492 * \return TRUE if the BLOB handle is readonly, FALSE otherweis
|
|
|
1493 */
|
|
|
1494 bool IsReadOnly();
|
|
|
1495
|
|
|
1496 /// Get the size of the associated BLOB
|
|
|
1497 /**
|
|
|
1498 * \return the BLOB size
|
|
|
1499 */
|
|
|
1500 int GetSize();
|
|
|
1501
|
|
|
1502 /// Rebind the associated BLOB to a new row
|
|
|
1503 /**
|
|
|
1504 * Please refer to the SQLite documentation for further information
|
|
|
1505 * (see function sqlite3_blob_reopen)
|
|
|
1506 * \param rowid id of the row to which the BLOB should be rebound
|
|
|
1507 * \since SQLite3 version 3.7.4
|
|
|
1508 */
|
|
|
1509 void Rebind(wxLongLong rowid);
|
|
|
1510
|
|
|
1511 /// Finalize the BLOB
|
|
|
1512 /**
|
|
|
1513 */
|
|
|
1514 void Finalize();
|
|
|
1515
|
|
|
1516 private:
|
|
|
1517 /// Check for valid BLOB
|
|
|
1518 void CheckBlob();
|
|
|
1519
|
|
|
1520 void* m_db; ///< associated SQLite3 database handle
|
|
|
1521 void* m_blob; ///< associated SQLite3 BLOB handle
|
|
|
1522 bool m_ok; ///< flag whether the BLOB handle is correctly initialized
|
|
|
1523 bool m_writable; ///< flag whether the BLOB is writable or read only
|
|
|
1524 };
|
|
|
1525
|
|
|
1526 /// Represents a named collection
|
|
|
1527 /**
|
|
|
1528 * A named collection is designed to facilitate using an array of
|
|
|
1529 * integers or strings as the right-hand side of an IN operator.
|
|
|
1530 * So instead of doing a prepared statement like this:
|
|
|
1531 *
|
|
|
1532 * SELECT * FROM table WHERE x IN (?,?,?,...,?);
|
|
|
1533 *
|
|
|
1534 * And then binding indivdual integers to each of ? slots, an application
|
|
|
1535 * can create a named collection object (named "ex1" in the following
|
|
|
1536 * example), prepare a statement like this:
|
|
|
1537 *
|
|
|
1538 * SELECT * FROM table WHERE x IN ex1;
|
|
|
1539 *
|
|
|
1540 * Then bind an array of integer or string values to the ex1 object
|
|
|
1541 * to run the statement.
|
|
|
1542 *
|
|
|
1543 * USAGE:
|
|
|
1544 *
|
|
|
1545 * One or more named collection objects can be created as follows:
|
|
|
1546 *
|
|
|
1547 * wxSQLite3IntegerCollection p1, p2, p3;
|
|
|
1548 * p1 = db.CreateIntegerCollection("ex1");
|
|
|
1549 * p2 = db.CreateIntegerCollection("ex2");
|
|
|
1550 * p3 = db.CreateIntegerCollection("ex3");
|
|
|
1551 *
|
|
|
1552 * Each call to CreateIntegerCollection generates a new virtual table
|
|
|
1553 * module and a singleton of that virtual table module in the TEMP
|
|
|
1554 * database. Both the module and the virtual table instance use the
|
|
|
1555 * name given by the second parameter. The virtual tables can then be
|
|
|
1556 * used in prepared statements:
|
|
|
1557 *
|
|
|
1558 * SELECT * FROM t1, t2, t3
|
|
|
1559 * WHERE t1.x IN ex1
|
|
|
1560 * AND t2.y IN ex2
|
|
|
1561 * AND t3.z IN ex3;
|
|
|
1562 *
|
|
|
1563 * Each integer array is initially empty. New arrays can be bound to
|
|
|
1564 * an integer array as follows:
|
|
|
1565 *
|
|
|
1566 * int a1[] = { 1, 2, 3, 4 };
|
|
|
1567 * int a2[] = { 5, 6, 7, 8, 9, 10, 11 };
|
|
|
1568 * wxArrayInt a3;
|
|
|
1569 * // Fill a3
|
|
|
1570 * p1.Bind(4, a1);
|
|
|
1571 * p2.Bind(7, a2);
|
|
|
1572 * p3.Bind(a3);
|
|
|
1573 *
|
|
|
1574 * A single named collection object can be rebound multiple times. But do not
|
|
|
1575 * attempt to change the bindings of a named collection while it is in the middle
|
|
|
1576 * of a query.
|
|
|
1577 *
|
|
|
1578 * The array that holds the integer or string values is automatically allocated
|
|
|
1579 * by the Bind method.
|
|
|
1580 *
|
|
|
1581 * The named collection object is automatically destroyed when its corresponding
|
|
|
1582 * virtual table is dropped. Since the virtual tables are created in the
|
|
|
1583 * TEMP database, they are automatically dropped when the database connection
|
|
|
1584 * closes so the application does not normally need to take any special
|
|
|
1585 * action to free the named collection objects.
|
|
|
1586 */
|
|
|
1587 class WXDLLIMPEXP_SQLITE3 wxSQLite3NamedCollection
|
|
|
1588 {
|
|
|
1589 public:
|
|
|
1590 /// Constructor
|
|
|
1591 wxSQLite3NamedCollection();
|
|
|
1592
|
|
|
1593 /// Copy constructor
|
|
|
1594 wxSQLite3NamedCollection(const wxSQLite3NamedCollection& collection);
|
|
|
1595
|
|
|
1596 /// Assignement constructor
|
|
|
1597 wxSQLite3NamedCollection& operator=(const wxSQLite3NamedCollection& collection);
|
|
|
1598
|
|
|
1599 /// Constructor (internal use only)
|
|
|
1600 wxSQLite3NamedCollection(const wxString& collectionName, void* collectionData);
|
|
|
1601
|
|
|
1602 /// Destructor
|
|
|
1603 virtual ~wxSQLite3NamedCollection();
|
|
|
1604
|
|
|
1605 /// Get the name of the collection
|
|
|
1606 /**
|
|
|
1607 * \return the name of the collection
|
|
|
1608 */
|
|
|
1609 const wxString& GetName() { return m_name; }
|
|
|
1610
|
|
|
1611 protected:
|
|
|
1612 wxString m_name; ///< Name of the collection
|
|
|
1613 void* m_data; ///< Reference to the actual array of values representing the collection
|
|
|
1614
|
|
|
1615 friend class wxSQLite3Database;
|
|
|
1616 };
|
|
|
1617
|
|
|
1618 /// Represents a named integer value collection
|
|
|
1619 class WXDLLIMPEXP_SQLITE3 wxSQLite3IntegerCollection : public wxSQLite3NamedCollection
|
|
|
1620 {
|
|
|
1621 public:
|
|
|
1622 /// Constructor
|
|
|
1623 wxSQLite3IntegerCollection();
|
|
|
1624
|
|
|
1625 /// Copy constructor
|
|
|
1626 wxSQLite3IntegerCollection(const wxSQLite3IntegerCollection& collection);
|
|
|
1627
|
|
|
1628 /// Assignement constructor
|
|
|
1629 wxSQLite3IntegerCollection& operator=(const wxSQLite3IntegerCollection& collection);
|
|
|
1630
|
|
|
1631 /// Constructor (internal use only)
|
|
|
1632 wxSQLite3IntegerCollection(const wxString& collectionName, void* collectionData);
|
|
|
1633
|
|
|
1634 /// Destructor
|
|
|
1635 virtual ~wxSQLite3IntegerCollection();
|
|
|
1636
|
|
|
1637 /// Bind a new array of integer values
|
|
|
1638 /**
|
|
|
1639 * Bind a new array of integer values to this named collection object.
|
|
|
1640 * \param integerCollection array of integer values to be bound
|
|
|
1641 * \note Binding values to a named collection after closing the corresponding
|
|
|
1642 * database results in undefined behaviour, i.e. the application is likely to crash.
|
|
|
1643 */
|
|
|
1644 void Bind(const wxArrayInt& integerCollection);
|
|
|
1645
|
|
|
1646 /// Bind a new array of integer values
|
|
|
1647 /**
|
|
|
1648 * Bind a new array of integer values to this named collection object.
|
|
|
1649 * \param n number of elements in the array
|
|
|
1650 * \param integerCollection array of integer values to be bound
|
|
|
1651 * \note Binding values to a named collection after closing the corresponding
|
|
|
1652 * database results in undefined behaviour, i.e. the application is likely to crash.
|
|
|
1653 */
|
|
|
1654 void Bind(int n, int* integerCollection);
|
|
|
1655
|
|
|
1656 private:
|
|
|
1657 friend class wxSQLite3Database;
|
|
|
1658 };
|
|
|
1659
|
|
|
1660 /// Represents a named string value collection
|
|
|
1661 class WXDLLIMPEXP_SQLITE3 wxSQLite3StringCollection : public wxSQLite3NamedCollection
|
|
|
1662 {
|
|
|
1663 public:
|
|
|
1664 /// Constructor
|
|
|
1665 wxSQLite3StringCollection();
|
|
|
1666
|
|
|
1667 /// Copy constructor
|
|
|
1668 wxSQLite3StringCollection(const wxSQLite3StringCollection& collection);
|
|
|
1669
|
|
|
1670 /// Assignement constructor
|
|
|
1671 wxSQLite3StringCollection& operator=(const wxSQLite3StringCollection& collection);
|
|
|
1672
|
|
|
1673 /// Constructor (internal use only)
|
|
|
1674 wxSQLite3StringCollection(const wxString& collectionName, void* collectionData);
|
|
|
1675
|
|
|
1676 /// Destructor
|
|
|
1677 virtual ~wxSQLite3StringCollection();
|
|
|
1678
|
|
|
1679 /// Bind a new array of integer values
|
|
|
1680 /**
|
|
|
1681 * Bind a new array of integer values to this named collection object.
|
|
|
1682 * \param stringCollection array of integer values to be bound
|
|
|
1683 * \note Binding values to a named collection after closing the corresponding
|
|
|
1684 * database results in undefined behaviour, i.e. the application is likely to crash.
|
|
|
1685 */
|
|
|
1686 void Bind(const wxArrayString& stringCollection);
|
|
|
1687
|
|
|
1688 private:
|
|
|
1689 friend class wxSQLite3Database;
|
|
|
1690 };
|
|
|
1691
|
|
|
1692 /// Represents a SQLite3 database object
|
|
|
1693 class WXDLLIMPEXP_SQLITE3 wxSQLite3Database
|
|
|
1694 {
|
|
|
1695 public:
|
|
|
1696 /// Default constructor
|
|
|
1697 /**
|
|
|
1698 * Initializes a SQLite database object.
|
|
|
1699 * The SQLite database object can only be used in the same thread in which it was created.
|
|
|
1700 */
|
|
|
1701 wxSQLite3Database();
|
|
|
1702
|
|
|
1703 /// Destructor
|
|
|
1704 /**
|
|
|
1705 * Destructs a SQLite database object.
|
|
|
1706 * The database will be closed implicitly if it is still open.
|
|
|
1707 */
|
|
|
1708 virtual ~wxSQLite3Database();
|
|
|
1709
|
|
|
1710 /// Open a SQLite3 database
|
|
|
1711 /**
|
|
|
1712 * Opens the sqlite database file "filename". The "filename" is UTF-8 encoded.
|
|
|
1713 * If the database could not be opened (or created) successfully, then an exception is thrown.
|
|
|
1714 * If the database file does not exist, then a new database will be created as needed.
|
|
|
1715 * \param[in] fileName Name of the database file.
|
|
|
1716 * \param[in] key Database encryption key.
|
|
|
1717 * \param[in] flags Control over the database connection (see http://www.sqlite.org/c3ref/open.html for further information).
|
|
|
1718 * Flag values are prefixed by WX to distinguish them from the original SQLite flag values.
|
|
|
1719 */
|
|
|
1720 void Open(const wxString& fileName, const wxString& key = wxEmptyString,
|
|
|
1721 int flags = WXSQLITE_OPEN_READWRITE | WXSQLITE_OPEN_CREATE);
|
|
|
1722
|
|
|
1723 /// Open a SQLite3 database using a binary key
|
|
|
1724 /**
|
|
|
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.
|
|
|
1732 */
|
|
|
1733 void Open(const wxString& fileName, const wxMemoryBuffer& key,
|
|
|
1734 int flags = WXSQLITE_OPEN_READWRITE | WXSQLITE_OPEN_CREATE);
|
|
|
1735
|
|
|
1736 /// Check whether the database has been opened
|
|
|
1737 /**
|
|
|
1738 * \return TRUE if database has been opened, FALSE otherwise
|
|
|
1739 */
|
|
|
1740 bool IsOpen() const;
|
|
|
1741
|
|
|
1742 /// Close a SQLite3 database
|
|
|
1743 /**
|
|
|
1744 * Take care that all prepared statements have been finalized!
|
|
|
1745 * Starting with version 3.6.0 SQLite has support to finialize all unfinalized
|
|
|
1746 * prepared statements. The Close method has been changed to take advantage of
|
|
|
1747 * this feature. Nevertheless it is recommended to explicitly finalize all
|
|
|
1748 * wxSQLite3Statement instances before closing a database.
|
|
|
1749 *
|
|
|
1750 * NOTE: Finalizing all wxSQLite3Blob instances before closing a database is still required!
|
|
|
1751 *
|
|
|
1752 */
|
|
|
1753 void Close();
|
|
|
1754
|
|
|
1755 /// Backup a SQLite3 database
|
|
|
1756 /**
|
|
|
1757 * This method is used to overwrite the contents of a database with the contents
|
|
|
1758 * of this database. This is useful either for creating backups of the database or
|
|
|
1759 * for copying an in-memory database to persistent files.
|
|
|
1760 *
|
|
|
1761 * NOTE: Exclusive access is required to the target database for the
|
|
|
1762 * duration of the operation. However the source database is only
|
|
|
1763 * read-locked while it is actually being read, it is not locked
|
|
|
1764 * continuously for the entire operation. Thus, the backup may be
|
|
|
1765 * performed on a live database without preventing other users from
|
|
|
1766 * writing to the database for an extended period of time.
|
|
|
1767 *
|
|
|
1768 * NOTE: If the target database file already exists it must be a valid
|
|
|
1769 * SQLite database, in case of an encrypted database the key used for
|
|
|
1770 * backup must be the same as the key used for creation.
|
|
|
1771 * If this does not hold true, the file should be deleted prior to
|
|
|
1772 * performing the backup.
|
|
|
1773 *
|
|
|
1774 * \param[in] targetFileName Name of the target database file.
|
|
|
1775 * \param[in] key Optional database encryption key for the target database.
|
|
|
1776 * \param[in] sourceDatabaseName Optional name of the source database (default: 'main').
|
|
|
1777 */
|
|
|
1778 void Backup(const wxString& targetFileName, const wxString& key = wxEmptyString, const wxString& sourceDatabaseName = wxT("main"));
|
|
|
1779
|
|
|
1780 /// Backup a SQLite3 database
|
|
|
1781 /**
|
|
|
1782 * This method is used to overwrite the contents of a database with the contents
|
|
|
1783 * of this database. This is useful either for creating backups of the database or
|
|
|
1784 * for copying an in-memory database to persistent files.
|
|
|
1785 *
|
|
|
1786 * NOTE: Exclusive access is required to the target database for the
|
|
|
1787 * duration of the operation. However the source database is only
|
|
|
1788 * read-locked while it is actually being read, it is not locked
|
|
|
1789 * continuously for the entire operation. Thus, the backup may be
|
|
|
1790 * performed on a live database without preventing other users from
|
|
|
1791 * writing to the database for an extended period of time.
|
|
|
1792 *
|
|
|
1793 * NOTE: If the target database file already exists it must be a valid
|
|
|
1794 * SQLite database, in case of an encrypted database the key used for
|
|
|
1795 * backup must be the same as the key used for creation.
|
|
|
1796 * If this does not hold true, the file should be deleted prior to
|
|
|
1797 * performing the backup.
|
|
|
1798 *
|
|
|
1799 * \param[in] targetFileName Name of the target database file.
|
|
|
1800 * \param[in] key Binary database encryption key for the target database.
|
|
|
1801 * \param[in] sourceDatabaseName Optional name of the source database (default: 'main').
|
|
|
1802 */
|
|
|
1803 void Backup(const wxString& targetFileName, const wxMemoryBuffer& key, const wxString& sourceDatabaseName = wxT("main"));
|
|
|
1804
|
|
|
1805 /// Restore a SQLite3 database
|
|
|
1806 /**
|
|
|
1807 * This method is used to restore the contents of this database with the contents
|
|
|
1808 * of another database. This is useful either for restoring a backup of the database or
|
|
|
1809 * for copying a persistent file to an in-memory database.
|
|
|
1810 *
|
|
|
1811 * NOTE: Exclusive access is required to the target database for the
|
|
|
1812 * duration of the operation. However the source database is only
|
|
|
1813 * read-locked while it is actually being read, it is not locked
|
|
|
1814 * continuously for the entire operation. Thus, the backup may be
|
|
|
1815 * performed on a live database without preventing other users from
|
|
|
1816 * writing to the database for an extended period of time.
|
|
|
1817 *
|
|
|
1818 * \param[in] sourceFileName Name of the source database file.
|
|
|
1819 * \param[in] key Optional database encryption key for the source database.
|
|
|
1820 * \param[in] targetDatabaseName Optional name of the target database (default: 'main').
|
|
|
1821 */
|
|
|
1822 void Restore(const wxString& sourceFileName, const wxString& key = wxEmptyString, const wxString& targetDatabaseName = wxT("main"));
|
|
|
1823
|
|
|
1824 /// Restore a SQLite3 database
|
|
|
1825 /**
|
|
|
1826 * This method is used to restore the contents of this database with the contents
|
|
|
1827 * of another database. This is useful either for restoring a backup of the database or
|
|
|
1828 * for copying a persistent file to an in-memory database.
|
|
|
1829 *
|
|
|
1830 * NOTE: Exclusive access is required to the target database for the
|
|
|
1831 * duration of the operation. However the source database is only
|
|
|
1832 * read-locked while it is actually being read, it is not locked
|
|
|
1833 * continuously for the entire operation. Thus, the backup may be
|
|
|
1834 * performed on a live database without preventing other users from
|
|
|
1835 * writing to the database for an extended period of time.
|
|
|
1836 *
|
|
|
1837 * \param[in] sourceFileName Name of the source database file.
|
|
|
1838 * \param[in] key Optional binary database encryption key for the source database.
|
|
|
1839 * \param[in] targetDatabaseName Optional name of the target database (default: 'main').
|
|
|
1840 */
|
|
|
1841 void Restore(const wxString& sourceFileName, const wxMemoryBuffer& key, const wxString& targetDatabaseName = wxT("main"));
|
|
|
1842
|
|
|
1843 /// Begin transaction
|
|
|
1844 /**
|
|
|
1845 * In SQLite transactions can be deferred, immediate, or exclusive.
|
|
|
1846 * Deferred means that no locks are acquired on the database until the database is first accessed.
|
|
|
1847 * Thus with a deferred transaction, the BEGIN statement itself does nothing. Locks are not
|
|
|
1848 * acquired until the first read or write operation. The first read operation against a database
|
|
|
1849 * creates a SHARED lock and the first write operation creates a RESERVED lock. Because the
|
|
|
1850 * acquisition of locks is deferred until they are needed, it is possible that another thread or
|
|
|
1851 * process could create a separate transaction and write to the database after the BEGIN on the
|
|
|
1852 * current thread has executed. If the transaction is immediate, then RESERVED locks are acquired
|
|
|
1853 * on all databases as soon as the BEGIN command is executed, without waiting for the database to
|
|
|
1854 * be used. After a BEGIN IMMEDIATE, it is guaranteed that no other thread or process will be able
|
|
|
1855 * to write to the database or do a BEGIN IMMEDIATE or BEGIN EXCLUSIVE. Other processes can continue
|
|
|
1856 * to read from the database, however. An exclusive transaction causes EXCLUSIVE locks to be acquired
|
|
|
1857 * on all databases. After a BEGIN EXCLUSIVE, it is guaranteed that no other thread or process will
|
|
|
1858 * be able to read or write the database until the transaction is complete.
|
|
|
1859 *
|
|
|
1860 * \param[in] transactionType type of transaction (default: DEFERRED).
|
|
|
1861 */
|
|
|
1862 void Begin(wxSQLite3TransactionType transactionType = WXSQLITE_TRANSACTION_DEFAULT);
|
|
|
1863
|
|
|
1864 /// Commit transaction
|
|
|
1865 /**
|
|
|
1866 */
|
|
|
1867 void Commit();
|
|
|
1868
|
|
|
1869 /// Rollback transaction
|
|
|
1870 /**
|
|
|
1871 * Rolls back a transaction or optionally to a previously set savepoint
|
|
|
1872 *
|
|
|
1873 * \param savepointName optional name of a previously set savepoint
|
|
|
1874 */
|
|
|
1875 void Rollback(const wxString& savepointName = wxEmptyString);
|
|
|
1876
|
|
|
1877 /// Get the auto commit state
|
|
|
1878 /**
|
|
|
1879 * Test to see whether or not the database connection is in autocommit mode.
|
|
|
1880 * \return TRUE if it is and FALSE if not.
|
|
|
1881 * Autocommit mode is on by default. Autocommit is disabled by a BEGIN statement
|
|
|
1882 * and reenabled by the next COMMIT or ROLLBACK.
|
|
|
1883 */
|
|
|
1884 bool GetAutoCommit();
|
|
|
1885
|
|
|
1886 /// Set savepoint
|
|
|
1887 /*
|
|
|
1888 * Sets a savepoint with a given name
|
|
|
1889 *
|
|
|
1890 * \param savepointName the name of the savepoint
|
|
|
1891 */
|
|
|
1892 void Savepoint(const wxString& savepointName);
|
|
|
1893
|
|
|
1894 /// Release savepoint
|
|
|
1895 /*
|
|
|
1896 * Releases a savepoint with a given name
|
|
|
1897 *
|
|
|
1898 * \param savepointName the name of the savepoint
|
|
|
1899 */
|
|
|
1900 void ReleaseSavepoint(const wxString& savepointName);
|
|
|
1901
|
|
|
1902 /// Check whether a table with the given name exists
|
|
|
1903 /**
|
|
|
1904 * Checks the main database or a specific attached database for existence of a table
|
|
|
1905 * with a given name.
|
|
|
1906 *
|
|
|
1907 * \param tableName name of the table
|
|
|
1908 * \param databaseName optional name of an attached database
|
|
|
1909 * \return TRUE if the table exists, FALSE otherwise
|
|
|
1910 */
|
|
|
1911 bool TableExists(const wxString& tableName, const wxString& databaseName = wxEmptyString);
|
|
|
1912
|
|
|
1913 /// Check whether a table with the given name exists in the main database or any attached database
|
|
|
1914 /**
|
|
|
1915 * \param tableName name of the table
|
|
|
1916 * \param databaseNames list of the names of those databases in which the table exists
|
|
|
1917 * \return TRUE if the table exists at least in one database, FALSE otherwise
|
|
|
1918 */
|
|
|
1919 bool TableExists(const wxString& tableName, wxArrayString& databaseNames);
|
|
|
1920
|
|
|
1921 /// Get a list containing the names of all attached databases including the main database
|
|
|
1922 /**
|
|
|
1923 * \param databaseNames contains on return the list of the database names
|
|
|
1924 */
|
|
|
1925 void GetDatabaseList(wxArrayString& databaseNames);
|
|
|
1926
|
|
|
1927 /// Get a list containing the names of all attached databases including the main database
|
|
|
1928 /**
|
|
|
1929 * \param databaseNames contains on return the list of the database names
|
|
|
1930 * \param databaseFiles contains on return the list of the database file names
|
|
|
1931 */
|
|
|
1932 void GetDatabaseList(wxArrayString& databaseNames, wxArrayString& databaseFiles);
|
|
|
1933
|
|
|
1934 /// Enable or disable foreign key support
|
|
|
1935 /**
|
|
|
1936 * Starting with SQLite version 3.6.19 foreign key constraints can be enforced.
|
|
|
1937 * Foreign key constraints are disabled by default (for backwards compatibility),
|
|
|
1938 * so they must be enabled separately for each database connection.
|
|
|
1939 * \note Future releases of SQLite might change so that foreign key constraints
|
|
|
1940 * are enabled by default. No assumptions should be made about whether or not
|
|
|
1941 * foreign keys are enabled by default
|
|
|
1942 * \return TRUE if the requested action succeeded, FALSE otherwise
|
|
|
1943 */
|
|
|
1944 bool EnableForeignKeySupport(bool enable);
|
|
|
1945
|
|
|
1946 /// Check whether foreign key support is enabled for this database
|
|
|
1947 /**
|
|
|
1948 * \return TRUE if foreign key support is enabled, FALSE otherwise
|
|
|
1949 */
|
|
|
1950 bool IsForeignKeySupportEnabled();
|
|
|
1951
|
|
|
1952 /// Set SQLite journal mode
|
|
|
1953 /**
|
|
|
1954 * \param mode the journal mode to be set
|
|
|
1955 * \param database the attached database for which the journal mode should be set. If not given then
|
|
|
1956 * the journal mode of all attached databases is set.
|
|
|
1957 * \return the active journal mode
|
|
|
1958 * \note The journal mode for an in-memory database is either MEMORY or OFF and can not be changed
|
|
|
1959 * to a different value. An attempt to change the journal mode of an in-memory database to any setting
|
|
|
1960 * other than MEMORY or OFF is ignored. Note also that the journal mode cannot be changed while a
|
|
|
1961 * transaction is active.
|
|
|
1962 * The WAL journaling mode uses a write-ahead log instead of a rollback journal to implement transactions.
|
|
|
1963 * The WAL journaling mode is persistent; after being set it stays in effect across multiple database
|
|
|
1964 * connections and after closing and reopening the database. A database in WAL journaling mode can only be
|
|
|
1965 * accessed by SQLite version 3.7.0 or later.
|
|
|
1966 */
|
|
|
1967 wxSQLite3JournalMode SetJournalMode(wxSQLite3JournalMode mode, const wxString& database = wxEmptyString);
|
|
|
1968
|
|
|
1969 /// Get the active SQLite journal mode
|
|
|
1970 /**
|
|
|
1971 * \param database the attached database for which the journal mode should be queried (default: main)
|
|
|
1972 * \return active journal mode
|
|
|
1973 */
|
|
|
1974 wxSQLite3JournalMode GetJournalMode(const wxString& database = wxEmptyString);
|
|
|
1975
|
|
|
1976 /// Check the syntax of an SQL statement given as a wxString
|
|
|
1977 /**
|
|
|
1978 * \param sql query string
|
|
|
1979 * \return TRUE if the syntax is correct, FALSE otherwise
|
|
|
1980 */
|
|
|
1981 bool CheckSyntax(const wxString& sql);
|
|
|
1982
|
|
|
1983 /// Check the syntax of an SQL statement given as a statement buffer
|
|
|
1984 /**
|
|
|
1985 * \param sql query string
|
|
|
1986 * \return TRUE if the syntax is correct, FALSE otherwise
|
|
|
1987 */
|
|
|
1988 bool CheckSyntax(const wxSQLite3StatementBuffer& sql);
|
|
|
1989
|
|
|
1990 /// Check the syntax of an SQL statement given as a utf-8 character string
|
|
|
1991 /**
|
|
|
1992 * \param sql query string
|
|
|
1993 * \return TRUE if the syntax is correct, FALSE otherwise
|
|
|
1994 */
|
|
|
1995 bool CheckSyntax(const char* sql);
|
|
|
1996
|
|
|
1997 /// Execute a insert, update or delete SQL statement given as a wxString
|
|
|
1998 /**
|
|
|
1999 * \param sql query string
|
|
|
2000 * \return the number of database rows that were changed (or inserted or deleted)
|
|
|
2001 */
|
|
|
2002 int ExecuteUpdate(const wxString& sql);
|
|
|
2003
|
|
|
2004 /// Execute a insert, update or delete SQL statement given as a statement buffer
|
|
|
2005 /**
|
|
|
2006 * \param sql query string
|
|
|
2007 * \return the number of database rows that were changed (or inserted or deleted)
|
|
|
2008 */
|
|
|
2009 int ExecuteUpdate(const wxSQLite3StatementBuffer& sql);
|
|
|
2010
|
|
|
2011 /// Execute a insert, update or delete SQL statement given as a utf-8 character string
|
|
|
2012 /**
|
|
|
2013 * \param sql query string
|
|
|
2014 * \return the number of database rows that were changed (or inserted or deleted)
|
|
|
2015 */
|
|
|
2016 int ExecuteUpdate(const char* sql);
|
|
|
2017
|
|
|
2018 /// Execute a SQL query statement given as a wxString
|
|
|
2019 /**
|
|
|
2020 * \param sql query string
|
|
|
2021 * \return result set instance
|
|
|
2022 */
|
|
|
2023 wxSQLite3ResultSet ExecuteQuery(const wxString& sql);
|
|
|
2024
|
|
|
2025 /// Execute a SQL query statement given as a statement buffer
|
|
|
2026 /**
|
|
|
2027 * \param sql query string
|
|
|
2028 * \return result set instance
|
|
|
2029 */
|
|
|
2030 wxSQLite3ResultSet ExecuteQuery(const wxSQLite3StatementBuffer& sql);
|
|
|
2031
|
|
|
2032 /// Execute a SQL query statement given as a utf-8 character string
|
|
|
2033 /**
|
|
|
2034 * \param sql query string
|
|
|
2035 * \return result set instance
|
|
|
2036 */
|
|
|
2037 wxSQLite3ResultSet ExecuteQuery(const char* sql);
|
|
|
2038
|
|
|
2039 /// Execute a scalar SQL query statement given as a wxString
|
|
|
2040 /**
|
|
|
2041 * Allows to easily retrieve the result of queries returning a single integer result
|
|
|
2042 * like SELECT COUNT(*) FROM table WHERE condition.
|
|
|
2043 * \param sql query string
|
|
|
2044 * \return first column of first row as an int
|
|
|
2045 */
|
|
|
2046 int ExecuteScalar(const wxString& sql);
|
|
|
2047
|
|
|
2048 /// Execute a scalar SQL query statement given as a statement buffer
|
|
|
2049 /**
|
|
|
2050 * Allows to easily retrieve the result of queries returning a single integer result
|
|
|
2051 * like SELECT COUNT(*) FROM table WHERE condition.
|
|
|
2052 * \param sql query string
|
|
|
2053 * \return first column of first row as an int
|
|
|
2054 */
|
|
|
2055 int ExecuteScalar(const wxSQLite3StatementBuffer& sql);
|
|
|
2056
|
|
|
2057 /// Execute a scalar SQL query statement given as a utf-8 character string
|
|
|
2058 /**
|
|
|
2059 * Allows to easily retrieve the result of queries returning a single integer result
|
|
|
2060 * like SELECT COUNT(*) FROM table WHERE condition.
|
|
|
2061 * \param sql query string
|
|
|
2062 * \return first column of first row as an int
|
|
|
2063 */
|
|
|
2064 int ExecuteScalar(const char* sql);
|
|
|
2065
|
|
|
2066 /// Get the result table for a SQL query statement given as a wxString
|
|
|
2067 /**
|
|
|
2068 * Returns all resulting rows of the query for later processing.
|
|
|
2069 * \param sql query string
|
|
|
2070 * \return table instance
|
|
|
2071 */
|
|
|
2072 wxSQLite3Table GetTable(const wxString& sql);
|
|
|
2073
|
|
|
2074 /// Get the result table for a SQL query statement given as a statement buffer
|
|
|
2075 /**
|
|
|
2076 * Returns all resulting rows of the query for later processing.
|
|
|
2077 * \param sql query string
|
|
|
2078 * \return table instance
|
|
|
2079 */
|
|
|
2080 wxSQLite3Table GetTable(const wxSQLite3StatementBuffer& sql);
|
|
|
2081
|
|
|
2082 /// Get the result table for a SQL query statement given as a utf-8 character string
|
|
|
2083 /**
|
|
|
2084 * Returns all resulting rows of the query for later processing.
|
|
|
2085 * \param sql query string
|
|
|
2086 * \return table instance
|
|
|
2087 */
|
|
|
2088 wxSQLite3Table GetTable(const char* sql);
|
|
|
2089
|
|
|
2090 /// Prepare a SQL query statement given as a wxString for parameter binding
|
|
|
2091 /**
|
|
|
2092 * \param sql query string
|
|
|
2093 * \return statement instance
|
|
|
2094 */
|
|
|
2095 wxSQLite3Statement PrepareStatement(const wxString& sql);
|
|
|
2096
|
|
|
2097 /// Prepare a SQL query statement given as a statement buffer for parameter binding
|
|
|
2098 /**
|
|
|
2099 * \param sql query string
|
|
|
2100 * \return statement instance
|
|
|
2101 */
|
|
|
2102 wxSQLite3Statement PrepareStatement(const wxSQLite3StatementBuffer& sql);
|
|
|
2103
|
|
|
2104 /// Prepare a SQL query statement given as a utf-8 character string for parameter binding
|
|
|
2105 /**
|
|
|
2106 * \param sql query string
|
|
|
2107 * \return statement instance
|
|
|
2108 */
|
|
|
2109 wxSQLite3Statement PrepareStatement(const char* sql);
|
|
|
2110
|
|
|
2111 /// Get the row id of last inserted row
|
|
|
2112 /**
|
|
|
2113 * Each entry in an SQLite table has a unique integer key.
|
|
|
2114 * (The key is the value of the INTEGER PRIMARY KEY column if there is such a column,
|
|
|
2115 * otherwise the key is generated at random. The unique key is always available as the
|
|
|
2116 * ROWID, OID, or _ROWID_ column.)
|
|
|
2117 * \return the integer key of the most recent insert in the database.
|
|
|
2118 */
|
|
|
2119 wxLongLong GetLastRowId();
|
|
|
2120
|
|
|
2121 /// Get handle to a read only BLOB
|
|
|
2122 /**
|
|
|
2123 * \param rowId
|
|
|
2124 * \param columnName
|
|
|
2125 * \param tableName
|
|
|
2126 * \param dbName
|
|
|
2127 */
|
|
|
2128 wxSQLite3Blob GetReadOnlyBlob(wxLongLong rowId,
|
|
|
2129 const wxString& columnName,
|
|
|
2130 const wxString& tableName,
|
|
|
2131 const wxString& dbName = wxEmptyString);
|
|
|
2132
|
|
|
2133 /// Get handle to a writable BLOB
|
|
|
2134 /**
|
|
|
2135 * \param rowId
|
|
|
2136 * \param columnName
|
|
|
2137 * \param tableName
|
|
|
2138 * \param dbName
|
|
|
2139 */
|
|
|
2140 wxSQLite3Blob GetWritableBlob(wxLongLong rowId,
|
|
|
2141 const wxString& columnName,
|
|
|
2142 const wxString& tableName,
|
|
|
2143 const wxString& dbName = wxEmptyString);
|
|
|
2144
|
|
|
2145 /// Get handle to a BLOB
|
|
|
2146 /**
|
|
|
2147 * \param rowId
|
|
|
2148 * \param columnName
|
|
|
2149 * \param tableName
|
|
|
2150 * \param dbName
|
|
|
2151 * \param writable
|
|
|
2152 */
|
|
|
2153 wxSQLite3Blob GetBlob(wxLongLong rowId,
|
|
|
2154 const wxString& columnName,
|
|
|
2155 const wxString& tableName,
|
|
|
2156 const wxString& dbName = wxEmptyString,
|
|
|
2157 bool writable = true);
|
|
|
2158
|
|
|
2159 /// Create a named integer value collection
|
|
|
2160 /**
|
|
|
2161 * Invoke this method to create a specific instance of an integer collection object.
|
|
|
2162 * Initially the created collection is empty. Use it's Bind method to actually bind
|
|
|
2163 * an array of values to the collection.
|
|
|
2164 * \param collectionName name of the collection
|
|
|
2165 * \return the new integer collection object.
|
|
|
2166 *
|
|
|
2167 * Each integer value collection object corresponds to a virtual table in the TEMP table
|
|
|
2168 * with a name of collectionName.
|
|
|
2169 *
|
|
|
2170 * The virtual table will be dropped implicitly when the database connection is closed.
|
|
|
2171 */
|
|
|
2172 wxSQLite3IntegerCollection CreateIntegerCollection(const wxString& collectionName);
|
|
|
2173
|
|
|
2174 /// Create a named string value collection
|
|
|
2175 /**
|
|
|
2176 * Invoke this method to create a specific instance of a string collection object.
|
|
|
2177 * Initially the created collection is empty. Use it's Bind method to actually bind
|
|
|
2178 * an array of values to the collection.
|
|
|
2179 * \param collectionName name of the collection
|
|
|
2180 * \return the new string collection object.
|
|
|
2181 *
|
|
|
2182 * Each integer value collection object corresponds to a virtual table in the TEMP table
|
|
|
2183 * with a name of collectionName.
|
|
|
2184 *
|
|
|
2185 * The virtual table will be dropped implicitly when the database connection is closed.
|
|
|
2186 */
|
|
|
2187 wxSQLite3StringCollection CreateStringCollection(const wxString& collectionName);
|
|
|
2188
|
|
|
2189 /// Interrupt a long running query
|
|
|
2190 /**
|
|
|
2191 * Causes any pending database operation to abort and return at its earliest opportunity.
|
|
|
2192 * This method is typically called in response to a user action such as pressing "Cancel"
|
|
|
2193 * or Ctrl-C where the user wants a long query operation to halt immediately.
|
|
|
2194 */
|
|
|
2195 void Interrupt();
|
|
|
2196
|
|
|
2197 /// Set the busy timeout
|
|
|
2198 /**
|
|
|
2199 * This method sets a busy handler that sleeps for a while when a table is locked.
|
|
|
2200 * The handler will sleep multiple times until at least "ms" milliseconds of sleeping
|
|
|
2201 * have been done.
|
|
|
2202 * Calling this routine with an argument less than or equal to zero turns off all busy handlers.
|
|
|
2203 * \param milliSeconds timeout in milliseconds
|
|
|
2204 */
|
|
|
2205 void SetBusyTimeout(int milliSeconds);
|
|
|
2206
|
|
|
2207 /// Create a user-defined scalar function
|
|
|
2208 /**
|
|
|
2209 * Registers a SQL scalar function with the database.
|
|
|
2210 * \param name
|
|
|
2211 * \param argCount number of arguments the scalar function takes.
|
|
|
2212 * If this argument is -1 then the scalar function may take any number of arguments.
|
|
|
2213 * \param function instance of an scalar function
|
|
|
2214 * \return TRUE on successful registration, FALSE otherwise
|
|
|
2215 */
|
|
|
2216 bool CreateFunction(const wxString& name, int argCount, wxSQLite3ScalarFunction& function);
|
|
|
2217
|
|
|
2218 /// Create a user-defined aggregate function
|
|
|
2219 /**
|
|
|
2220 * Registers a SQL aggregate function with the database.
|
|
|
2221 * \param name
|
|
|
2222 * \param argCount number of arguments the aggregate function takes.
|
|
|
2223 * If this argument is -1 then the aggregate function may take any number of arguments.
|
|
|
2224 * \param function instance of an aggregate function
|
|
|
2225 * \return TRUE on successful registration, FALSE otherwise
|
|
|
2226 */
|
|
|
2227 bool CreateFunction(const wxString& name, int argCount, wxSQLite3AggregateFunction& function);
|
|
|
2228
|
|
|
2229 /// Create a user-defined authorizer function
|
|
|
2230 /**
|
|
|
2231 * Registers an authorizer object with the SQLite library. The authorizer is invoked
|
|
|
2232 * (at compile-time, not at run-time) for each attempt to access a column of a table in the database.
|
|
|
2233 * The authorizer should return SQLITE_OK if access is allowed, SQLITE_DENY if the entire SQL statement
|
|
|
2234 * should be aborted with an error and SQLITE_IGNORE if the column should be treated as a NULL value.
|
|
|
2235 * \param authorizer instance of an authorizer function
|
|
|
2236 * \return TRUE on successful registration, FALSE otherwise
|
|
|
2237 */
|
|
|
2238 bool SetAuthorizer(wxSQLite3Authorizer& authorizer);
|
|
|
2239
|
|
|
2240 /// Create a user-defined commit callback function
|
|
|
2241 /**
|
|
|
2242 * Registers a callback function object to be invoked whenever a new transaction is committed.
|
|
|
2243 * If the callback function returns non-zero, then the commit is converted into a rollback.
|
|
|
2244 * Registering a NULL function object disables the callback. Only a single commit hook callback
|
|
|
2245 * can be registered at a time.
|
|
|
2246 * \param commitHook address of an instance of a commit callback function
|
|
|
2247 */
|
|
|
2248 void SetCommitHook(wxSQLite3Hook* commitHook);
|
|
|
2249
|
|
|
2250 /// Create a user-defined rollback callback function
|
|
|
2251 /**
|
|
|
2252 * Registers a callback function object to be invoked whenever a transaction is rolled back.
|
|
|
2253 * Registering a NULL function object disables the callback. Only a single rollback hook callback
|
|
|
2254 * can be registered at a time.
|
|
|
2255 *
|
|
|
2256 * For the purposes of this API, a transaction is said to have been rolled back if an explicit
|
|
|
2257 * "ROLLBACK" statement is executed, or an error or constraint causes an implicit rollback to occur.
|
|
|
2258 * The callback is not invoked if a transaction is automatically rolled back because the database
|
|
|
2259 * connection is closed.
|
|
|
2260 * \param rollbackHook address of an instance of a rollback callback function
|
|
|
2261 */
|
|
|
2262 void SetRollbackHook(wxSQLite3Hook* rollbackHook);
|
|
|
2263
|
|
|
2264 /// Create a user-defined update callback function
|
|
|
2265 /**
|
|
|
2266 * Registers a callback function object to be invoked whenever a row is updated, inserted or deleted.
|
|
|
2267 * Registering a NULL function object disables the callback. Only a single commit hook callback
|
|
|
2268 * can be registered at a time.
|
|
|
2269 * The update hook is not invoked when internal system tables are modified (i.e. sqlite_master and sqlite_sequence).
|
|
|
2270 * \param updateHook address of an instance of an update callback function
|
|
|
2271 */
|
|
|
2272 void SetUpdateHook(wxSQLite3Hook* updateHook);
|
|
|
2273
|
|
|
2274 /// Create a user-defined Write Ahead Log callback function
|
|
|
2275 /**
|
|
|
2276 * Registers a callback function object to be invoked whenever a commit has taken place in WAL journal mode.
|
|
|
2277 * Registering a NULL function object disables the callback. Only a single Write Ahead Log hook callback
|
|
|
2278 * can be registered at a time.
|
|
|
2279 * \param walHook address of an instance of a Write Ahead Log callback function
|
|
|
2280 */
|
|
|
2281 void SetWriteAheadLogHook(wxSQLite3Hook* walHook);
|
|
|
2282
|
|
|
2283 /// Checkpoint database in write-ahead log mode
|
|
|
2284 /**
|
|
|
2285 * Causes an optionally named database to be checkpointed.
|
|
|
2286 * If no database name is given, then a checkpoint is run on all databases associated with this
|
|
|
2287 * database instance. If the database instance is not in write-ahead log mode then this method
|
|
|
2288 * is a harmless no-op.
|
|
|
2289 * \param database name of a database to be checkpointed
|
|
|
2290 */
|
|
|
2291 void WriteAheadLogCheckpoint(const wxString& database);
|
|
|
2292
|
|
|
2293 /// Automatically checkpoint database in write-ahead log mode
|
|
|
2294 /**
|
|
|
2295 * Causes any database associated with this database instance to automatically checkpoint after
|
|
|
2296 * committing a transaction if there are N or more frames in the write-ahead log file.
|
|
|
2297 * Passing zero or a negative value as the nFrame parameter disables automatic checkpoints entirely.
|
|
|
2298 * \param frameCount frame threshold
|
|
|
2299 */
|
|
|
2300 void AutoWriteAheadLogCheckpoint(int frameCount);
|
|
|
2301
|
|
|
2302 /// Create a user-defined collation sequence
|
|
|
2303 /**
|
|
|
2304 * Registers a callback function object to be invoked whenever this collation is needed
|
|
|
2305 * in comparing strings.
|
|
|
2306 * Registering a NULL function object disables the specified collation sequence.
|
|
|
2307 * \param name name of a user-defined collation sequence
|
|
|
2308 * \param collation address of an instance of a user-defined collation sequence
|
|
|
2309 */
|
|
|
2310 void SetCollation(const wxString& name, wxSQLite3Collation* collation);
|
|
|
2311
|
|
|
2312 /// Return meta information about a specific column of a specific database table
|
|
|
2313 /**
|
|
|
2314 * \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.
|
|
|
2315 * \param tableName name of the database table
|
|
|
2316 * \param columnName name of the database column
|
|
|
2317 * \param dataType declared data type of the column. Pass NULL if information not needed.
|
|
|
2318 * \param collation name of the collation sequence. Pass NULL if information is not needed.
|
|
|
2319 * \param notNull output flag whether the column has a not null constraint. Pass NULL if information not needed.
|
|
|
2320 * \param primaryKey output flag whether the column is part of the primary key. Pass NULL if information not needed.
|
|
|
2321 * \param autoIncrement output flag whether the column is an auto increment column. Pass NULL if information not needed.
|
|
|
2322 *
|
|
|
2323 * This method is only available if WXSQLITE3_HAVE_METADATA is defined and SQLite has been compiled with SQLITE_ENABLE_COLUMN_METADATA defined.
|
|
|
2324 */
|
|
|
2325 void GetMetaData(const wxString& dbName, const wxString& tableName, const wxString& columnName,
|
|
|
2326 wxString* dataType = NULL, wxString* collation = NULL,
|
|
|
2327 bool* notNull = NULL, bool* primaryKey = NULL, bool* autoIncrement = NULL);
|
|
|
2328
|
|
|
2329 /// Load a database extension
|
|
|
2330 /**
|
|
|
2331 * \param fileName Name of the shared library containing extension.
|
|
|
2332 * \param entryPoint Name of the entry point.
|
|
|
2333 */
|
|
|
2334 void LoadExtension(const wxString& fileName, const wxString& entryPoint = wxT("sqlite3_extension_init"));
|
|
|
2335
|
|
|
2336 /// Enable or disable loading of database extensions
|
|
|
2337 /**
|
|
|
2338 * \param enable Flag whether to enable (TRUE) or disable (FALSE) loadable extensions
|
|
|
2339 */
|
|
|
2340 void EnableLoadExtension(bool enable);
|
|
|
2341
|
|
|
2342 /// Change the encryption key of the database
|
|
|
2343 /**
|
|
|
2344 * If the database is currently not encrypted, this method will encrypt it.
|
|
|
2345 * If an empty key (with key length == 0) is given, the database is decrypted.
|
|
|
2346 *
|
|
|
2347 * \param newKey The new encryption key (will be converted to UTF-8)
|
|
|
2348 */
|
|
|
2349 void ReKey(const wxString& newKey);
|
|
|
2350
|
|
|
2351 /// Change the encryption key of the database
|
|
|
2352 /**
|
|
|
2353 * If the database is currently not encrypted, this method will encrypt it.
|
|
|
2354 * If an empty key (with key length == 0) is given, the database is decrypted.
|
|
|
2355 *
|
|
|
2356 * \param newKey The new encryption key
|
|
|
2357 */
|
|
|
2358 void ReKey(const wxMemoryBuffer& newKey);
|
|
|
2359
|
|
|
2360 /// Check whether the database is encrypted
|
|
|
2361 /**
|
|
|
2362 * Check whether the database has been opened using an encryption key.
|
|
|
2363 *
|
|
|
2364 * \return TRUE if database is encrypted, FALSE otherwise
|
|
|
2365 */
|
|
|
2366 bool IsEncrypted() const { return m_isEncrypted; }
|
|
|
2367
|
|
|
2368 /// Query the value of a database limit
|
|
|
2369 /**
|
|
|
2370 * This method allows to query several database limits. Consult the SQLite
|
|
|
2371 * documentation for further explanation.
|
|
|
2372 *
|
|
|
2373 * \param id The identifier of the limit to be queried
|
|
|
2374 * \return the current value of the queried limit
|
|
|
2375 */
|
|
|
2376 int GetLimit(wxSQLite3LimitType id);
|
|
|
2377
|
|
|
2378 /// Change a database limit to a new value
|
|
|
2379 /**
|
|
|
2380 * This method allows to change several database limits. Consult the SQLite
|
|
|
2381 * documentation for further explanation.
|
|
|
2382 *
|
|
|
2383 * \param id The identifier of the limit to be queried
|
|
|
2384 * \param newValue The new value of the limit to be set
|
|
|
2385 * \return the previous value of the specified limit
|
|
|
2386 */
|
|
|
2387 int SetLimit(wxSQLite3LimitType id, int newValue);
|
|
|
2388
|
|
|
2389 /// Convert database limit type to string
|
|
|
2390 /**
|
|
|
2391 * \param type The database limit type to be converted to string representation.
|
|
|
2392 */
|
|
|
2393 static wxString LimitTypeToString(wxSQLite3LimitType type);
|
|
|
2394
|
|
|
2395 /// Initialize the SQLite library
|
|
|
2396 /**
|
|
|
2397 * Starting with SQLite version 3.6.0 there is a new method to initialize
|
|
|
2398 * the SQLite library. Currently an explicit call to this method is not
|
|
|
2399 * required, but this behaviour might change in the future of SQLite.
|
|
|
2400 * Therefore it is recommended to call this method once before accessing
|
|
|
2401 * any SQLite databases.
|
|
|
2402 */
|
|
|
2403 static void InitializeSQLite();
|
|
|
2404
|
|
|
2405 /// Shutdown the SQLite library
|
|
|
2406 /**
|
|
|
2407 * Starting with SQLite version 3.6.0 there is a new method to shutdown
|
|
|
2408 * the SQLite library. Currently an explicit call to this method is not
|
|
|
2409 * required, but this behaviour might change in the future of SQLite.
|
|
|
2410 * Therefore it is recommended to call this method once when no further
|
|
|
2411 * access to any SQLite databases is required.
|
|
|
2412 */
|
|
|
2413 static void ShutdownSQLite();
|
|
|
2414
|
|
|
2415 /// Get random bytes
|
|
|
2416 /**
|
|
|
2417 * SQLite contains a high-quality pseudo-random number generator.
|
|
|
2418 * This method allows to access it for application specofoc purposes.
|
|
|
2419 *
|
|
|
2420 * \param n The amount of random bytes to be created
|
|
|
2421 * \param random A memory buffer containing the random bytes on return
|
|
|
2422 */
|
|
|
2423 static bool Randomness(int n, wxMemoryBuffer& random);
|
|
|
2424
|
|
|
2425 /// Enable or disable SQLite shared cache
|
|
|
2426 /**
|
|
|
2427 * The cache sharing mode set effects all subsequent database connections.
|
|
|
2428 * Existing database connections continue use the sharing mode that was in effect
|
|
|
2429 * at the time they were opened.
|
|
|
2430 *
|
|
|
2431 * Virtual tables cannot be used with a shared cache.
|
|
|
2432 */
|
|
|
2433 static void SetSharedCache(bool enable);
|
|
|
2434
|
|
|
2435 /// Check whether SQLite shared cache is enabled
|
|
|
2436 /**
|
|
|
2437 * \return TRUE if the SQLite shared cache is enabled, FALSE otherwise
|
|
|
2438 */
|
|
|
2439 static bool IsSharedCacheEnabled() { return ms_sharedCacheEnabled; }
|
|
|
2440
|
|
|
2441 /// Get the version of the underlying SQLite3 library
|
|
|
2442 /**
|
|
|
2443 * \return a string which contains the version number of the library
|
|
|
2444 */
|
|
|
2445 static wxString GetVersion();
|
|
|
2446
|
|
|
2447 /// Get the source id of the underlying SQLite3 library
|
|
|
2448 /**
|
|
|
2449 * \return a string which contains the source id of the library
|
|
|
2450 */
|
|
|
2451 static wxString GetSourceId();
|
|
|
2452
|
|
|
2453 /// Check SQLite compile option
|
|
|
2454 /**
|
|
|
2455 * Check whether the compile option with a given name has been used on building SQLite.
|
|
|
2456 * The SQLITE_ prefix may be omitted from the option name passed to this method.
|
|
|
2457 *
|
|
|
2458 * \param optionName name of the compile option to be queried
|
|
|
2459 * \return TRUE if the compile option was in use, FALSE otherwise
|
|
|
2460 *
|
|
|
2461 * \note If the option name is unknown or if the SQLite version is lower than 3.6.23
|
|
|
2462 * this method returns FALSE.
|
|
|
2463 */
|
|
|
2464 static bool CompileOptionUsed(const wxString& optionName);
|
|
|
2465
|
|
|
2466 /// Get SQLite compile option name
|
|
|
2467 /**
|
|
|
2468 * Get the name of a SQLite compile option at a given index.
|
|
|
2469 * This method allows interating over the list of options that were defined
|
|
|
2470 * at compile time. If the option index is out of range, an empty string is returned.
|
|
|
2471 * The SQLITE_ prefix is omitted from any strings returned by this method.
|
|
|
2472 *
|
|
|
2473 * \param optionIndex Index of the compile option
|
|
|
2474 * \return a string containing the name of the n-th
|
|
|
2475 */
|
|
|
2476 static wxString GetCompileOptionName(int optionIndex);
|
|
|
2477
|
|
|
2478 /// Convert journal mode to/from string
|
|
|
2479 /**
|
|
|
2480 * \param mode the wxSQLite3JournalMode enum value signifying the desired journal mode.
|
|
|
2481 * \return the string representation of the journal mode
|
|
|
2482 */
|
|
|
2483 static wxString ConvertJournalMode(wxSQLite3JournalMode mode);
|
|
|
2484
|
|
|
2485 /// Convert journal mode to/from string
|
|
|
2486 /**
|
|
|
2487 * \param mode the string representation of the desired journal mode.
|
|
|
2488 * \return the enum representation of the journal mode
|
|
|
2489 */
|
|
|
2490 static wxSQLite3JournalMode ConvertJournalMode(const wxString& mode);
|
|
|
2491
|
|
|
2492 /// Check whether wxSQLite3 has been compiled with encryption support
|
|
|
2493 /**
|
|
|
2494 * \return TRUE if encryption support is enabled, FALSE otherwise
|
|
|
2495 */
|
|
|
2496 static bool HasEncryptionSupport();
|
|
|
2497
|
|
|
2498 /// Check whether wxSQLite3 has been compiled with meta data support
|
|
|
2499 /**
|
|
|
2500 * \return TRUE if meta data support is enabled, FALSE otherwise
|
|
|
2501 */
|
|
|
2502 static bool HasMetaDataSupport();
|
|
|
2503
|
|
|
2504 /// Check whether wxSQLite3 has been compiled with loadable extension support
|
|
|
2505 /**
|
|
|
2506 * \return TRUE if loadable extension support is enabled, FALSE otherwise
|
|
|
2507 */
|
|
|
2508 static bool HasLoadExtSupport();
|
|
|
2509
|
|
|
2510 /// Check whether wxSQLite3 has been compiled with support for named collections
|
|
|
2511 /**
|
|
|
2512 * \return TRUE if named collection support is enabled, FALSE otherwise
|
|
|
2513 */
|
|
|
2514 static bool HasNamedCollectionSupport();
|
|
|
2515
|
|
|
2516 /// Check whether wxSQLite3 has support for incremental BLOBs
|
|
|
2517 /**
|
|
|
2518 * \return TRUE if incremental BLOB support is available, FALSE otherwise
|
|
|
2519 */
|
|
|
2520 static bool HasIncrementalBlobSupport();
|
|
|
2521
|
|
|
2522 /// Check whether wxSQLite3 has support for SQLite savepoints
|
|
|
2523 /**
|
|
|
2524 * \return TRUE if SQLite savepoints are supported, FALSE otherwise
|
|
|
2525 */
|
|
|
2526 static bool HasSavepointSupport();
|
|
|
2527
|
|
|
2528 /// Check whether wxSQLite3 has support for SQLite backup/restore
|
|
|
2529 /**
|
|
|
2530 * \return TRUE if SQLite backup/restore is supported, FALSE otherwise
|
|
|
2531 */
|
|
|
2532 static bool HasBackupSupport();
|
|
|
2533
|
|
|
2534 /// Check whether wxSQLite3 has support for SQLite write-ahead log
|
|
|
2535 /**
|
|
|
2536 * \return TRUE if SQLite write-ahead log is supported, FALSE otherwise
|
|
|
2537 */
|
|
|
2538 static bool HasWriteAheadLogSupport();
|
|
|
2539
|
|
|
2540 protected:
|
|
|
2541 /// Access SQLite's internal database handle
|
|
|
2542 void* GetDatabaseHandle() { return m_db; }
|
|
|
2543
|
|
|
2544 /// Activate the callback for needed collations for this database
|
|
|
2545 /**
|
|
|
2546 * To avoid having to register all collation sequences before a database can be used,
|
|
|
2547 * a single callback function may be registered with the database handle to be called
|
|
|
2548 * whenever an undefined collation sequence is required.
|
|
|
2549 */
|
|
|
2550 void SetCollationNeededCallback();
|
|
|
2551
|
|
|
2552 /// Request the instantiation of a user defined collation sequence
|
|
|
2553 /**
|
|
|
2554 * This method is called for every undefined collation sequence.
|
|
|
2555 * In a derived database class this method should call SetCollation registering an
|
|
|
2556 * appropriate collation class instance.
|
|
|
2557 * \param collationName name of the collation which is needed for string comparison
|
|
|
2558 */
|
|
|
2559 virtual void SetNeededCollation(const wxString& WXUNUSED(collationName)) {}
|
|
|
2560
|
|
|
2561 /// Execute a comparison using a user-defined collation
|
|
|
2562 static int ExecComparisonWithCollation(void* collation, int len1, const void* txt1, int len2, const void* txt2);
|
|
|
2563
|
|
|
2564 /// Execute callback for needed collation sequences
|
|
|
2565 static void ExecCollationNeeded(void* db, void* internalDb, int eTextRep, const char* name);
|
|
|
2566
|
|
|
2567 private:
|
|
|
2568 /// Private copy constructor
|
|
|
2569 wxSQLite3Database(const wxSQLite3Database& db);
|
|
|
2570
|
|
|
2571 /// Private assignment constructor
|
|
|
2572 wxSQLite3Database& operator=(const wxSQLite3Database& db);
|
|
|
2573
|
|
|
2574 /// Prepare a SQL statement (internal use only)
|
|
|
2575 void* Prepare(const char* sql);
|
|
|
2576
|
|
|
2577 /// Check for valid database connection
|
|
|
2578 void CheckDatabase();
|
|
|
2579
|
|
|
2580 void* m_db; ///< associated SQLite3 database
|
|
|
2581 int m_busyTimeoutMs; ///< Timeout in milli seconds
|
|
|
2582 bool m_isEncrypted; ///< Flag whether the database is encrypted or not
|
|
|
2583
|
|
|
2584 static bool ms_sharedCacheEnabled; ///< Flag whether SQLite shared cache is enabled
|
|
|
2585 static bool ms_hasEncryptionSupport; ///< Flag whether wxSQLite3 has been compiled with encryption support
|
|
|
2586 static bool ms_hasMetaDataSupport; ///< Flag whether wxSQLite3 has been compiled with meta data support
|
|
|
2587 static bool ms_hasLoadExtSupport; ///< Flag whether wxSQLite3 has been compiled with loadable extension support
|
|
|
2588 static bool ms_hasNamedCollectionSupport; ///< Flag whether wxSQLite3 has been compiled with support for named collections
|
|
|
2589 static bool ms_hasIncrementalBlobSupport; ///< Flag whether wxSQLite3 has support for incremental BLOBs
|
|
|
2590 static bool ms_hasSavepointSupport; ///< Flag whether wxSQLite3 has support for SQLite savepoints
|
|
|
2591 static bool ms_hasBackupSupport; ///< Flag whether wxSQLite3 has support for SQLite backup/restore
|
|
|
2592 static bool ms_hasWriteAheadLogSupport; ///< Flag whether wxSQLite3 has support for SQLite write-ahead log
|
|
|
2593 };
|
|
|
2594
|
|
|
2595 /// RAII class for managing transactions
|
|
|
2596 /***
|
|
|
2597 * This object allows easy managment of transaction. It con only be
|
|
|
2598 * created on the stack. This guarantees that the destructor is called
|
|
|
2599 * at the moment it goes out of scope. Usage:
|
|
|
2600 * \code
|
|
|
2601 * void doDB(wxSQLite3Database *db)
|
|
|
2602 * {
|
|
|
2603 * wxSQLite3Transaction t(db);
|
|
|
2604 * doDatabaseOperations();
|
|
|
2605 * t.Commit();
|
|
|
2606 * }
|
|
|
2607 * \endcode
|
|
|
2608 * In case doDatabseOperations() fails by throwing an exception,
|
|
|
2609 * the transaction is automatically rolled back. If it succedes,
|
|
|
2610 * Commit() commits the changes to the db and the destructor
|
|
|
2611 * of Transaction does nothing.
|
|
|
2612 */
|
|
|
2613 class WXDLLIMPEXP_SQLITE3 wxSQLite3Transaction
|
|
|
2614 {
|
|
|
2615 public:
|
|
|
2616 /// Constructor. Start the Transaction.
|
|
|
2617 /**
|
|
|
2618 * The constructor starts the transaction.
|
|
|
2619 * \param db Pointer to the open Database. The pointer to the database
|
|
|
2620 * is NOT freed on destruction!
|
|
|
2621 * \param transactionType Type of the transaction to be opened.
|
|
|
2622 */
|
|
|
2623 explicit wxSQLite3Transaction(wxSQLite3Database* db, wxSQLite3TransactionType transactionType = WXSQLITE_TRANSACTION_DEFAULT);
|
|
|
2624
|
|
|
2625 /// Destructor.
|
|
|
2626 /**
|
|
|
2627 * The destructor does nothing if the changes were already commited (see commit()).
|
|
|
2628 * In case the changes were not commited, a call to the destructor rolls back the
|
|
|
2629 * transaction.
|
|
|
2630 */
|
|
|
2631 ~wxSQLite3Transaction();
|
|
|
2632
|
|
|
2633 /// Commits the transaction
|
|
|
2634 /**
|
|
|
2635 * Commits the transaction if active. If not, it does nothing.
|
|
|
2636 * After the commit, the transaction is not active.
|
|
|
2637 */
|
|
|
2638 void Commit();
|
|
|
2639
|
|
|
2640 /// Rolls back the transaction
|
|
|
2641 /**
|
|
|
2642 * Rolls back the transaction if active. If not, it does nothing.
|
|
|
2643 * After the rollback, the transaction is not active.
|
|
|
2644 */
|
|
|
2645 void Rollback();
|
|
|
2646
|
|
|
2647 /// Determins wether the transaction is open or not
|
|
|
2648 /**
|
|
|
2649 * \return TRUE if the constructor successfully opend the transaction, false otherwise.
|
|
|
2650 * After committing the transaction, active returns false.
|
|
|
2651 */
|
|
|
2652 inline bool IsActive()
|
|
|
2653 {
|
|
|
2654 return m_database != NULL;
|
|
|
2655 }
|
|
|
2656
|
|
|
2657 private:
|
|
|
2658 /// New operator (May only be created on the stack)
|
|
|
2659 static void *operator new(size_t size);
|
|
|
2660
|
|
|
2661 /// Delete operator (May not be deleted (for symmetry))
|
|
|
2662 static void operator delete(void *ptr);
|
|
|
2663
|
|
|
2664 /// Copy constructor (Must not be copied)
|
|
|
2665 wxSQLite3Transaction(const wxSQLite3Transaction&);
|
|
|
2666
|
|
|
2667 /// Assignment operator (Must not be assigned)
|
|
|
2668 wxSQLite3Transaction& operator=(const wxSQLite3Transaction&);
|
|
|
2669
|
|
|
2670 wxSQLite3Database* m_database; ///< Pointer to the associated database (no ownership)
|
|
|
2671 };
|
|
|
2672
|
|
|
2673 #if wxUSE_REGEX
|
|
|
2674
|
|
|
2675 /// User defined function for REGEXP operator
|
|
|
2676 /**
|
|
|
2677 */
|
|
|
2678 class WXDLLIMPEXP_SQLITE3 wxSQLite3RegExpOperator : public wxSQLite3ScalarFunction
|
|
|
2679 {
|
|
|
2680 public:
|
|
|
2681 /// Constructor
|
|
|
2682 wxSQLite3RegExpOperator(int flags = wxRE_DEFAULT);
|
|
|
2683
|
|
|
2684 /// Virtual destructor
|
|
|
2685 virtual ~wxSQLite3RegExpOperator();
|
|
|
2686
|
|
|
2687 /// Execute the scalar function
|
|
|
2688 /**
|
|
|
2689 * This method is invoked for each appearance of the scalar function in the SQL query.
|
|
|
2690 * \param ctx function context which can be used to access arguments and result value
|
|
|
2691 */
|
|
|
2692 virtual void Execute(wxSQLite3FunctionContext& ctx);
|
|
|
2693
|
|
|
2694 private:
|
|
|
2695 wxString m_exprStr; ///< Last regular expression string
|
|
|
2696 wxRegEx m_regEx; ///< Regular expression cache (currently only 1 instance)
|
|
|
2697 int m_flags; ///< Flags for regular expression
|
|
|
2698 };
|
|
|
2699
|
|
|
2700 #endif // wxUSE_REGEX
|
|
|
2701
|
|
|
2702 #endif
|
|
|
2703
|
