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