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