+
+LuaSQLite 3 - a Lua 5.1 to 5.3 wrapper for the SQLite3 library
++
+LuaSQLite 3 is a thin wrapper around the public domain SQLite3 +database engine.
+The lsqlite3 module supports the creation and manipulation of
+SQLite3 databases. After a sqlite3 = require('lsqlite3') the exported
+functions are called with prefix sqlite3. However, most sqlite3
+functions are called via an object-oriented interface to either
+database or SQL statement objects; see below for details.
This documentation does not attempt to describe how SQLite3 itself +works, it just describes the Lua binding and the available functions. +For more information about the SQL features supported by SQLite3 and +details about the syntax of SQL statements and queries, please see the +SQLite3 documentation http://www.sqlite.org/. Using some of the +advanced features (how to use callbacks, for instance) will require +some familiarity with the SQLite3 API.
++
+LuaSQLite 3 source code can be downloaded from its +Fossil (http://lua.sqlite.org/) page.
+You will also need to build or obtain an SQLite3 loadable library +(DLL or .so). See http://www.sqlite.org/ for obtaining SQLite3 +source code or downloading a binary SQLite3 library.
++
+Luarocks (http://luarocks.org/) is the preferred mechanism
+to build and install lsqlite3; it assumes an SQLite3 library is already installed.
+
+The distribution contains an examples directory. The unit tests +also show some example use.
++
+The distribution contains a tests directory with some units tests using
+an enhanced version of Michael Roth's lunit called lunitx. Some of the
+tests were also derived from Michael's lua-sqlite3 module, and more unit tests
+added by Doug Currie. Get lunitx using Luarocks.
The distribution also contains some functional tests by Tiago.
+This version of lsqlite3 was tested with SQLite 3.11.0 and 3.15.0.
+
++
++
++ sqlite3.complete(sql)+
Returns true if the string sql comprises one or more complete SQL
+statements and false otherwise.
+
++ sqlite3.open(filename)+
Opens (or creates if it does not exist) an SQLite database with name
+filename and returns its handle as userdata (the returned object
+should be used for all further method calls in connection with this
+specific database, see Database methods). Example:
+ myDB=sqlite3.open('MyDatabase.sqlite3') -- open
+ -- do some database calls...
+ myDB:close() -- close
+In case of an error, the function returns nil, an error code and an +error message.
+Since 0.9.4, there is a second optional flags argument to sqlite3.open.
+
+ sqlite3.open(filename, flags)+
+See sqlite3_open_v2 for an explanation of +these flags and options.
++Example: +
+ local db = sqlite3.open('foo.db', sqlite3.OPEN_READWRITE + sqlite3.OPEN_CREATE + sqlite3.OPEN_SHAREDCACHE)
+
+The default value for flags is sqlite3.OPEN_READWRITE + sqlite3.OPEN_CREATE.
++
++ sqlite3.open_memory()+
Opens an SQLite database in memory and returns its handle as +userdata. In case of an error, the function returns nil, an error code +and an error message. (In-memory databases are volatile as they are +never stored on disk.)
++
+ ++ sqlite3.backup_init(target_db, target_name, source_db, source_name)+
Starts an SQLite Online Backup from source_db to target_db and
+returns its handle as userdata. The source_db and target_db are
+open databases; they may be in-memory or file-based databases. The target_name and
+source_name are "main" for the main database, "temp" for the temporary database, or
+the name specified after the AS keyword in an ATTACH statement for an attached database.
The source and target databases must be different, or else the init call will fail with an
+error. A call to sqlite3.backup_init will fail, returning NULL, if there is already
+a read or read-write transaction open on the target database.
+
If an error occurs within sqlite3.backup_init, then NULL is returned, and an
+error code and error message are stored in target_db. The error code and message
+for the failed call can be retrieved using the db:errcode,
+or db:errmsg.
+
++ sqlite3.temp_directory([temp])+
Sets or queries the directory used by SQLite for temporary files. If
+string temp is a directory name or nil, the temporary directory is
+set accordingly and the old value is returned. If temp is missing,
+the function simply returns the current temporary directory.
+
++ sqlite3.version()+
Returns a string with SQLite version information, in the form 'x.y[.z[.p]]'.
++
++ sqlite3.lversion()+
Returns a string with lsqlite3 library version information, in the form 'x.y[.z]'.
++
+After opening a database with sqlite3.open() or
+sqlite3.open_memory()
+the returned database object should be used for all further method calls
+in connection with that database. An open database object supports the
+following methods.
+
++ db:busy_handler([func[,udata]])+
Sets or removes a busy handler for a database. func is either a Lua
+function that implements the busy handler or nil to remove a previously
+set handler. This function returns nothing.
The handler function is called with two parameters: udata and the
+number of (re-)tries for a pending transaction. It should return nil,
+false or 0 if the transaction is to be aborted. All other values will
+result in another attempt to perform the transaction. (See the SQLite
+documentation for important hints about writing busy handlers.)
+
++ db:busy_timeout(t)+
Sets a busy handler that waits for t milliseconds if a transaction
+cannot proceed. Calling this function will remove any busy handler set
+by db:busy_handler(); calling it with an argument
+less than or equal to 0 will turn off all busy handlers.
+
++ db:changes()+
This function returns the number of database rows that were changed (or
+inserted or deleted) by the most recent SQL statement. Only changes that
+are directly specified by INSERT, UPDATE, or DELETE statements are
+counted. Auxiliary changes caused by triggers are not counted. Use
+db:total_changes() to find the total number of
+changes.
+
++ db:close()+
Closes a database. All SQL statements prepared using
+db:prepare() should
+have been finalized before this function is called. The function returns
+sqlite3.OK on success or else a numerical error code (see the list of
+Numerical error and result codes).
+
++ db:close_vm(temponly)+
Finalizes all statements that have not been explicitly finalized. If
+temponly is true, only internal, temporary statements are finalized.
+This function returns nothing.
+
++ db:commit_hook(func,udata)+
This function installs a commit_hook callback handler. func is a Lua function
+that is invoked by SQLite3 whenever a transaction is commited. This callback receives one argument:
+the udata argument used when the callback was installed. If func returns false
+or nil the COMMIT is allowed to prodeed, otherwise the COMMIT is converted to a ROLLBACK.
See: db:rollback_hook and db:update_hook
++
++ db:create_aggregate(name,nargs,step,final)+
This function creates an aggregate callback function. Aggregates perform
+an operation over all rows in a query. name is a string with the name
+of the aggregate function as given in an SQL statement; nargs is the
+number of arguments this call will provide. step is the actual Lua
+function that gets called once for every row; it should accept a function
+context (see Methods for callback contexts) plus the same number of
+parameters as given in nargs. final is a function that is called
+once after all rows have been processed; it receives one argument, the
+function context.
The function context can be used inside the two callback functions to +communicate with SQLite3. Here is a simple example:
+
+ db:exec[=[
+ CREATE TABLE numbers(num1,num2);
+ INSERT INTO numbers VALUES(1,11);
+ INSERT INTO numbers VALUES(2,22);
+ INSERT INTO numbers VALUES(3,33);
+ ]=]
+ local num_sum=0
+ local function oneRow(context,num) -- add one column in all rows
+ num_sum=num_sum+num
+ end
+ local function afterLast(context) -- return sum after last row has been processed
+ context:result_number(num_sum)
+ num_sum=0
+ end
+ db:create_aggregate("do_the_sums",1,oneRow,afterLast)
+ for sum in db:urows('SELECT do_the_sums(num1) FROM numbers') do print("Sum of col 1:",sum) end
+ for sum in db:urows('SELECT do_the_sums(num2) FROM numbers') do print("Sum of col 2:",sum) end
+This prints:
++ Sum of col 1: 6 + Sum of col 2: 66+
+
++ db:create_collation(name,func)+
This creates a collation callback. A collation callback is used to
+establish a collation order, mostly for string comparisons and sorting
+purposes. name is a string with the name of the collation to be created;
+func is a function that accepts two string arguments, compares them
+and returns 0 if both strings are identical, -1 if the first argument is
+lower in the collation order than the second and 1 if the first argument
+is higher in the collation order than the second. A simple example:
+ local function collate(s1,s2)
+ s1=s1:lower()
+ s2=s2:lower()
+ if s1==s2 then return 0
+ elseif s1<s2 then return -1
+ else return 1 end
+ end
+ db:exec[=[
+ CREATE TABLE test(id INTEGER PRIMARY KEY,content COLLATE CINSENS);
+ INSERT INTO test VALUES(NULL,'hello world');
+ INSERT INTO test VALUES(NULL,'Buenos dias');
+ INSERT INTO test VALUES(NULL,'HELLO WORLD');
+ ]=]
+ db:create_collation('CINSENS',collate)
+ for row in db:nrows('SELECT * FROM test') do print(row.id,row.content) end
++
++ db:create_function(name,nargs,func)+
This function creates a callback function. Callback function are called
+by SQLite3 once for every row in a query. name is a string with the
+name of the callback function as given in an SQL statement; nargs is
+the number of arguments this call will provide. func is the actual Lua
+function that gets called once for every row; it should accept a
+function context (see Methods for callback contexts) plus the same
+number of parameters as given in nargs. Here is an example:
+ db:exec'CREATE TABLE test(col1,col2,col3)'
+ db:exec'INSERT INTO test VALUES(1,2,4)'
+ db:exec'INSERT INTO test VALUES(2,4,9)'
+ db:exec'INSERT INTO test VALUES(3,6,16)'
+ db:create_function('sum_cols',3,function(ctx,a,b,c)
+ ctx:result_number(a+b+c)
+ end))
+ for col1,col2,col3,sum in db:urows('SELECT *,sum_cols(col1,col2,col3) FROM test') do
+ util.printf('%2i+%2i+%2i=%2i\n',col1,col2,col3,sum)
+ end
++
++ db:load_extension([name,[entrypoint]])+ +
When a name is provided, loads an SQLite extension library from the
+named file into this database connection. The optional entrypoint is the
+library initialization function name; if not supplied, SQLite tries various default
+entrypoint names. Returns true when successful, or false and
+an error string otherwise.
+
When called with no arguments, disables the load_extension() SQL function, which is
+enabled as a side effect of calling db:load_extension with a
+name.
+
+
++ db:errcode() + db:error_code()+
Returns the numerical result code (or extended result code) for the most +recent failed call associated with database db. See +Numerical error and result codes for details.
++
++ db:errmsg() + db:error_message()+
Returns a string that contains an error message for the most recent +failed call associated with database db.
++
++ db:exec(sql[,func[,udata]]) + db:execute(sql[,func[,udata]])+
Compiles and executes the SQL statement(s) given in string sql. The
+statements are simply executed one after the other and not stored. The
+function returns sqlite3.OK on success or else a numerical error code
+(see Numerical error and result codes).
If one or more of the SQL statements are queries, then the callback
+function specified in func is invoked once for each row of the query
+result (if func is nil, no callback is invoked). The callback receives
+four arguments: udata (the third parameter of the db:exec() call),
+the number of columns in the row, a table with the column values and
+another table with the column names. The callback function should return
+0. If the callback returns a non-zero value then the query is aborted,
+all subsequent SQL statements are skipped and db:exec() returns
+sqlite3.ABORT. Here is a simple example:
+ sql=[=[
+ CREATE TABLE numbers(num1,num2,str);
+ INSERT INTO numbers VALUES(1,11,"ABC");
+ INSERT INTO numbers VALUES(2,22,"DEF");
+ INSERT INTO numbers VALUES(3,33,"UVW");
+ INSERT INTO numbers VALUES(4,44,"XYZ");
+ SELECT * FROM numbers;
+ ]=]
+ function showrow(udata,cols,values,names)
+ assert(udata=='test_udata')
+ print('exec:')
+ for i=1,cols do print('',names[i],values[i]) end
+ return 0
+ end
+ db:exec(sql,showrow,'test_udata')
++
++ db:interrupt()+
This function causes any pending database operation to abort and return +at the next opportunity. This function returns nothing.
++
++ db:isopen()+
Returns true if database db is open, false otherwise.
++
++ db:last_insert_rowid()+
This function returns the rowid of the most recent INSERT into the +database. If no inserts have ever occurred, 0 is returned. (Each row in +an SQLite table has a unique 64-bit signed integer key called the +'rowid'. This id is always available as an undeclared column named +ROWID, OID, or _ROWID_. If the table has a column of type INTEGER +PRIMARY KEY then that column is another alias for the rowid.)
+If an INSERT occurs within a trigger, then the rowid of the inserted row +is returned as long as the trigger is running. Once the trigger +terminates, the value returned reverts to the last value inserted before +the trigger fired.
++
++ db:nrows(sql)+
Creates an iterator that returns the successive rows selected by the SQL
+statement given in string sql. Each call to the iterator returns a
+table in which the named fields correspond to the columns in the database.
+Here is an example:
+ db:exec[=[
+ CREATE TABLE numbers(num1,num2);
+ INSERT INTO numbers VALUES(1,11);
+ INSERT INTO numbers VALUES(2,22);
+ INSERT INTO numbers VALUES(3,33);
+ ]=]
+ for a in db:nrows('SELECT * FROM numbers') do table.print(a) end
+This script prints:
++ num2: 11 + num1: 1 + num2: 22 + num1: 2 + num2: 33 + num1: 3+
+
++ db:prepare(sql)+
This function compiles the SQL statement in string sql into an internal
+representation and returns this as userdata. The returned object should
+be used for all further method calls in connection with this specific
+SQL statement (see Methods for prepared statements).
+
++ db:progress_handler(n,func,udata)+
This function installs a callback function func that is invoked
+periodically during long-running calls to db:exec()
+or stmt:step(). The
+progress callback is invoked once for every n internal operations,
+where n is the first argument to this function. udata is passed to
+the progress callback function each time it is invoked. If a call to
+db:exec() or stmt:step() results in fewer than n operations
+being executed, then the progress callback is never invoked. Only a
+single progress callback function may be registered for each opened
+database and a call to this function will overwrite any previously set
+callback function. To remove the progress callback altogether, pass nil
+as the second argument.
If the progress callback returns a result other than 0, then the current
+query is immediately terminated, any database changes are rolled back
+and the containing db:exec() or stmt:step() call returns
+sqlite3.INTERRUPT. This feature can be used to cancel long-running
+queries.
+
++ db:rollback_hook(func,udata)+
This function installs a rollback_hook callback handler. func is a Lua function
+that is invoked by SQLite3 whenever a transaction is rolled back. This callback receives one argument:
+the udata argument used when the callback was installed.
See: db:commit_hook and db:update_hook
++
++ db:rows(sql)+
Creates an iterator that returns the successive rows selected by the SQL
+statement given in string sql. Each call to the iterator returns a table
+in which the numerical indices 1 to n correspond to the selected columns
+1 to n in the database. Here is an example:
+ db:exec[=[
+ CREATE TABLE numbers(num1,num2);
+ INSERT INTO numbers VALUES(1,11);
+ INSERT INTO numbers VALUES(2,22);
+ INSERT INTO numbers VALUES(3,33);
+ ]=]
+ for a in db:rows('SELECT * FROM numbers') do table.print(a) end
+This script prints:
++ 1: 1 + 2: 11 + 1: 2 + 2: 22 + 1: 3 + 2: 33+
+
++ db:total_changes()+
This function returns the number of database rows that have been
+modified by INSERT, UPDATE or DELETE statements since the database was
+opened. This includes UPDATE, INSERT and DELETE statements executed as
+part of trigger programs. All changes are counted as soon as the
+statement that produces them is completed by calling either
+stmt:reset() or stmt:finalize().
+
++ db:trace(func,udata)+
This function installs a trace callback handler. func is a Lua
+function that is called by SQLite3 just before the evaluation of an SQL
+statement. This callback receives two arguments: the first is the
+udata argument used when the callback was installed; the second is a
+string with the SQL statement about to be executed.
+
++ db:update_hook(func,udata)+
This function installs an update_hook Data Change Notification Callback handler.
+func is a Lua function that is invoked by SQLite3 whenever a row is updated,
+inserted or deleted. This callback receives five arguments: the first is the
+udata argument used when the callback was installed; the second is an
+integer indicating the operation that caused the callback to be invoked (one of sqlite3.UPDATE,
+sqlite3.INSERT, or sqlite3.DELETE). The third and fourth arguments
+are the database and table name containing the affected row. The final callback parameter is
+the rowid of the row. In the case of an update, this is the rowid after the update takes place.
See: db:commit_hook and db:rollback_hook
++
++ db:urows(sql)+
Creates an iterator that returns the successive rows selected by the SQL
+statement given in string sql. Each call to the iterator returns the
+values that correspond to the columns in the currently selected row.
+Here is an example:
+ db:exec[=[
+ CREATE TABLE numbers(num1,num2);
+ INSERT INTO numbers VALUES(1,11);
+ INSERT INTO numbers VALUES(2,22);
+ INSERT INTO numbers VALUES(3,33);
+ ]=]
+ for num1,num2 in db:urows('SELECT * FROM numbers') do print(num1,num2) end
+This script prints:
++ 1 11 + 2 22 + 3 33+
+
+After creating a prepared statement with db:prepare()
+the returned statement object should be used for all further calls in
+connection with that statement. Statement objects support the following
+methods.
+
++ stmt:bind(n[,value])+
Binds value to statement parameter n. If the type of value is string
+it is bound as text. If the type of value is number, then with Lua prior to 5.3
+it is bound as a double, with Lua 5.3 it is bound as an integer or double
+depending on its subtype using lua_isinteger. If value is a
+boolean then it is bound as 0 for false or 1 for true.
+If value is nil or missing, any previous binding is removed. The function
+returns sqlite3.OK on success or else a numerical error code (see
+Numerical error and result codes).
+
++ stmt:bind_blob(n,blob)+
Binds string blob (which can be a binary string) as a blob to
+statement parameter n. The function returns sqlite3.OK on success
+or else a numerical error code (see Numerical error and result codes).
+
++ stmt:bind_names(nametable)+
Binds the values in nametable to statement parameters. If the
+statement parameters are named (i.e., of the form ":AAA" or "$AAA")
+then this function looks for appropriately named fields in nametable;
+if the statement parameters are
+not named, it looks for numerical fields 1 to the number of statement
+parameters. The function returns sqlite3.OK on success or else a
+numerical error code (see Numerical error and result codes).
+
++ stmt:bind_parameter_count()+
Returns the largest statement parameter index in prepared statement
+stmt. When the statement parameters are of the forms ":AAA" or "?",
+then they are assigned sequentially increasing numbers beginning with
+one, so the value returned is the number of parameters. However if the
+same statement parameter name is used multiple times, each occurrence
+is given the same number, so the value returned is the number of unique
+statement parameter names.
If statement parameters of the form "?NNN" are used (where NNN is an +integer) then there might be gaps in the numbering and the value +returned by this interface is the index of the statement parameter with +the largest index value.
++
++ stmt:bind_parameter_name(n)+
Returns the name of the n-th parameter in prepared statement stmt.
+Statement parameters of the form ":AAA" or "@AAA" or "$VVV" have a name
+which is the string ":AAA" or "@AAA" or "$VVV". In other words, the
+initial ":" or "$" or "@" is included as part of the name. Parameters
+of the form "?" or "?NNN" have no name. The first bound parameter has
+an index of 1.
+If the value n is out of range or if the n-th parameter is
+nameless, then nil is returned. The function returns sqlite3.OK on
+success or else a numerical error code (see
+Numerical error and result codes)
+
++ stmt:bind_values(value1,value2,...,valueN)+
Binds the given values to statement parameters. The function returns
+sqlite3.OK on success or else a numerical error code (see
+Numerical error and result codes).
+
++ stmt:columns()+
Returns the number of columns in the result set returned by statement +stmt or 0 if the statement does not return data (for example an UPDATE).
++
++ stmt:finalize()+
This function frees prepared statement stmt. If the statement was
+executed successfully, or not executed at all, then sqlite3.OK is
+returned. If execution of the statement failed then an error code is
+returned.
+
++ stmt:get_name(n)+
Returns the name of column n in the result set of statement stmt. (The
+left-most column is number 0.)
+
++ stmt:get_named_types()+
Returns a table with the names and types of all columns in the result +set of statement stmt.
++
++ stmt:get_named_values()+
This function returns a table with names and values of all columns in +the current result row of a query.
++
++ stmt:get_names()+
This function returns an array with the names of all columns in the +result set returned by statement stmt.
++
++ stmt:get_type(n)+
Returns the type of column n in the result set of statement stmt. (The
+left-most column is number 0.)
+
++ stmt:get_types()+
This function returns an array with the types of all columns in the +result set returned by statement stmt.
++
++ stmt:get_unames()+
This function returns a list with the names of all columns in the result +set returned by statement stmt.
++
++ stmt:get_utypes()+
This function returns a list with the types of all columns in the result +set returned by statement stmt.
++
++ stmt:get_uvalues()+
This function returns a list with the values of all columns in the +current result row of a query.
++
++ stmt:get_value(n)+
Returns the value of column n in the result set of statement stmt. (The
+left-most column is number 0.)
+
++ stmt:get_values()+
This function returns an array with the values of all columns in the +result set returned by statement stmt.
++
++ stmt:isopen()+
Returns true if stmt has not yet been finalized, false otherwise.
++
++ stmt:nrows()+
Returns an function that iterates over the names and values of the
+result set of statement stmt. Each iteration returns a table with the
+names and values for the current row.
+This is the prepared statement equivalent of db:nrows().
+
++ stmt:reset()+
This function resets SQL statement stmt, so that it is ready to be
+re-executed. Any statement variables that had values bound to them using
+the stmt:bind*() functions retain their values.
+
++ stmt:rows()+
Returns an function that iterates over the values of the result set of
+statement stmt. Each iteration returns an array with the values for the
+current row.
+This is the prepared statement equivalent of db:rows().
+
++ stmt:step()+
This function must be called to evaluate the (next iteration of the) +prepared statement stmt. It will return one of the following values:
+sqlite3.BUSY: the engine was unable to acquire the locks needed. If the
+statement is a COMMIT or occurs outside of an explicit transaction, then
+you can retry the statement. If the statement is not a COMMIT and occurs
+within a explicit transaction then you should rollback the transaction
+before continuing.
sqlite3.DONE: the statement has finished executing successfully.
+stmt:step() should not be called again on this statement
+without first calling stmt:reset() to reset the virtual
+machine back to the initial state.
sqlite3.ROW: this is returned each time a new row of data is ready for
+processing by the caller. The values may be accessed using the column
+access functions. stmt:step() can be called again to
+retrieve the next row of data.
sqlite3.ERROR: a run-time error (such as a constraint violation) has
+occurred. stmt:step() should not be called again. More
+information may be found by calling db:errmsg(). A more
+specific error
+code (can be obtained by calling stmt:reset().
sqlite3.MISUSE: the function was called inappropriately, perhaps
+because the statement has already been finalized or a previous call to
+stmt:step() has returned sqlite3.ERROR or
+sqlite3.DONE.
+
++ stmt:urows()+
Returns an function that iterates over the values of the result set of
+statement stmt. Each iteration returns the values for the current row.
+This is the prepared statement equivalent of db:urows().
+
++ stmt:last_insert_rowid()+
This function returns the rowid of the most recent INSERT into the
+database corresponding to this statement.
+See db:last_insert_rowid().
+
+A callback context is available as a parameter inside the callback
+functions db:create_aggregate() and
+db:create_function(). It can be used
+to get further information about the state of a query.
+
++ context:aggregate_count()+
Returns the number of calls to the aggregate step function.
++
++ context:get_aggregate_data()+
Returns the user-definable data field for callback funtions.
++
++ context:set_aggregate_data(udata)+
Set the user-definable data field for callback funtions to udata.
+
++ context:result(res)+
This function sets the result of a callback function to res. The type of +the result depends on the type of res and is either a number or a string +or nil. All other values will raise an error message.
++
++ context:result_null()+
This function sets the result of a callback function to nil. It returns +nothing.
++
++ context:result_number(number) + context:result_double(number)+
This function sets the result of a callback function to the value
+number. It returns nothing.
+
++ context:result_int(number)+
This function sets the result of a callback function to the integer
+value in number. It returns nothing.
+
++ context:result_text(str)+
This function sets the result of a callback function to the string in
+str. It returns nothing.
+
++ context:result_blob(blob)+
This function sets the result of a callback function to the binary
+string in blob. It returns nothing.
+
++ context:result_error(err)+
This function sets the result of a callback function to the error value
+in err. It returns nothing.
+
++ context:user_data()+
Returns the userdata parameter given in the call to install the callback
+function (see db:create_aggregate() and
+db:create_function() for details).
+
+A backup userdata is created using backup =
+sqlite3.backup_init(...). It is then
+used to step the backup, or inquire about its progress.
+
++ backup:step(nPages)+
Returns the status of the backup after stepping nPages. It is called one or more
+times to transfer the data between the two databases.
backup:step(nPages) will copy up to nPages pages between the
+source and destination databases specified by backup userdata.
+If nPages is negative, all remaining source pages are copied.
+
If backup:step(nPages) successfully copies nPages pages and there
+are still more pages to be copied, then the function returns sqlite3.OK.
+If backup:step(nPages) successfully finishes copying all pages from source to
+destination, then it returns sqlite3.DONE. If an error occurs during the step, then
+an error code is returned. such as sqlite3.READONLY, sqlite3.NOMEM,
+sqlite3.BUSY, sqlite3.LOCKED, or an sqlite3.IOERR_XXX
+extended error code.
+
+
++ backup:remaining()+
Returns the number of pages still to be backed up at the conclusion of the most recent step. +
++
++ backup:pagecount()+
Returns the total number of pages in the source database at the conclusion of the most recent +step.
++
++ backup:finish()+
When backup:step(nPages) has returned sqlite3.DONE, or when the
+application wishes to abandon the backup operation, the application should destroy the backup
+by calling backup:finish(). This releases all resources associated with the backup.
+If backup:step(nPages) has not yet returned sqlite3.DONE, then any
+active write-transaction on the destination database is rolled back. After the call, the backup
+userdata corresponds to a completed backup, and should not be used.
+
The value returned by backup:finish() is sqlite3.OK if no errors
+occurred, regardless or whether or not the backup completed. If an out-of-memory condition or IO
+error occurred during any prior step on the same backup, then backup:finish()
+returns the corresponding error code.
+
A return of sqlite3.BUSY or sqlite3.LOCKED from
+backup:step(nPages) is not a permanent error and does not affect the return value
+of backup:finish().
+
+
+The following constants are defined by module sqlite3:
++ OK: 0 ERROR: 1 INTERNAL: 2 PERM: 3 ABORT: 4 + BUSY: 5 LOCKED: 6 NOMEM: 7 READONLY: 8 INTERRUPT: 9 + IOERR: 10 CORRUPT: 11 NOTFOUND: 12 FULL: 13 CANTOPEN: 14 + PROTOCOL: 15 EMPTY: 16 SCHEMA: 17 TOOBIG: 18 CONSTRAINT: 19 + MISMATCH: 20 MISUSE: 21 NOLFS: 22 FORMAT: 24 RANGE: 25 + NOTADB: 26 ROW: 100 DONE: 101+ +
plus the Authorizer Action Codes:
++ CREATE_INDEX: 1 CREATE_TABLE: 2 CREATE_TEMP_INDEX: 3 CREATE_TEMP_TABLE: 4 + CREATE_TEMP_TRIGGER: 5 CREATE_TEMP_VIEW: 6 CREATE_TRIGGER: 7 CREATE_VIEW: 8 + DELETE: 9 DROP_INDEX: 10 DROP_TABLE: 11 DROP_TEMP_INDEX: 12 + DROP_TEMP_TABLE: 13 DROP_TEMP_TRIGGER: 14 DROP_TEMP_VIEW: 15 DROP_TRIGGER: 16 + DROP_VIEW: 17 INSERT: 18 PRAGMA: 19 READ: 20 + SELECT: 21 TRANSACTION: 22 UPDATE: 23 ATTACH: 24 + DETACH: 25 ALTER_TABLE: 26 REINDEX: 27 ANALYZE: 28 + CREATE_VTABLE: 29 DROP_VTABLE: 30 FUNCTION: 31 SAVEPOINT: 32 ++
and the Open Flags:
++ OPEN_READONLY OPEN_READWRITE OPEN_CREATE OPEN_URI + OPEN_MEMORY OPEN_NOMUTEX OPEN_FULLMUTEX OPEN_SHAREDCACHE + OPEN_PRIVATECACHE ++
For details about their exact meaning please see the SQLite3 +documentation http://www.sqlite.org/.
++
+This is lsqlite3 version "0.9.4", also tagged as fsl_9x.
+
+lsqlite3 was developed by Tiago Dionizio and Doug Currie with
+contributions from Thomas Lauer, Michael Roth, and Wolfgang Oertl.
This documentation is based on the "(very) preliminary" documents +for the Idle-SQLite3 database module. Thanks to Thomas Lauer for +making it available.
++
++ /************************************************************************ + * lsqlite3 * + * Copyright (C) 2002-2016 Tiago Dionizio, Doug Currie * + * All rights reserved. * + * Author : Tiago Dionizio <tiago.dionizio@ist.utl.pt> * + * Author : Doug Currie <doug.currie@alum.mit.edu> * + * Library : lsqlite3 - an SQLite 3 database binding for Lua 5 * + * * + * Permission is hereby granted, free of charge, to any person obtaining * + * a copy of this software and associated documentation files (the * + * "Software"), to deal in the Software without restriction, including * + * without limitation the rights to use, copy, modify, merge, publish, * + * distribute, sublicense, and/or sell copies of the Software, and to * + * permit persons to whom the Software is furnished to do so, subject to * + * the following conditions: * + * * + * The above copyright notice and this permission notice shall be * + * included in all copies or substantial portions of the Software. * + * * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, * + * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * + * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.* + * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY * + * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, * + * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE * + * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. * + ************************************************************************/ ++
| URI filenames | Results +** |
|---|---|
| file:data.db | +** Open the file "data.db" in the current directory. +** |
| file:/home/fred/data.db +** file:///home/fred/data.db +** file://localhost/home/fred/data.db | +** Open the database file "/home/fred/data.db". +** |
| file://darkstar/home/fred/data.db | +** An error. "darkstar" is not a recognized authority. +** |
| +** file:///C:/Documents%20and%20Settings/fred/Desktop/data.db +** | Windows only: Open the file "data.db" on fred's desktop on drive +** C:. Note that the %20 escaping in this example is not strictly +** necessary - space characters can be used literally +** in URI filenames. +** |
| file:data.db?mode=ro&cache=private | +** Open file "data.db" in the current directory for read-only access. +** Regardless of whether or not shared-cache mode is enabled by +** default, use a private cache. +** |
| file:/home/fred/data.db?vfs=unix-dotfile | +** Open file "/home/fred/data.db". Use the special VFS "unix-dotfile" +** that uses dot-files in place of posix advisory locking. +** |
| file:data.db?mode=readonly | +** An error. "readonly" is not a valid option for the "mode" parameter. +** |
+** SELECT eval('DELETE FROM t1') FROM t2;
+** +**)^ +** +** Note that when type conversions occur, pointers returned by prior +** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or +** sqlite3_column_text16() may be invalidated. +** Type conversions and pointer invalidations might occur +** in the following cases: +** +**+**
+**Internal
TypeRequested
TypeConversion +** +** NULL INTEGER Result is 0 +** NULL FLOAT Result is 0.0 +** NULL TEXT Result is a NULL pointer +** NULL BLOB Result is a NULL pointer +** INTEGER FLOAT Convert from integer to float +** INTEGER TEXT ASCII rendering of the integer +** INTEGER BLOB Same as INTEGER->TEXT +** FLOAT INTEGER [CAST] to INTEGER +** FLOAT TEXT ASCII rendering of the float +** FLOAT BLOB [CAST] to BLOB +** TEXT INTEGER [CAST] to INTEGER +** TEXT FLOAT [CAST] to REAL +** TEXT BLOB No change +** BLOB INTEGER [CAST] to INTEGER +** BLOB FLOAT [CAST] to REAL +** BLOB TEXT Add a zero terminator if needed +**
+** LPCWSTR zPath = Windows::Storage::ApplicationData::Current->
+** TemporaryFolder->Path->Data();
+** char zPathBuf[MAX_PATH + 1];
+** memset(zPathBuf, 0, sizeof(zPathBuf));
+** WideCharToMultiByte(CP_UTF8, 0, zPath, -1, zPathBuf, sizeof(zPathBuf),
+** NULL, NULL);
+** sqlite3_temp_directory = sqlite3_mprintf("%s", zPathBuf);
+** +**)^ +** +** ^The memory pointed to by the character pointers returned for the +** declaration type and collation sequence is valid until the next +** call to any SQLite API function. +** +** ^If the specified table is actually a view, an [error code] is returned. +** +** ^If the specified column is "rowid", "oid" or "_rowid_" and the table +** is not a [WITHOUT ROWID] table and an +** [INTEGER PRIMARY KEY] column has been explicitly declared, then the output +** parameters are set for the explicitly declared column. ^(If there is no +** [INTEGER PRIMARY KEY] column, then the outputs +** for the [rowid] are set as follows: +** +**+**
+**Parameter Output
TypeDescription +** +** 5th const char* Data type +** 6th const char* Name of default collation sequence +** 7th int True if column has a NOT NULL constraint +** 8th int True if column is part of the PRIMARY KEY +** 9th int True if column is [AUTOINCREMENT] +**
+** data type: "INTEGER" +** collation sequence: "BINARY" +** not null: 0 +** primary key: 1 +** auto increment: 0 +**)^ +** +** ^This function causes all database schemas to be read from disk and +** parsed, if that has not already been done, and returns an error if +** any errors are encountered while loading the schema. +*/ +SQLITE_API int sqlite3_table_column_metadata( + sqlite3 *db, /* Connection handle */ + const char *zDbName, /* Database name or NULL */ + const char *zTableName, /* Table name */ + const char *zColumnName, /* Column name */ + char const **pzDataType, /* OUTPUT: Declared data type */ + char const **pzCollSeq, /* OUTPUT: Collation sequence name */ + int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ + int *pPrimaryKey, /* OUTPUT: True if column part of PK */ + int *pAutoinc /* OUTPUT: True if column is auto-increment */ +); + +/* +** CAPI3REF: Load An Extension +** METHOD: sqlite3 +** +** ^This interface loads an SQLite extension library from the named file. +** +** ^The sqlite3_load_extension() interface attempts to load an +** [SQLite extension] library contained in the file zFile. If +** the file cannot be loaded directly, attempts are made to load +** with various operating-system specific extensions added. +** So for example, if "samplelib" cannot be loaded, then names like +** "samplelib.so" or "samplelib.dylib" or "samplelib.dll" might +** be tried also. +** +** ^The entry point is zProc. +** ^(zProc may be 0, in which case SQLite will try to come up with an +** entry point name on its own. It first tries "sqlite3_extension_init". +** If that does not work, it constructs a name "sqlite3_X_init" where the +** X is consists of the lower-case equivalent of all ASCII alphabetic +** characters in the filename from the last "/" to the first following +** "." and omitting any initial "lib".)^ +** ^The sqlite3_load_extension() interface returns +** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. +** ^If an error occurs and pzErrMsg is not 0, then the +** [sqlite3_load_extension()] interface shall attempt to +** fill *pzErrMsg with error message text stored in memory +** obtained from [sqlite3_malloc()]. The calling function +** should free this memory by calling [sqlite3_free()]. +** +** ^Extension loading must be enabled using +** [sqlite3_enable_load_extension()] or +** [sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],1,NULL) +** prior to calling this API, +** otherwise an error will be returned. +** +** Security warning: It is recommended that the +** [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method be used to enable only this +** interface. The use of the [sqlite3_enable_load_extension()] interface +** should be avoided. This will keep the SQL function [load_extension()] +** disabled and prevent SQL injections from giving attackers +** access to extension loading capabilities. +** +** See also the [load_extension() SQL function]. +*/ +SQLITE_API int sqlite3_load_extension( + sqlite3 *db, /* Load the extension into this database connection */ + const char *zFile, /* Name of the shared library containing extension */ + const char *zProc, /* Entry point. Derived from zFile if 0 */ + char **pzErrMsg /* Put error message here if not 0 */ +); + +/* +** CAPI3REF: Enable Or Disable Extension Loading +** METHOD: sqlite3 +** +** ^So as not to open security holes in older applications that are +** unprepared to deal with [extension loading], and as a means of disabling +** [extension loading] while evaluating user-entered SQL, the following API +** is provided to turn the [sqlite3_load_extension()] mechanism on and off. +** +** ^Extension loading is off by default. +** ^Call the sqlite3_enable_load_extension() routine with onoff==1 +** to turn extension loading on and call it with onoff==0 to turn +** it back off again. +** +** ^This interface enables or disables both the C-API +** [sqlite3_load_extension()] and the SQL function [load_extension()]. +** ^(Use [sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],..) +** to enable or disable only the C-API.)^ +** +** Security warning: It is recommended that extension loading +** be disabled using the [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method +** rather than this interface, so the [load_extension()] SQL function +** remains disabled. This will prevent SQL injections from giving attackers +** access to extension loading capabilities. +*/ +SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff); + +/* +** CAPI3REF: Automatically Load Statically Linked Extensions +** +** ^This interface causes the xEntryPoint() function to be invoked for +** each new [database connection] that is created. The idea here is that +** xEntryPoint() is the entry point for a statically linked [SQLite extension] +** that is to be automatically loaded into all new database connections. +** +** ^(Even though the function prototype shows that xEntryPoint() takes +** no arguments and returns void, SQLite invokes xEntryPoint() with three +** arguments and expects an integer result as if the signature of the +** entry point where as follows: +** +**
)^ +** +** If the xEntryPoint routine encounters an error, it should make *pzErrMsg +** point to an appropriate error message (obtained from [sqlite3_mprintf()]) +** and return an appropriate [error code]. ^SQLite ensures that *pzErrMsg +** is NULL before calling the xEntryPoint(). ^SQLite will invoke +** [sqlite3_free()] on *pzErrMsg after xEntryPoint() returns. ^If any +** xEntryPoint() returns an error, the [sqlite3_open()], [sqlite3_open16()], +** or [sqlite3_open_v2()] call that provoked the xEntryPoint() will fail. +** +** ^Calling sqlite3_auto_extension(X) with an entry point X that is already +** on the list of automatic extensions is a harmless no-op. ^No entry point +** will be called more than once for each database connection that is opened. +** +** See also: [sqlite3_reset_auto_extension()] +** and [sqlite3_cancel_auto_extension()] +*/ +SQLITE_API int sqlite3_auto_extension(void(*xEntryPoint)(void)); + +/* +** CAPI3REF: Cancel Automatic Extension Loading +** +** ^The [sqlite3_cancel_auto_extension(X)] interface unregisters the +** initialization routine X that was registered using a prior call to +** [sqlite3_auto_extension(X)]. ^The [sqlite3_cancel_auto_extension(X)] +** routine returns 1 if initialization routine X was successfully +** unregistered and it returns 0 if X was not on the list of initialization +** routines. +*/ +SQLITE_API int sqlite3_cancel_auto_extension(void(*xEntryPoint)(void)); + +/* +** CAPI3REF: Reset Automatic Extension Loading +** +** ^This interface disables all automatic extensions previously +** registered using [sqlite3_auto_extension()]. +*/ +SQLITE_API void sqlite3_reset_auto_extension(void); + +/* +** The interface to the virtual-table mechanism is currently considered +** to be experimental. The interface might change in incompatible ways. +** If this is a problem for you, do not use the interface at this time. +** +** When the virtual-table mechanism stabilizes, we will declare the +** interface fixed, support it indefinitely, and remove this comment. +*/ + +/* +** Structures used by the virtual table interface +*/ +typedef struct sqlite3_vtab sqlite3_vtab; +typedef struct sqlite3_index_info sqlite3_index_info; +typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor; +typedef struct sqlite3_module sqlite3_module; + +/* +** CAPI3REF: Virtual Table Object +** KEYWORDS: sqlite3_module {virtual table module} +** +** This structure, sometimes called a "virtual table module", +** defines the implementation of a [virtual tables]. +** This structure consists mostly of methods for the module. +** +** ^A virtual table module is created by filling in a persistent +** instance of this structure and passing a pointer to that instance +** to [sqlite3_create_module()] or [sqlite3_create_module_v2()]. +** ^The registration remains valid until it is replaced by a different +** module or until the [database connection] closes. The content +** of this structure must not change while it is registered with +** any database connection. +*/ +struct sqlite3_module { + int iVersion; + int (*xCreate)(sqlite3*, void *pAux, + int argc, const char *const*argv, + sqlite3_vtab **ppVTab, char**); + int (*xConnect)(sqlite3*, void *pAux, + int argc, const char *const*argv, + sqlite3_vtab **ppVTab, char**); + int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*); + int (*xDisconnect)(sqlite3_vtab *pVTab); + int (*xDestroy)(sqlite3_vtab *pVTab); + int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor); + int (*xClose)(sqlite3_vtab_cursor*); + int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr, + int argc, sqlite3_value **argv); + int (*xNext)(sqlite3_vtab_cursor*); + int (*xEof)(sqlite3_vtab_cursor*); + int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int); + int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid); + int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *); + int (*xBegin)(sqlite3_vtab *pVTab); + int (*xSync)(sqlite3_vtab *pVTab); + int (*xCommit)(sqlite3_vtab *pVTab); + int (*xRollback)(sqlite3_vtab *pVTab); + int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName, + void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), + void **ppArg); + int (*xRename)(sqlite3_vtab *pVtab, const char *zNew); + /* The methods above are in version 1 of the sqlite_module object. Those + ** below are for version 2 and greater. */ + int (*xSavepoint)(sqlite3_vtab *pVTab, int); + int (*xRelease)(sqlite3_vtab *pVTab, int); + int (*xRollbackTo)(sqlite3_vtab *pVTab, int); +}; + +/* +** CAPI3REF: Virtual Table Indexing Information +** KEYWORDS: sqlite3_index_info +** +** The sqlite3_index_info structure and its substructures is used as part +** of the [virtual table] interface to +** pass information into and receive the reply from the [xBestIndex] +** method of a [virtual table module]. The fields under **Inputs** are the +** inputs to xBestIndex and are read-only. xBestIndex inserts its +** results into the **Outputs** fields. +** +** ^(The aConstraint[] array records WHERE clause constraints of the form: +** +**+** int xEntryPoint( +** sqlite3 *db, +** const char **pzErrMsg, +** const struct sqlite3_api_routines *pThunk +** ); +**
column OP expr+** +** where OP is =, <, <=, >, or >=.)^ ^(The particular operator is +** stored in aConstraint[].op using one of the +** [SQLITE_INDEX_CONSTRAINT_EQ | SQLITE_INDEX_CONSTRAINT_ values].)^ +** ^(The index of the column is stored in +** aConstraint[].iColumn.)^ ^(aConstraint[].usable is TRUE if the +** expr on the right-hand side can be evaluated (and thus the constraint +** is usable) and false if it cannot.)^ +** +** ^The optimizer automatically inverts terms of the form "expr OP column" +** and makes other simplifications to the WHERE clause in an attempt to +** get as many WHERE clause terms into the form shown above as possible. +** ^The aConstraint[] array only reports WHERE clause terms that are +** relevant to the particular virtual table being queried. +** +** ^Information about the ORDER BY clause is stored in aOrderBy[]. +** ^Each term of aOrderBy records a column of the ORDER BY clause. +** +** The colUsed field indicates which columns of the virtual table may be +** required by the current scan. Virtual table columns are numbered from +** zero in the order in which they appear within the CREATE TABLE statement +** passed to sqlite3_declare_vtab(). For the first 63 columns (columns 0-62), +** the corresponding bit is set within the colUsed mask if the column may be +** required by SQLite. If the table has at least 64 columns and any column +** to the right of the first 63 is required, then bit 63 of colUsed is also +** set. In other words, column iCol may be required if the expression +** (colUsed & ((sqlite3_uint64)1 << (iCol>=63 ? 63 : iCol))) evaluates to +** non-zero. +** +** The [xBestIndex] method must fill aConstraintUsage[] with information +** about what parameters to pass to xFilter. ^If argvIndex>0 then +** the right-hand side of the corresponding aConstraint[] is evaluated +** and becomes the argvIndex-th entry in argv. ^(If aConstraintUsage[].omit +** is true, then the constraint is assumed to be fully handled by the +** virtual table and is not checked again by SQLite.)^ +** +** ^The idxNum and idxPtr values are recorded and passed into the +** [xFilter] method. +** ^[sqlite3_free()] is used to free idxPtr if and only if +** needToFreeIdxPtr is true. +** +** ^The orderByConsumed means that output from [xFilter]/[xNext] will occur in +** the correct order to satisfy the ORDER BY clause so that no separate +** sorting step is required. +** +** ^The estimatedCost value is an estimate of the cost of a particular +** strategy. A cost of N indicates that the cost of the strategy is similar +** to a linear scan of an SQLite table with N rows. A cost of log(N) +** indicates that the expense of the operation is similar to that of a +** binary search on a unique indexed field of an SQLite table with N rows. +** +** ^The estimatedRows value is an estimate of the number of rows that +** will be returned by the strategy. +** +** The xBestIndex method may optionally populate the idxFlags field with a +** mask of SQLITE_INDEX_SCAN_* flags. Currently there is only one such flag - +** SQLITE_INDEX_SCAN_UNIQUE. If the xBestIndex method sets this flag, SQLite +** assumes that the strategy may visit at most one row. +** +** Additionally, if xBestIndex sets the SQLITE_INDEX_SCAN_UNIQUE flag, then +** SQLite also assumes that if a call to the xUpdate() method is made as +** part of the same statement to delete or update a virtual table row and the +** implementation returns SQLITE_CONSTRAINT, then there is no need to rollback +** any database changes. In other words, if the xUpdate() returns +** SQLITE_CONSTRAINT, the database contents must be exactly as they were +** before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not +** set and xUpdate returns SQLITE_CONSTRAINT, any database changes made by +** the xUpdate method are automatically rolled back by SQLite. +** +** IMPORTANT: The estimatedRows field was added to the sqlite3_index_info +** structure for SQLite [version 3.8.2] ([dateof:3.8.2]). +** If a virtual table extension is +** used with an SQLite version earlier than 3.8.2, the results of attempting +** to read or write the estimatedRows field are undefined (but are likely +** to included crashing the application). The estimatedRows field should +** therefore only be used if [sqlite3_libversion_number()] returns a +** value greater than or equal to 3008002. Similarly, the idxFlags field +** was added for [version 3.9.0] ([dateof:3.9.0]). +** It may therefore only be used if +** sqlite3_libversion_number() returns a value greater than or equal to +** 3009000. +*/ +struct sqlite3_index_info { + /* Inputs */ + int nConstraint; /* Number of entries in aConstraint */ + struct sqlite3_index_constraint { + int iColumn; /* Column constrained. -1 for ROWID */ + unsigned char op; /* Constraint operator */ + unsigned char usable; /* True if this constraint is usable */ + int iTermOffset; /* Used internally - xBestIndex should ignore */ + } *aConstraint; /* Table of WHERE clause constraints */ + int nOrderBy; /* Number of terms in the ORDER BY clause */ + struct sqlite3_index_orderby { + int iColumn; /* Column number */ + unsigned char desc; /* True for DESC. False for ASC. */ + } *aOrderBy; /* The ORDER BY clause */ + /* Outputs */ + struct sqlite3_index_constraint_usage { + int argvIndex; /* if >0, constraint is part of argv to xFilter */ + unsigned char omit; /* Do not code a test for this constraint */ + } *aConstraintUsage; + int idxNum; /* Number used to identify the index */ + char *idxStr; /* String, possibly obtained from sqlite3_malloc */ + int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */ + int orderByConsumed; /* True if output is already ordered */ + double estimatedCost; /* Estimated cost of using this index */ + /* Fields below are only available in SQLite 3.8.2 and later */ + sqlite3_int64 estimatedRows; /* Estimated number of rows returned */ + /* Fields below are only available in SQLite 3.9.0 and later */ + int idxFlags; /* Mask of SQLITE_INDEX_SCAN_* flags */ + /* Fields below are only available in SQLite 3.10.0 and later */ + sqlite3_uint64 colUsed; /* Input: Mask of columns used by statement */ +}; + +/* +** CAPI3REF: Virtual Table Scan Flags +*/ +#define SQLITE_INDEX_SCAN_UNIQUE 1 /* Scan visits at most 1 row */ + +/* +** CAPI3REF: Virtual Table Constraint Operator Codes +** +** These macros defined the allowed values for the +** [sqlite3_index_info].aConstraint[].op field. Each value represents +** an operator that is part of a constraint term in the wHERE clause of +** a query that uses a [virtual table]. +*/ +#define SQLITE_INDEX_CONSTRAINT_EQ 2 +#define SQLITE_INDEX_CONSTRAINT_GT 4 +#define SQLITE_INDEX_CONSTRAINT_LE 8 +#define SQLITE_INDEX_CONSTRAINT_LT 16 +#define SQLITE_INDEX_CONSTRAINT_GE 32 +#define SQLITE_INDEX_CONSTRAINT_MATCH 64 +#define SQLITE_INDEX_CONSTRAINT_LIKE 65 +#define SQLITE_INDEX_CONSTRAINT_GLOB 66 +#define SQLITE_INDEX_CONSTRAINT_REGEXP 67 + +/* +** CAPI3REF: Register A Virtual Table Implementation +** METHOD: sqlite3 +** +** ^These routines are used to register a new [virtual table module] name. +** ^Module names must be registered before +** creating a new [virtual table] using the module and before using a +** preexisting [virtual table] for the module. +** +** ^The module name is registered on the [database connection] specified +** by the first parameter. ^The name of the module is given by the +** second parameter. ^The third parameter is a pointer to +** the implementation of the [virtual table module]. ^The fourth +** parameter is an arbitrary client data pointer that is passed through +** into the [xCreate] and [xConnect] methods of the virtual table module +** when a new virtual table is be being created or reinitialized. +** +** ^The sqlite3_create_module_v2() interface has a fifth parameter which +** is a pointer to a destructor for the pClientData. ^SQLite will +** invoke the destructor function (if it is not NULL) when SQLite +** no longer needs the pClientData pointer. ^The destructor will also +** be invoked if the call to sqlite3_create_module_v2() fails. +** ^The sqlite3_create_module() +** interface is equivalent to sqlite3_create_module_v2() with a NULL +** destructor. +*/ +SQLITE_API int sqlite3_create_module( + sqlite3 *db, /* SQLite connection to register module with */ + const char *zName, /* Name of the module */ + const sqlite3_module *p, /* Methods for the module */ + void *pClientData /* Client data for xCreate/xConnect */ +); +SQLITE_API int sqlite3_create_module_v2( + sqlite3 *db, /* SQLite connection to register module with */ + const char *zName, /* Name of the module */ + const sqlite3_module *p, /* Methods for the module */ + void *pClientData, /* Client data for xCreate/xConnect */ + void(*xDestroy)(void*) /* Module destructor function */ +); + +/* +** CAPI3REF: Virtual Table Instance Object +** KEYWORDS: sqlite3_vtab +** +** Every [virtual table module] implementation uses a subclass +** of this object to describe a particular instance +** of the [virtual table]. Each subclass will +** be tailored to the specific needs of the module implementation. +** The purpose of this superclass is to define certain fields that are +** common to all module implementations. +** +** ^Virtual tables methods can set an error message by assigning a +** string obtained from [sqlite3_mprintf()] to zErrMsg. The method should +** take care that any prior string is freed by a call to [sqlite3_free()] +** prior to assigning a new string to zErrMsg. ^After the error message +** is delivered up to the client application, the string will be automatically +** freed by sqlite3_free() and the zErrMsg field will be zeroed. +*/ +struct sqlite3_vtab { + const sqlite3_module *pModule; /* The module for this virtual table */ + int nRef; /* Number of open cursors */ + char *zErrMsg; /* Error message from sqlite3_mprintf() */ + /* Virtual table implementations will typically add additional fields */ +}; + +/* +** CAPI3REF: Virtual Table Cursor Object +** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor} +** +** Every [virtual table module] implementation uses a subclass of the +** following structure to describe cursors that point into the +** [virtual table] and are used +** to loop through the virtual table. Cursors are created using the +** [sqlite3_module.xOpen | xOpen] method of the module and are destroyed +** by the [sqlite3_module.xClose | xClose] method. Cursors are used +** by the [xFilter], [xNext], [xEof], [xColumn], and [xRowid] methods +** of the module. Each module implementation will define +** the content of a cursor structure to suit its own needs. +** +** This superclass exists in order to define fields of the cursor that +** are common to all implementations. +*/ +struct sqlite3_vtab_cursor { + sqlite3_vtab *pVtab; /* Virtual table of this cursor */ + /* Virtual table implementations will typically add additional fields */ +}; + +/* +** CAPI3REF: Declare The Schema Of A Virtual Table +** +** ^The [xCreate] and [xConnect] methods of a +** [virtual table module] call this interface +** to declare the format (the names and datatypes of the columns) of +** the virtual tables they implement. +*/ +SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zSQL); + +/* +** CAPI3REF: Overload A Function For A Virtual Table +** METHOD: sqlite3 +** +** ^(Virtual tables can provide alternative implementations of functions +** using the [xFindFunction] method of the [virtual table module]. +** But global versions of those functions +** must exist in order to be overloaded.)^ +** +** ^(This API makes sure a global version of a function with a particular +** name and number of parameters exists. If no such function exists +** before this API is called, a new function is created.)^ ^The implementation +** of the new function always causes an exception to be thrown. So +** the new function is not good for anything by itself. Its only +** purpose is to be a placeholder function that can be overloaded +** by a [virtual table]. +*/ +SQLITE_API int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); + +/* +** The interface to the virtual-table mechanism defined above (back up +** to a comment remarkably similar to this one) is currently considered +** to be experimental. The interface might change in incompatible ways. +** If this is a problem for you, do not use the interface at this time. +** +** When the virtual-table mechanism stabilizes, we will declare the +** interface fixed, support it indefinitely, and remove this comment. +*/ + +/* +** CAPI3REF: A Handle To An Open BLOB +** KEYWORDS: {BLOB handle} {BLOB handles} +** +** An instance of this object represents an open BLOB on which +** [sqlite3_blob_open | incremental BLOB I/O] can be performed. +** ^Objects of this type are created by [sqlite3_blob_open()] +** and destroyed by [sqlite3_blob_close()]. +** ^The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces +** can be used to read or write small subsections of the BLOB. +** ^The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes. +*/ +typedef struct sqlite3_blob sqlite3_blob; + +/* +** CAPI3REF: Open A BLOB For Incremental I/O +** METHOD: sqlite3 +** CONSTRUCTOR: sqlite3_blob +** +** ^(This interfaces opens a [BLOB handle | handle] to the BLOB located +** in row iRow, column zColumn, table zTable in database zDb; +** in other words, the same BLOB that would be selected by: +** +**
+** SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow; +**)^ +** +** ^(Parameter zDb is not the filename that contains the database, but +** rather the symbolic name of the database. For attached databases, this is +** the name that appears after the AS keyword in the [ATTACH] statement. +** For the main database file, the database name is "main". For TEMP +** tables, the database name is "temp".)^ +** +** ^If the flags parameter is non-zero, then the BLOB is opened for read +** and write access. ^If the flags parameter is zero, the BLOB is opened for +** read-only access. +** +** ^(On success, [SQLITE_OK] is returned and the new [BLOB handle] is stored +** in *ppBlob. Otherwise an [error code] is returned and, unless the error +** code is SQLITE_MISUSE, *ppBlob is set to NULL.)^ ^This means that, provided +** the API is not misused, it is always safe to call [sqlite3_blob_close()] +** on *ppBlob after this function it returns. +** +** This function fails with SQLITE_ERROR if any of the following are true: +**
| createFlag | Behavior when page is not already in cache +** |
|---|---|
| 0 | Do not allocate a new page. Return NULL. +** |
| 1 | Allocate a new page if it easy and convenient to do so. +** Otherwise return NULL. +** |
| 2 | Make every effort to allocate a new page. Only return +** NULL if allocating a new page is effectively impossible. +** |
| Existing Change | +**New Change | +**Output Change +** |
|---|---|---|
| INSERT | INSERT | +** The new change is ignored. This case does not occur if the new +** changeset was recorded immediately after the changesets already +** added to the changegroup. +** |
| INSERT | UPDATE | +** The INSERT change remains in the changegroup. The values in the +** INSERT change are modified as if the row was inserted by the +** existing change and then updated according to the new change. +** |
| INSERT | DELETE | +** The existing INSERT is removed from the changegroup. The DELETE is +** not added. +** |
| UPDATE | INSERT | +** The new change is ignored. This case does not occur if the new +** changeset was recorded immediately after the changesets already +** added to the changegroup. +** |
| UPDATE | UPDATE | +** The existing UPDATE remains within the changegroup. It is amended +** so that the accompanying values are as if the row was updated once +** by the existing change and then again by the new change. +** |
| UPDATE | DELETE | +** The existing UPDATE is replaced by the new DELETE within the +** changegroup. +** |
| DELETE | INSERT | +** If one or more of the column values in the row inserted by the +** new change differ from those in the row deleted by the existing +** change, the existing DELETE is replaced by an UPDATE within the +** changegroup. Otherwise, if the inserted row is exactly the same +** as the deleted row, the existing DELETE is simply discarded. +** |
| DELETE | UPDATE | +** The new change is ignored. This case does not occur if the new +** changeset was recorded immediately after the changesets already +** added to the changegroup. +** |
| DELETE | DELETE | +** The new change is ignored. This case does not occur if the new +** changeset was recorded immediately after the changesets already +** added to the changegroup. +** |
| Streaming function | Non-streaming equivalent | +**
|---|---|
| sqlite3changeset_apply_str | [sqlite3changeset_apply] +** |
| sqlite3changeset_concat_str | [sqlite3changeset_concat] +** |
| sqlite3changeset_invert_str | [sqlite3changeset_invert] +** |
| sqlite3changeset_start_str | [sqlite3changeset_start] +** |
| sqlite3session_changeset_str | [sqlite3session_changeset] +** |
| sqlite3session_patchset_str | [sqlite3session_patchset] +** |
+** int nChangeset, +** void *pChangeset, +**+** +** Is replaced by: +** +**
+** int (*xInput)(void *pIn, void *pData, int *pnData), +** void *pIn, +**+** +** Each time the xInput callback is invoked by the sessions module, the first +** argument passed is a copy of the supplied pIn context pointer. The second +** argument, pData, points to a buffer (*pnData) bytes in size. Assuming no +** error occurs the xInput method should copy up to (*pnData) bytes of data +** into the buffer and set (*pnData) to the actual number of bytes copied +** before returning SQLITE_OK. If the input is completely exhausted, (*pnData) +** should be set to zero to indicate this. Or, if an error occurs, an SQLite +** error code should be returned. In all cases, if an xInput callback returns +** an error, all processing is abandoned and the streaming API function +** returns a copy of the error code to the caller. +** +** In the case of sqlite3changeset_start_strm(), the xInput callback may be +** invoked by the sessions module at any point during the lifetime of the +** iterator. If such an xInput callback returns an error, the iterator enters +** an error state, whereby all subsequent calls to iterator functions +** immediately fail with the same error code as returned by xInput. +** +** Similarly, streaming API functions that return changesets (or patchsets) +** return them in chunks by way of a callback function instead of via a +** pointer to a single large buffer. In this case, a pair of parameters such +** as: +** +**
+** int *pnChangeset, +** void **ppChangeset, +**+** +** Is replaced by: +** +**
+** int (*xOutput)(void *pOut, const void *pData, int nData), +** void *pOut +**+** +** The xOutput callback is invoked zero or more times to return data to +** the application. The first parameter passed to each call is a copy of the +** pOut pointer supplied by the application. The second parameter, pData, +** points to a buffer nData bytes in size containing the chunk of output +** data being returned. If the xOutput callback successfully processes the +** supplied data, it should return SQLITE_OK to indicate success. Otherwise, +** it should return some other SQLite error code. In this case processing +** is immediately abandoned and the streaming API function returns a copy +** of the xOutput error code to the application. +** +** The sessions module never invokes an xOutput callback with the third +** parameter set to a value less than or equal to zero. Other than this, +** no guarantees are made as to the size of the chunks of data returned. +*/ +int sqlite3changeset_apply_strm( + sqlite3 *db, /* Apply change to "main" db of this handle */ + int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */ + void *pIn, /* First arg for xInput */ + int(*xFilter)( + void *pCtx, /* Copy of sixth arg to _apply() */ + const char *zTab /* Table name */ + ), + int(*xConflict)( + void *pCtx, /* Copy of sixth arg to _apply() */ + int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */ + sqlite3_changeset_iter *p /* Handle describing change and conflict */ + ), + void *pCtx /* First argument passed to xConflict */ +); +int sqlite3changeset_concat_strm( + int (*xInputA)(void *pIn, void *pData, int *pnData), + void *pInA, + int (*xInputB)(void *pIn, void *pData, int *pnData), + void *pInB, + int (*xOutput)(void *pOut, const void *pData, int nData), + void *pOut +); +int sqlite3changeset_invert_strm( + int (*xInput)(void *pIn, void *pData, int *pnData), + void *pIn, + int (*xOutput)(void *pOut, const void *pData, int nData), + void *pOut +); +int sqlite3changeset_start_strm( + sqlite3_changeset_iter **pp, + int (*xInput)(void *pIn, void *pData, int *pnData), + void *pIn +); +int sqlite3session_changeset_strm( + sqlite3_session *pSession, + int (*xOutput)(void *pOut, const void *pData, int nData), + void *pOut +); +int sqlite3session_patchset_strm( + sqlite3_session *pSession, + int (*xOutput)(void *pOut, const void *pData, int nData), + void *pOut +); +int sqlite3changegroup_add_strm(sqlite3_changegroup*, + int (*xInput)(void *pIn, void *pData, int *pnData), + void *pIn +); +int sqlite3changegroup_output_strm(sqlite3_changegroup*, + int (*xOutput)(void *pOut, const void *pData, int nData), + void *pOut +); + + +/* +** Make sure we can call this stuff from C++. +*/ +#if 0 +} +#endif + +#endif /* !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION) */ + +/******** End of sqlite3session.h *********/ +/******** Begin file fts5.h *********/ +/* +** 2014 May 31 +** +** The author disclaims copyright to this source code. In place of +** a legal notice, here is a blessing: +** +** May you do good and not evil. +** May you find forgiveness for yourself and forgive others. +** May you share freely, never taking more than you give. +** +****************************************************************************** +** +** Interfaces to extend FTS5. Using the interfaces defined in this file, +** FTS5 may be extended with: +** +** * custom tokenizers, and +** * custom auxiliary functions. +*/ + + +#ifndef _FTS5_H +#define _FTS5_H + + +#if 0 +extern "C" { +#endif + +/************************************************************************* +** CUSTOM AUXILIARY FUNCTIONS +** +** Virtual table implementations may overload SQL functions by implementing +** the sqlite3_module.xFindFunction() method. +*/ + +typedef struct Fts5ExtensionApi Fts5ExtensionApi; +typedef struct Fts5Context Fts5Context; +typedef struct Fts5PhraseIter Fts5PhraseIter; + +typedef void (*fts5_extension_function)( + const Fts5ExtensionApi *pApi, /* API offered by current FTS version */ + Fts5Context *pFts, /* First arg to pass to pApi functions */ + sqlite3_context *pCtx, /* Context for returning result/error */ + int nVal, /* Number of values in apVal[] array */ + sqlite3_value **apVal /* Array of trailing arguments */ +); + +struct Fts5PhraseIter { + const unsigned char *a; + const unsigned char *b; +}; + +/* +** EXTENSION API FUNCTIONS +** +** xUserData(pFts): +** Return a copy of the context pointer the extension function was +** registered with. +** +** xColumnTotalSize(pFts, iCol, pnToken): +** If parameter iCol is less than zero, set output variable *pnToken +** to the total number of tokens in the FTS5 table. Or, if iCol is +** non-negative but less than the number of columns in the table, return +** the total number of tokens in column iCol, considering all rows in +** the FTS5 table. +** +** If parameter iCol is greater than or equal to the number of columns +** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g. +** an OOM condition or IO error), an appropriate SQLite error code is +** returned. +** +** xColumnCount(pFts): +** Return the number of columns in the table. +** +** xColumnSize(pFts, iCol, pnToken): +** If parameter iCol is less than zero, set output variable *pnToken +** to the total number of tokens in the current row. Or, if iCol is +** non-negative but less than the number of columns in the table, set +** *pnToken to the number of tokens in column iCol of the current row. +** +** If parameter iCol is greater than or equal to the number of columns +** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g. +** an OOM condition or IO error), an appropriate SQLite error code is +** returned. +** +** This function may be quite inefficient if used with an FTS5 table +** created with the "columnsize=0" option. +** +** xColumnText: +** This function attempts to retrieve the text of column iCol of the +** current document. If successful, (*pz) is set to point to a buffer +** containing the text in utf-8 encoding, (*pn) is set to the size in bytes +** (not characters) of the buffer and SQLITE_OK is returned. Otherwise, +** if an error occurs, an SQLite error code is returned and the final values +** of (*pz) and (*pn) are undefined. +** +** xPhraseCount: +** Returns the number of phrases in the current query expression. +** +** xPhraseSize: +** Returns the number of tokens in phrase iPhrase of the query. Phrases +** are numbered starting from zero. +** +** xInstCount: +** Set *pnInst to the total number of occurrences of all phrases within +** the query within the current row. Return SQLITE_OK if successful, or +** an error code (i.e. SQLITE_NOMEM) if an error occurs. +** +** This API can be quite slow if used with an FTS5 table created with the +** "detail=none" or "detail=column" option. If the FTS5 table is created +** with either "detail=none" or "detail=column" and "content=" option +** (i.e. if it is a contentless table), then this API always returns 0. +** +** xInst: +** Query for the details of phrase match iIdx within the current row. +** Phrase matches are numbered starting from zero, so the iIdx argument +** should be greater than or equal to zero and smaller than the value +** output by xInstCount(). +** +** Usually, output parameter *piPhrase is set to the phrase number, *piCol +** to the column in which it occurs and *piOff the token offset of the +** first token of the phrase. The exception is if the table was created +** with the offsets=0 option specified. In this case *piOff is always +** set to -1. +** +** Returns SQLITE_OK if successful, or an error code (i.e. SQLITE_NOMEM) +** if an error occurs. +** +** This API can be quite slow if used with an FTS5 table created with the +** "detail=none" or "detail=column" option. +** +** xRowid: +** Returns the rowid of the current row. +** +** xTokenize: +** Tokenize text using the tokenizer belonging to the FTS5 table. +** +** xQueryPhrase(pFts5, iPhrase, pUserData, xCallback): +** This API function is used to query the FTS table for phrase iPhrase +** of the current query. Specifically, a query equivalent to: +** +** ... FROM ftstable WHERE ftstable MATCH $p ORDER BY rowid +** +** with $p set to a phrase equivalent to the phrase iPhrase of the +** current query is executed. Any column filter that applies to +** phrase iPhrase of the current query is included in $p. For each +** row visited, the callback function passed as the fourth argument +** is invoked. The context and API objects passed to the callback +** function may be used to access the properties of each matched row. +** Invoking Api.xUserData() returns a copy of the pointer passed as +** the third argument to pUserData. +** +** If the callback function returns any value other than SQLITE_OK, the +** query is abandoned and the xQueryPhrase function returns immediately. +** If the returned value is SQLITE_DONE, xQueryPhrase returns SQLITE_OK. +** Otherwise, the error code is propagated upwards. +** +** If the query runs to completion without incident, SQLITE_OK is returned. +** Or, if some error occurs before the query completes or is aborted by +** the callback, an SQLite error code is returned. +** +** +** xSetAuxdata(pFts5, pAux, xDelete) +** +** Save the pointer passed as the second argument as the extension functions +** "auxiliary data". The pointer may then be retrieved by the current or any +** future invocation of the same fts5 extension function made as part of +** of the same MATCH query using the xGetAuxdata() API. +** +** Each extension function is allocated a single auxiliary data slot for +** each FTS query (MATCH expression). If the extension function is invoked +** more than once for a single FTS query, then all invocations share a +** single auxiliary data context. +** +** If there is already an auxiliary data pointer when this function is +** invoked, then it is replaced by the new pointer. If an xDelete callback +** was specified along with the original pointer, it is invoked at this +** point. +** +** The xDelete callback, if one is specified, is also invoked on the +** auxiliary data pointer after the FTS5 query has finished. +** +** If an error (e.g. an OOM condition) occurs within this function, an +** the auxiliary data is set to NULL and an error code returned. If the +** xDelete parameter was not NULL, it is invoked on the auxiliary data +** pointer before returning. +** +** +** xGetAuxdata(pFts5, bClear) +** +** Returns the current auxiliary data pointer for the fts5 extension +** function. See the xSetAuxdata() method for details. +** +** If the bClear argument is non-zero, then the auxiliary data is cleared +** (set to NULL) before this function returns. In this case the xDelete, +** if any, is not invoked. +** +** +** xRowCount(pFts5, pnRow) +** +** This function is used to retrieve the total number of rows in the table. +** In other words, the same value that would be returned by: +** +** SELECT count(*) FROM ftstable; +** +** xPhraseFirst() +** This function is used, along with type Fts5PhraseIter and the xPhraseNext +** method, to iterate through all instances of a single query phrase within +** the current row. This is the same information as is accessible via the +** xInstCount/xInst APIs. While the xInstCount/xInst APIs are more convenient +** to use, this API may be faster under some circumstances. To iterate +** through instances of phrase iPhrase, use the following code: +** +** Fts5PhraseIter iter; +** int iCol, iOff; +** for(pApi->xPhraseFirst(pFts, iPhrase, &iter, &iCol, &iOff); +** iCol>=0; +** pApi->xPhraseNext(pFts, &iter, &iCol, &iOff) +** ){ +** // An instance of phrase iPhrase at offset iOff of column iCol +** } +** +** The Fts5PhraseIter structure is defined above. Applications should not +** modify this structure directly - it should only be used as shown above +** with the xPhraseFirst() and xPhraseNext() API methods (and by +** xPhraseFirstColumn() and xPhraseNextColumn() as illustrated below). +** +** This API can be quite slow if used with an FTS5 table created with the +** "detail=none" or "detail=column" option. If the FTS5 table is created +** with either "detail=none" or "detail=column" and "content=" option +** (i.e. if it is a contentless table), then this API always iterates +** through an empty set (all calls to xPhraseFirst() set iCol to -1). +** +** xPhraseNext() +** See xPhraseFirst above. +** +** xPhraseFirstColumn() +** This function and xPhraseNextColumn() are similar to the xPhraseFirst() +** and xPhraseNext() APIs described above. The difference is that instead +** of iterating through all instances of a phrase in the current row, these +** APIs are used to iterate through the set of columns in the current row +** that contain one or more instances of a specified phrase. For example: +** +** Fts5PhraseIter iter; +** int iCol; +** for(pApi->xPhraseFirstColumn(pFts, iPhrase, &iter, &iCol); +** iCol>=0; +** pApi->xPhraseNextColumn(pFts, &iter, &iCol) +** ){ +** // Column iCol contains at least one instance of phrase iPhrase +** } +** +** This API can be quite slow if used with an FTS5 table created with the +** "detail=none" option. If the FTS5 table is created with either +** "detail=none" "content=" option (i.e. if it is a contentless table), +** then this API always iterates through an empty set (all calls to +** xPhraseFirstColumn() set iCol to -1). +** +** The information accessed using this API and its companion +** xPhraseFirstColumn() may also be obtained using xPhraseFirst/xPhraseNext +** (or xInst/xInstCount). The chief advantage of this API is that it is +** significantly more efficient than those alternatives when used with +** "detail=column" tables. +** +** xPhraseNextColumn() +** See xPhraseFirstColumn above. +*/ +struct Fts5ExtensionApi { + int iVersion; /* Currently always set to 3 */ + + void *(*xUserData)(Fts5Context*); + + int (*xColumnCount)(Fts5Context*); + int (*xRowCount)(Fts5Context*, sqlite3_int64 *pnRow); + int (*xColumnTotalSize)(Fts5Context*, int iCol, sqlite3_int64 *pnToken); + + int (*xTokenize)(Fts5Context*, + const char *pText, int nText, /* Text to tokenize */ + void *pCtx, /* Context passed to xToken() */ + int (*xToken)(void*, int, const char*, int, int, int) /* Callback */ + ); + + int (*xPhraseCount)(Fts5Context*); + int (*xPhraseSize)(Fts5Context*, int iPhrase); + + int (*xInstCount)(Fts5Context*, int *pnInst); + int (*xInst)(Fts5Context*, int iIdx, int *piPhrase, int *piCol, int *piOff); + + sqlite3_int64 (*xRowid)(Fts5Context*); + int (*xColumnText)(Fts5Context*, int iCol, const char **pz, int *pn); + int (*xColumnSize)(Fts5Context*, int iCol, int *pnToken); + + int (*xQueryPhrase)(Fts5Context*, int iPhrase, void *pUserData, + int(*)(const Fts5ExtensionApi*,Fts5Context*,void*) + ); + int (*xSetAuxdata)(Fts5Context*, void *pAux, void(*xDelete)(void*)); + void *(*xGetAuxdata)(Fts5Context*, int bClear); + + int (*xPhraseFirst)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*, int*); + void (*xPhraseNext)(Fts5Context*, Fts5PhraseIter*, int *piCol, int *piOff); + + int (*xPhraseFirstColumn)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*); + void (*xPhraseNextColumn)(Fts5Context*, Fts5PhraseIter*, int *piCol); +}; + +/* +** CUSTOM AUXILIARY FUNCTIONS +*************************************************************************/ + +/************************************************************************* +** CUSTOM TOKENIZERS +** +** Applications may also register custom tokenizer types. A tokenizer +** is registered by providing fts5 with a populated instance of the +** following structure. All structure methods must be defined, setting +** any member of the fts5_tokenizer struct to NULL leads to undefined +** behaviour. The structure methods are expected to function as follows: +** +** xCreate: +** This function is used to allocate and initialize a tokenizer instance. +** A tokenizer instance is required to actually tokenize text. +** +** The first argument passed to this function is a copy of the (void*) +** pointer provided by the application when the fts5_tokenizer object +** was registered with FTS5 (the third argument to xCreateTokenizer()). +** The second and third arguments are an array of nul-terminated strings +** containing the tokenizer arguments, if any, specified following the +** tokenizer name as part of the CREATE VIRTUAL TABLE statement used +** to create the FTS5 table. +** +** The final argument is an output variable. If successful, (*ppOut) +** should be set to point to the new tokenizer handle and SQLITE_OK +** returned. If an error occurs, some value other than SQLITE_OK should +** be returned. In this case, fts5 assumes that the final value of *ppOut +** is undefined. +** +** xDelete: +** This function is invoked to delete a tokenizer handle previously +** allocated using xCreate(). Fts5 guarantees that this function will +** be invoked exactly once for each successful call to xCreate(). +** +** xTokenize: +** This function is expected to tokenize the nText byte string indicated +** by argument pText. pText may or may not be nul-terminated. The first +** argument passed to this function is a pointer to an Fts5Tokenizer object +** returned by an earlier call to xCreate(). +** +** The second argument indicates the reason that FTS5 is requesting +** tokenization of the supplied text. This is always one of the following +** four values: +** +**