Annotation of embedaddon/php/ext/sqlite/libsqlite/src/sqlite.w32.h, revision 1.1.1.1
1.1 misho 1: /*
2: ** 2001 September 15
3: **
4: ** The author disclaims copyright to this source code. In place of
5: ** a legal notice, here is a blessing:
6: **
7: ** May you do good and not evil.
8: ** May you find forgiveness for yourself and forgive others.
9: ** May you share freely, never taking more than you give.
10: **
11: *************************************************************************
12: ** This header file defines the interface that the SQLite library
13: ** presents to client programs.
14: **
15: ** @(#) $Id: sqlite.w32.h 203289 2005-12-20 15:26:26Z iliaa $
16: */
17: #ifndef _SQLITE_H_
18: #define _SQLITE_H_
19: #include <stdarg.h> /* Needed for the definition of va_list */
20:
21: /*
22: ** Make sure we can call this stuff from C++.
23: */
24: #ifdef __cplusplus
25: extern "C" {
26: #endif
27:
28: /*
29: ** The version of the SQLite library.
30: */
31: #define SQLITE_VERSION "2.8.17"
32:
33: /*
34: ** The version string is also compiled into the library so that a program
35: ** can check to make sure that the lib*.a file and the *.h file are from
36: ** the same version.
37: */
38: extern const char sqlite_version[];
39:
40: /*
41: ** The SQLITE_UTF8 macro is defined if the library expects to see
42: ** UTF-8 encoded data. The SQLITE_ISO8859 macro is defined if the
43: ** iso8859 encoded should be used.
44: */
45: #define SQLITE_ISO8859 1
46:
47: /*
48: ** The following constant holds one of two strings, "UTF-8" or "iso8859",
49: ** depending on which character encoding the SQLite library expects to
50: ** see. The character encoding makes a difference for the LIKE and GLOB
51: ** operators and for the LENGTH() and SUBSTR() functions.
52: */
53: extern const char sqlite_encoding[];
54:
55: /*
56: ** Each open sqlite database is represented by an instance of the
57: ** following opaque structure.
58: */
59: typedef struct sqlite sqlite;
60:
61: /*
62: ** A function to open a new sqlite database.
63: **
64: ** If the database does not exist and mode indicates write
65: ** permission, then a new database is created. If the database
66: ** does not exist and mode does not indicate write permission,
67: ** then the open fails, an error message generated (if errmsg!=0)
68: ** and the function returns 0.
69: **
70: ** If mode does not indicates user write permission, then the
71: ** database is opened read-only.
72: **
73: ** The Truth: As currently implemented, all databases are opened
74: ** for writing all the time. Maybe someday we will provide the
75: ** ability to open a database readonly. The mode parameters is
76: ** provided in anticipation of that enhancement.
77: */
78: sqlite *sqlite_open(const char *filename, int mode, char **errmsg);
79:
80: /*
81: ** A function to close the database.
82: **
83: ** Call this function with a pointer to a structure that was previously
84: ** returned from sqlite_open() and the corresponding database will by closed.
85: */
86: void sqlite_close(sqlite *);
87:
88: /*
89: ** The type for a callback function.
90: */
91: typedef int (*sqlite_callback)(void*,int,char**, char**);
92:
93: /*
94: ** A function to executes one or more statements of SQL.
95: **
96: ** If one or more of the SQL statements are queries, then
97: ** the callback function specified by the 3rd parameter is
98: ** invoked once for each row of the query result. This callback
99: ** should normally return 0. If the callback returns a non-zero
100: ** value then the query is aborted, all subsequent SQL statements
101: ** are skipped and the sqlite_exec() function returns the SQLITE_ABORT.
102: **
103: ** The 4th parameter is an arbitrary pointer that is passed
104: ** to the callback function as its first parameter.
105: **
106: ** The 2nd parameter to the callback function is the number of
107: ** columns in the query result. The 3rd parameter to the callback
108: ** is an array of strings holding the values for each column.
109: ** The 4th parameter to the callback is an array of strings holding
110: ** the names of each column.
111: **
112: ** The callback function may be NULL, even for queries. A NULL
113: ** callback is not an error. It just means that no callback
114: ** will be invoked.
115: **
116: ** If an error occurs while parsing or evaluating the SQL (but
117: ** not while executing the callback) then an appropriate error
118: ** message is written into memory obtained from malloc() and
119: ** *errmsg is made to point to that message. The calling function
120: ** is responsible for freeing the memory that holds the error
121: ** message. Use sqlite_freemem() for this. If errmsg==NULL,
122: ** then no error message is ever written.
123: **
124: ** The return value is is SQLITE_OK if there are no errors and
125: ** some other return code if there is an error. The particular
126: ** return value depends on the type of error.
127: **
128: ** If the query could not be executed because a database file is
129: ** locked or busy, then this function returns SQLITE_BUSY. (This
130: ** behavior can be modified somewhat using the sqlite_busy_handler()
131: ** and sqlite_busy_timeout() functions below.)
132: */
133: int sqlite_exec(
134: sqlite*, /* An open database */
135: const char *sql, /* SQL to be executed */
136: sqlite_callback, /* Callback function */
137: void *, /* 1st argument to callback function */
138: char **errmsg /* Error msg written here */
139: );
140:
141: /*
142: ** Return values for sqlite_exec() and sqlite_step()
143: */
144: #define SQLITE_OK 0 /* Successful result */
145: #define SQLITE_ERROR 1 /* SQL error or missing database */
146: #define SQLITE_INTERNAL 2 /* An internal logic error in SQLite */
147: #define SQLITE_PERM 3 /* Access permission denied */
148: #define SQLITE_ABORT 4 /* Callback routine requested an abort */
149: #define SQLITE_BUSY 5 /* The database file is locked */
150: #define SQLITE_LOCKED 6 /* A table in the database is locked */
151: #define SQLITE_NOMEM 7 /* A malloc() failed */
152: #define SQLITE_READONLY 8 /* Attempt to write a readonly database */
153: #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite_interrupt() */
154: #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
155: #define SQLITE_CORRUPT 11 /* The database disk image is malformed */
156: #define SQLITE_NOTFOUND 12 /* (Internal Only) Table or record not found */
157: #define SQLITE_FULL 13 /* Insertion failed because database is full */
158: #define SQLITE_CANTOPEN 14 /* Unable to open the database file */
159: #define SQLITE_PROTOCOL 15 /* Database lock protocol error */
160: #define SQLITE_EMPTY 16 /* (Internal Only) Database table is empty */
161: #define SQLITE_SCHEMA 17 /* The database schema changed */
162: #define SQLITE_TOOBIG 18 /* Too much data for one row of a table */
163: #define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */
164: #define SQLITE_MISMATCH 20 /* Data type mismatch */
165: #define SQLITE_MISUSE 21 /* Library used incorrectly */
166: #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
167: #define SQLITE_AUTH 23 /* Authorization denied */
168: #define SQLITE_FORMAT 24 /* Auxiliary database format error */
169: #define SQLITE_RANGE 25 /* 2nd parameter to sqlite_bind out of range */
170: #define SQLITE_NOTADB 26 /* File opened that is not a database file */
171: #define SQLITE_ROW 100 /* sqlite_step() has another row ready */
172: #define SQLITE_DONE 101 /* sqlite_step() has finished executing */
173:
174: /*
175: ** Each entry in an SQLite table has a unique integer key. (The key is
176: ** the value of the INTEGER PRIMARY KEY column if there is such a column,
177: ** otherwise the key is generated at random. The unique key is always
178: ** available as the ROWID, OID, or _ROWID_ column.) The following routine
179: ** returns the integer key of the most recent insert in the database.
180: **
181: ** This function is similar to the mysql_insert_id() function from MySQL.
182: */
183: int sqlite_last_insert_rowid(sqlite*);
184:
185: /*
186: ** This function returns the number of database rows that were changed
187: ** (or inserted or deleted) by the most recent called sqlite_exec().
188: **
189: ** All changes are counted, even if they were later undone by a
190: ** ROLLBACK or ABORT. Except, changes associated with creating and
191: ** dropping tables are not counted.
192: **
193: ** If a callback invokes sqlite_exec() recursively, then the changes
194: ** in the inner, recursive call are counted together with the changes
195: ** in the outer call.
196: **
197: ** SQLite implements the command "DELETE FROM table" without a WHERE clause
198: ** by dropping and recreating the table. (This is much faster than going
199: ** through and deleting individual elements form the table.) Because of
200: ** this optimization, the change count for "DELETE FROM table" will be
201: ** zero regardless of the number of elements that were originally in the
202: ** table. To get an accurate count of the number of rows deleted, use
203: ** "DELETE FROM table WHERE 1" instead.
204: */
205: int sqlite_changes(sqlite*);
206:
207: /* If the parameter to this routine is one of the return value constants
208: ** defined above, then this routine returns a constant text string which
209: ** descripts (in English) the meaning of the return value.
210: */
211: const char *sqlite_error_string(int);
212: #define sqliteErrStr sqlite_error_string /* Legacy. Do not use in new code. */
213:
214: /* This function causes any pending database operation to abort and
215: ** return at its earliest opportunity. This routine is typically
216: ** called in response to a user action such as pressing "Cancel"
217: ** or Ctrl-C where the user wants a long query operation to halt
218: ** immediately.
219: */
220: void sqlite_interrupt(sqlite*);
221:
222:
223: /* This function returns true if the given input string comprises
224: ** one or more complete SQL statements.
225: **
226: ** The algorithm is simple. If the last token other than spaces
227: ** and comments is a semicolon, then return true. otherwise return
228: ** false.
229: */
230: int sqlite_complete(const char *sql);
231:
232: /*
233: ** This routine identifies a callback function that is invoked
234: ** whenever an attempt is made to open a database table that is
235: ** currently locked by another process or thread. If the busy callback
236: ** is NULL, then sqlite_exec() returns SQLITE_BUSY immediately if
237: ** it finds a locked table. If the busy callback is not NULL, then
238: ** sqlite_exec() invokes the callback with three arguments. The
239: ** second argument is the name of the locked table and the third
240: ** argument is the number of times the table has been busy. If the
241: ** busy callback returns 0, then sqlite_exec() immediately returns
242: ** SQLITE_BUSY. If the callback returns non-zero, then sqlite_exec()
243: ** tries to open the table again and the cycle repeats.
244: **
245: ** The default busy callback is NULL.
246: **
247: ** Sqlite is re-entrant, so the busy handler may start a new query.
248: ** (It is not clear why anyone would every want to do this, but it
249: ** is allowed, in theory.) But the busy handler may not close the
250: ** database. Closing the database from a busy handler will delete
251: ** data structures out from under the executing query and will
252: ** probably result in a coredump.
253: */
254: void sqlite_busy_handler(sqlite*, int(*)(void*,const char*,int), void*);
255:
256: /*
257: ** This routine sets a busy handler that sleeps for a while when a
258: ** table is locked. The handler will sleep multiple times until
259: ** at least "ms" milleseconds of sleeping have been done. After
260: ** "ms" milleseconds of sleeping, the handler returns 0 which
261: ** causes sqlite_exec() to return SQLITE_BUSY.
262: **
263: ** Calling this routine with an argument less than or equal to zero
264: ** turns off all busy handlers.
265: */
266: void sqlite_busy_timeout(sqlite*, int ms);
267:
268: /*
269: ** This next routine is really just a wrapper around sqlite_exec().
270: ** Instead of invoking a user-supplied callback for each row of the
271: ** result, this routine remembers each row of the result in memory
272: ** obtained from malloc(), then returns all of the result after the
273: ** query has finished.
274: **
275: ** As an example, suppose the query result where this table:
276: **
277: ** Name | Age
278: ** -----------------------
279: ** Alice | 43
280: ** Bob | 28
281: ** Cindy | 21
282: **
283: ** If the 3rd argument were &azResult then after the function returns
284: ** azResult will contain the following data:
285: **
286: ** azResult[0] = "Name";
287: ** azResult[1] = "Age";
288: ** azResult[2] = "Alice";
289: ** azResult[3] = "43";
290: ** azResult[4] = "Bob";
291: ** azResult[5] = "28";
292: ** azResult[6] = "Cindy";
293: ** azResult[7] = "21";
294: **
295: ** Notice that there is an extra row of data containing the column
296: ** headers. But the *nrow return value is still 3. *ncolumn is
297: ** set to 2. In general, the number of values inserted into azResult
298: ** will be ((*nrow) + 1)*(*ncolumn).
299: **
300: ** After the calling function has finished using the result, it should
301: ** pass the result data pointer to sqlite_free_table() in order to
302: ** release the memory that was malloc-ed. Because of the way the
303: ** malloc() happens, the calling function must not try to call
304: ** malloc() directly. Only sqlite_free_table() is able to release
305: ** the memory properly and safely.
306: **
307: ** The return value of this routine is the same as from sqlite_exec().
308: */
309: int sqlite_get_table(
310: sqlite*, /* An open database */
311: const char *sql, /* SQL to be executed */
312: char ***resultp, /* Result written to a char *[] that this points to */
313: int *nrow, /* Number of result rows written here */
314: int *ncolumn, /* Number of result columns written here */
315: char **errmsg /* Error msg written here */
316: );
317:
318: /*
319: ** Call this routine to free the memory that sqlite_get_table() allocated.
320: */
321: void sqlite_free_table(char **result);
322:
323: /*
324: ** The following routines are wrappers around sqlite_exec() and
325: ** sqlite_get_table(). The only difference between the routines that
326: ** follow and the originals is that the second argument to the
327: ** routines that follow is really a printf()-style format
328: ** string describing the SQL to be executed. Arguments to the format
329: ** string appear at the end of the argument list.
330: **
331: ** All of the usual printf formatting options apply. In addition, there
332: ** is a "%q" option. %q works like %s in that it substitutes a null-terminated
333: ** string from the argument list. But %q also doubles every '\'' character.
334: ** %q is designed for use inside a string literal. By doubling each '\''
335: ** character it escapes that character and allows it to be inserted into
336: ** the string.
337: **
338: ** For example, so some string variable contains text as follows:
339: **
340: ** char *zText = "It's a happy day!";
341: **
342: ** We can use this text in an SQL statement as follows:
343: **
344: ** sqlite_exec_printf(db, "INSERT INTO table VALUES('%q')",
345: ** callback1, 0, 0, zText);
346: **
347: ** Because the %q format string is used, the '\'' character in zText
348: ** is escaped and the SQL generated is as follows:
349: **
350: ** INSERT INTO table1 VALUES('It''s a happy day!')
351: **
352: ** This is correct. Had we used %s instead of %q, the generated SQL
353: ** would have looked like this:
354: **
355: ** INSERT INTO table1 VALUES('It's a happy day!');
356: **
357: ** This second example is an SQL syntax error. As a general rule you
358: ** should always use %q instead of %s when inserting text into a string
359: ** literal.
360: */
361: int sqlite_exec_printf(
362: sqlite*, /* An open database */
363: const char *sqlFormat, /* printf-style format string for the SQL */
364: sqlite_callback, /* Callback function */
365: void *, /* 1st argument to callback function */
366: char **errmsg, /* Error msg written here */
367: ... /* Arguments to the format string. */
368: );
369: int sqlite_exec_vprintf(
370: sqlite*, /* An open database */
371: const char *sqlFormat, /* printf-style format string for the SQL */
372: sqlite_callback, /* Callback function */
373: void *, /* 1st argument to callback function */
374: char **errmsg, /* Error msg written here */
375: va_list ap /* Arguments to the format string. */
376: );
377: int sqlite_get_table_printf(
378: sqlite*, /* An open database */
379: const char *sqlFormat, /* printf-style format string for the SQL */
380: char ***resultp, /* Result written to a char *[] that this points to */
381: int *nrow, /* Number of result rows written here */
382: int *ncolumn, /* Number of result columns written here */
383: char **errmsg, /* Error msg written here */
384: ... /* Arguments to the format string */
385: );
386: int sqlite_get_table_vprintf(
387: sqlite*, /* An open database */
388: const char *sqlFormat, /* printf-style format string for the SQL */
389: char ***resultp, /* Result written to a char *[] that this points to */
390: int *nrow, /* Number of result rows written here */
391: int *ncolumn, /* Number of result columns written here */
392: char **errmsg, /* Error msg written here */
393: va_list ap /* Arguments to the format string */
394: );
395: char *sqlite_mprintf(const char*,...);
396: char *sqlite_vmprintf(const char*, va_list);
397:
398: /*
399: ** Windows systems should call this routine to free memory that
400: ** is returned in the in the errmsg parameter of sqlite_open() when
401: ** SQLite is a DLL. For some reason, it does not work to call free()
402: ** directly.
403: */
404: void sqlite_freemem(void *p);
405:
406: /*
407: ** Windows systems need functions to call to return the sqlite_version
408: ** and sqlite_encoding strings.
409: */
410: const char *sqlite_libversion(void);
411: const char *sqlite_libencoding(void);
412:
413: /*
414: ** A pointer to the following structure is used to communicate with
415: ** the implementations of user-defined functions.
416: */
417: typedef struct sqlite_func sqlite_func;
418:
419: /*
420: ** Use the following routines to create new user-defined functions. See
421: ** the documentation for details.
422: */
423: int sqlite_create_function(
424: sqlite*, /* Database where the new function is registered */
425: const char *zName, /* Name of the new function */
426: int nArg, /* Number of arguments. -1 means any number */
427: void (*xFunc)(sqlite_func*,int,const char**), /* C code to implement */
428: void *pUserData /* Available via the sqlite_user_data() call */
429: );
430: int sqlite_create_aggregate(
431: sqlite*, /* Database where the new function is registered */
432: const char *zName, /* Name of the function */
433: int nArg, /* Number of arguments */
434: void (*xStep)(sqlite_func*,int,const char**), /* Called for each row */
435: void (*xFinalize)(sqlite_func*), /* Called once to get final result */
436: void *pUserData /* Available via the sqlite_user_data() call */
437: );
438:
439: /*
440: ** Use the following routine to define the datatype returned by a
441: ** user-defined function. The second argument can be one of the
442: ** constants SQLITE_NUMERIC, SQLITE_TEXT, or SQLITE_ARGS or it
443: ** can be an integer greater than or equal to zero. The datatype
444: ** will be numeric or text (the only two types supported) if the
445: ** argument is SQLITE_NUMERIC or SQLITE_TEXT. If the argument is
446: ** SQLITE_ARGS, then the datatype is numeric if any argument to the
447: ** function is numeric and is text otherwise. If the second argument
448: ** is an integer, then the datatype of the result is the same as the
449: ** parameter to the function that corresponds to that integer.
450: */
451: int sqlite_function_type(
452: sqlite *db, /* The database there the function is registered */
453: const char *zName, /* Name of the function */
454: int datatype /* The datatype for this function */
455: );
456: #define SQLITE_NUMERIC (-1)
457: #define SQLITE_TEXT (-2)
458: #define SQLITE_ARGS (-3)
459:
460: /*
461: ** The user function implementations call one of the following four routines
462: ** in order to return their results. The first parameter to each of these
463: ** routines is a copy of the first argument to xFunc() or xFinialize().
464: ** The second parameter to these routines is the result to be returned.
465: ** A NULL can be passed as the second parameter to sqlite_set_result_string()
466: ** in order to return a NULL result.
467: **
468: ** The 3rd argument to _string and _error is the number of characters to
469: ** take from the string. If this argument is negative, then all characters
470: ** up to and including the first '\000' are used.
471: **
472: ** The sqlite_set_result_string() function allocates a buffer to hold the
473: ** result and returns a pointer to this buffer. The calling routine
474: ** (that is, the implmentation of a user function) can alter the content
475: ** of this buffer if desired.
476: */
477: char *sqlite_set_result_string(sqlite_func*,const char*,int);
478: void sqlite_set_result_int(sqlite_func*,int);
479: void sqlite_set_result_double(sqlite_func*,double);
480: void sqlite_set_result_error(sqlite_func*,const char*,int);
481:
482: /*
483: ** The pUserData parameter to the sqlite_create_function() and
484: ** sqlite_create_aggregate() routines used to register user functions
485: ** is available to the implementation of the function using this
486: ** call.
487: */
488: void *sqlite_user_data(sqlite_func*);
489:
490: /*
491: ** Aggregate functions use the following routine to allocate
492: ** a structure for storing their state. The first time this routine
493: ** is called for a particular aggregate, a new structure of size nBytes
494: ** is allocated, zeroed, and returned. On subsequent calls (for the
495: ** same aggregate instance) the same buffer is returned. The implementation
496: ** of the aggregate can use the returned buffer to accumulate data.
497: **
498: ** The buffer allocated is freed automatically be SQLite.
499: */
500: void *sqlite_aggregate_context(sqlite_func*, int nBytes);
501:
502: /*
503: ** The next routine returns the number of calls to xStep for a particular
504: ** aggregate function instance. The current call to xStep counts so this
505: ** routine always returns at least 1.
506: */
507: int sqlite_aggregate_count(sqlite_func*);
508:
509: /*
510: ** This routine registers a callback with the SQLite library. The
511: ** callback is invoked (at compile-time, not at run-time) for each
512: ** attempt to access a column of a table in the database. The callback
513: ** returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire
514: ** SQL statement should be aborted with an error and SQLITE_IGNORE
515: ** if the column should be treated as a NULL value.
516: */
517: int sqlite_set_authorizer(
518: sqlite*,
519: int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
520: void *pUserData
521: );
522:
523: /*
524: ** The second parameter to the access authorization function above will
525: ** be one of the values below. These values signify what kind of operation
526: ** is to be authorized. The 3rd and 4th parameters to the authorization
527: ** function will be parameters or NULL depending on which of the following
528: ** codes is used as the second parameter. The 5th parameter is the name
529: ** of the database ("main", "temp", etc.) if applicable. The 6th parameter
530: ** is the name of the inner-most trigger or view that is responsible for
531: ** the access attempt or NULL if this access attempt is directly from
532: ** input SQL code.
533: **
534: ** Arg-3 Arg-4
535: */
536: #define SQLITE_COPY 0 /* Table Name File Name */
537: #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
538: #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
539: #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
540: #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
541: #define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
542: #define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
543: #define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
544: #define SQLITE_CREATE_VIEW 8 /* View Name NULL */
545: #define SQLITE_DELETE 9 /* Table Name NULL */
546: #define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
547: #define SQLITE_DROP_TABLE 11 /* Table Name NULL */
548: #define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
549: #define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
550: #define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
551: #define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
552: #define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
553: #define SQLITE_DROP_VIEW 17 /* View Name NULL */
554: #define SQLITE_INSERT 18 /* Table Name NULL */
555: #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
556: #define SQLITE_READ 20 /* Table Name Column Name */
557: #define SQLITE_SELECT 21 /* NULL NULL */
558: #define SQLITE_TRANSACTION 22 /* NULL NULL */
559: #define SQLITE_UPDATE 23 /* Table Name Column Name */
560: #define SQLITE_ATTACH 24 /* Filename NULL */
561: #define SQLITE_DETACH 25 /* Database Name NULL */
562:
563:
564: /*
565: ** The return value of the authorization function should be one of the
566: ** following constants:
567: */
568: /* #define SQLITE_OK 0 // Allow access (This is actually defined above) */
569: #define SQLITE_DENY 1 /* Abort the SQL statement with an error */
570: #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
571:
572: /*
573: ** Register a function that is called at every invocation of sqlite_exec()
574: ** or sqlite_compile(). This function can be used (for example) to generate
575: ** a log file of all SQL executed against a database.
576: */
577: void *sqlite_trace(sqlite*, void(*xTrace)(void*,const char*), void*);
578:
579: /*** The Callback-Free API
580: **
581: ** The following routines implement a new way to access SQLite that does not
582: ** involve the use of callbacks.
583: **
584: ** An sqlite_vm is an opaque object that represents a single SQL statement
585: ** that is ready to be executed.
586: */
587: typedef struct sqlite_vm sqlite_vm;
588:
589: /*
590: ** To execute an SQLite query without the use of callbacks, you first have
591: ** to compile the SQL using this routine. The 1st parameter "db" is a pointer
592: ** to an sqlite object obtained from sqlite_open(). The 2nd parameter
593: ** "zSql" is the text of the SQL to be compiled. The remaining parameters
594: ** are all outputs.
595: **
596: ** *pzTail is made to point to the first character past the end of the first
597: ** SQL statement in zSql. This routine only compiles the first statement
598: ** in zSql, so *pzTail is left pointing to what remains uncompiled.
599: **
600: ** *ppVm is left pointing to a "virtual machine" that can be used to execute
601: ** the compiled statement. Or if there is an error, *ppVm may be set to NULL.
602: ** If the input text contained no SQL (if the input is and empty string or
603: ** a comment) then *ppVm is set to NULL.
604: **
605: ** If any errors are detected during compilation, an error message is written
606: ** into space obtained from malloc() and *pzErrMsg is made to point to that
607: ** error message. The calling routine is responsible for freeing the text
608: ** of this message when it has finished with it. Use sqlite_freemem() to
609: ** free the message. pzErrMsg may be NULL in which case no error message
610: ** will be generated.
611: **
612: ** On success, SQLITE_OK is returned. Otherwise and error code is returned.
613: */
614: int sqlite_compile(
615: sqlite *db, /* The open database */
616: const char *zSql, /* SQL statement to be compiled */
617: const char **pzTail, /* OUT: uncompiled tail of zSql */
618: sqlite_vm **ppVm, /* OUT: the virtual machine to execute zSql */
619: char **pzErrmsg /* OUT: Error message. */
620: );
621:
622: /*
623: ** After an SQL statement has been compiled, it is handed to this routine
624: ** to be executed. This routine executes the statement as far as it can
625: ** go then returns. The return value will be one of SQLITE_DONE,
626: ** SQLITE_ERROR, SQLITE_BUSY, SQLITE_ROW, or SQLITE_MISUSE.
627: **
628: ** SQLITE_DONE means that the execute of the SQL statement is complete
629: ** an no errors have occurred. sqlite_step() should not be called again
630: ** for the same virtual machine. *pN is set to the number of columns in
631: ** the result set and *pazColName is set to an array of strings that
632: ** describe the column names and datatypes. The name of the i-th column
633: ** is (*pazColName)[i] and the datatype of the i-th column is
634: ** (*pazColName)[i+*pN]. *pazValue is set to NULL.
635: **
636: ** SQLITE_ERROR means that the virtual machine encountered a run-time
637: ** error. sqlite_step() should not be called again for the same
638: ** virtual machine. *pN is set to 0 and *pazColName and *pazValue are set
639: ** to NULL. Use sqlite_finalize() to obtain the specific error code
640: ** and the error message text for the error.
641: **
642: ** SQLITE_BUSY means that an attempt to open the database failed because
643: ** another thread or process is holding a lock. The calling routine
644: ** can try again to open the database by calling sqlite_step() again.
645: ** The return code will only be SQLITE_BUSY if no busy handler is registered
646: ** using the sqlite_busy_handler() or sqlite_busy_timeout() routines. If
647: ** a busy handler callback has been registered but returns 0, then this
648: ** routine will return SQLITE_ERROR and sqltie_finalize() will return
649: ** SQLITE_BUSY when it is called.
650: **
651: ** SQLITE_ROW means that a single row of the result is now available.
652: ** The data is contained in *pazValue. The value of the i-th column is
653: ** (*azValue)[i]. *pN and *pazColName are set as described in SQLITE_DONE.
654: ** Invoke sqlite_step() again to advance to the next row.
655: **
656: ** SQLITE_MISUSE is returned if sqlite_step() is called incorrectly.
657: ** For example, if you call sqlite_step() after the virtual machine
658: ** has halted (after a prior call to sqlite_step() has returned SQLITE_DONE)
659: ** or if you call sqlite_step() with an incorrectly initialized virtual
660: ** machine or a virtual machine that has been deleted or that is associated
661: ** with an sqlite structure that has been closed.
662: */
663: int sqlite_step(
664: sqlite_vm *pVm, /* The virtual machine to execute */
665: int *pN, /* OUT: Number of columns in result */
666: const char ***pazValue, /* OUT: Column data */
667: const char ***pazColName /* OUT: Column names and datatypes */
668: );
669:
670: /*
671: ** This routine is called to delete a virtual machine after it has finished
672: ** executing. The return value is the result code. SQLITE_OK is returned
673: ** if the statement executed successfully and some other value is returned if
674: ** there was any kind of error. If an error occurred and pzErrMsg is not
675: ** NULL, then an error message is written into memory obtained from malloc()
676: ** and *pzErrMsg is made to point to that error message. The calling routine
677: ** should use sqlite_freemem() to delete this message when it has finished
678: ** with it.
679: **
680: ** This routine can be called at any point during the execution of the
681: ** virtual machine. If the virtual machine has not completed execution
682: ** when this routine is called, that is like encountering an error or
683: ** an interrupt. (See sqlite_interrupt().) Incomplete updates may be
684: ** rolled back and transactions cancelled, depending on the circumstances,
685: ** and the result code returned will be SQLITE_ABORT.
686: */
687: int sqlite_finalize(sqlite_vm*, char **pzErrMsg);
688:
689: /*
690: ** This routine deletes the virtual machine, writes any error message to
691: ** *pzErrMsg and returns an SQLite return code in the same way as the
692: ** sqlite_finalize() function.
693: **
694: ** Additionally, if ppVm is not NULL, *ppVm is left pointing to a new virtual
695: ** machine loaded with the compiled version of the original query ready for
696: ** execution.
697: **
698: ** If sqlite_reset() returns SQLITE_SCHEMA, then *ppVm is set to NULL.
699: **
700: ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
701: */
702: int sqlite_reset(sqlite_vm*, char **pzErrMsg);
703:
704: /*
705: ** If the SQL that was handed to sqlite_compile contains variables that
706: ** are represeted in the SQL text by a question mark ('?'). This routine
707: ** is used to assign values to those variables.
708: **
709: ** The first parameter is a virtual machine obtained from sqlite_compile().
710: ** The 2nd "idx" parameter determines which variable in the SQL statement
711: ** to bind the value to. The left most '?' is 1. The 3rd parameter is
712: ** the value to assign to that variable. The 4th parameter is the number
713: ** of bytes in the value, including the terminating \000 for strings.
714: ** Finally, the 5th "copy" parameter is TRUE if SQLite should make its
715: ** own private copy of this value, or false if the space that the 3rd
716: ** parameter points to will be unchanging and can be used directly by
717: ** SQLite.
718: **
719: ** Unbound variables are treated as having a value of NULL. To explicitly
720: ** set a variable to NULL, call this routine with the 3rd parameter as a
721: ** NULL pointer.
722: **
723: ** If the 4th "len" parameter is -1, then strlen() is used to find the
724: ** length.
725: **
726: ** This routine can only be called immediately after sqlite_compile()
727: ** or sqlite_reset() and before any calls to sqlite_step().
728: **
729: ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
730: */
731: int sqlite_bind(sqlite_vm*, int idx, const char *value, int len, int copy);
732:
733: /*
734: ** This routine configures a callback function - the progress callback - that
735: ** is invoked periodically during long running calls to sqlite_exec(),
736: ** sqlite_step() and sqlite_get_table(). An example use for this API is to keep
737: ** a GUI updated during a large query.
738: **
739: ** The progress callback is invoked once for every N virtual machine opcodes,
740: ** where N is the second argument to this function. The progress callback
741: ** itself is identified by the third argument to this function. The fourth
742: ** argument to this function is a void pointer passed to the progress callback
743: ** function each time it is invoked.
744: **
745: ** If a call to sqlite_exec(), sqlite_step() or sqlite_get_table() results
746: ** in less than N opcodes being executed, then the progress callback is not
747: ** invoked.
748: **
749: ** Calling this routine overwrites any previously installed progress callback.
750: ** To remove the progress callback altogether, pass NULL as the third
751: ** argument to this function.
752: **
753: ** If the progress callback returns a result other than 0, then the current
754: ** query is immediately terminated and any database changes rolled back. If the
755: ** query was part of a larger transaction, then the transaction is not rolled
756: ** back and remains active. The sqlite_exec() call returns SQLITE_ABORT.
757: */
758: void sqlite_progress_handler(sqlite*, int, int(*)(void*), void*);
759:
760: #ifdef __cplusplus
761: } /* End of the 'extern "C"' block */
762: #endif
763:
764: #endif /* _SQLITE_H_ */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to sqlite.w32.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php / ext / sqlite / libsqlite / src