capi3ref.html

嵌入式数据库sqlite 3.5.9的文档

<a href="#sqlite3_value_blob">sqlite3_value_text</a></li>
<li>
<a href="#sqlite3_value_blob">sqlite3_value_text16</a></li>
<li>
<a href="#sqlite3_value_blob">sqlite3_value_text16be</a></li>
<li>
<a href="#sqlite3_value_blob">sqlite3_value_text16le</a></li>
<li>
<a href="#sqlite3_value_blob">sqlite3_value_type</a></li>
<li>
<a href="#sqlite3_libversion">sqlite3_version</a></li>
<li>
<a href="#sqlite3_vfs_find">sqlite3_vfs_find</a></li>
<li>
<a href="#sqlite3_vfs_find">sqlite3_vfs_register</a></li>
<li>
<a href="#sqlite3_vfs_find">sqlite3_vfs_unregister</a></li>
<li>
<a href="#sqlite3_mprintf">sqlite3_vmprintf</a></li>
</ul></td>
</tr></table>
<hr>
<a name="sqlite3_index_info"></a>
<h2>Virtual Table Indexing Information</h2>
<blockquote><pre>
struct sqlite3_index_info {
  /* Inputs */
  int nConstraint;           /* Number of entries in aConstraint */
  struct sqlite3_index_constraint {
     int iColumn;              /* Column on left-hand side of constraint */
     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 */

</pre></blockquote>
<p>
The sqlite3_index_info structure and its substructures is used to
pass information into and receive the reply from the xBestIndex
method of an sqlite3_module.  The fields under **Inputs** are the
inputs to xBestIndex and are read-only.  xBestIndex inserts its
results into the **Outputs** fields.</p>

<p>The aConstraint
[]
 array records WHERE clause constraints of the
form:</p>

<p>column OP expr</p>

<p>Where OP is =, &lt;, &lt;=, &gt;, or &gt;=.
The particular operator is stored
in aConstraint
[]
.op.  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.</p>

<p>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 in the correct
form that refer to the particular virtual table being queried.</p>

<p>Information about the ORDER BY clause is stored in aOrderBy
[]
.
Each term of aOrderBy records a column of the ORDER BY clause.</p>

<p>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.</p>

<p>The idxNum and idxPtr values are recorded and passed into xFilter.
sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true.</p>

<p>The orderByConsumed means that output from xFilter will occur in
the correct order to satisfy the ORDER BY clause so that no separate
sorting step is required.</p>

<p>The estimatedCost value is an estimate of the cost of doing the
particular lookup.  A full scan of a table with N entries should have
a cost of N.  A binary search of a table of N entries should have a
cost of approximately log(N).
</p>
<hr>
<a name="sqlite3_module"></a>
<h2>Virtual Table Object</h2>
<blockquote><pre>
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);

</pre></blockquote>
<p>
A module is a class of virtual tables.  Each module is defined
by an instance of the following structure.  This structure consists
mostly of methods for the module.
</p>
<hr>
<a name="sqlite3_vtab"></a>
<h2>Virtual Table Instance Object</h2>
<blockquote><pre>
struct sqlite3_vtab {
  const sqlite3_module *pModule;  /* The module for this virtual table */
  int nRef;                       /* Used internally */
  char *zErrMsg;                  /* Error message from sqlite3_mprintf() */
  /* Virtual table implementations will typically add additional fields */
};

</pre></blockquote>
<p>
Every module implementation uses a subclass of the following structure
to describe a particular instance of the module.  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.</p>

<p>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.  Note
that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field
since virtual tables are commonly implemented in loadable extensions which
do not have access to sqlite3MPrintf() or sqlite3Free().
</p>
<hr>
<a name="sqlite3_vtab_cursor"></a>
<h2>Virtual Table Cursor Object</h2>
<blockquote><pre>
struct sqlite3_vtab_cursor {
  sqlite3_vtab *pVtab;      /* Virtual table of this cursor */
  /* Virtual table implementations will typically add additional fields */
};

</pre></blockquote>
<p>
Every 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
xOpen method of the module.  Each module implementation will define
the content of a cursor structure to suit its own needs.</p>

<p>This superclass exists in order to define fields of the cursor that
are common to all implementations.
</p>
<hr>
<a name="SQLITE_FCNTL_LOCKSTATE"></a>
<h2>Standard File Control Opcodes</h2>
<blockquote><pre>
#define SQLITE_FCNTL_LOCKSTATE        1

</pre></blockquote>
<p>
These integer constants are opcodes for the xFileControl method
of the 
<a href="#sqlite3_io_methods">sqlite3_io_methods</a> object and to the 
<a href="#sqlite3_file_control">sqlite3_file_control()</a>
interface.</p>

<p>The 
<a href="#SQLITE_FCNTL_LOCKSTATE">SQLITE_FCNTL_LOCKSTATE</a> opcode is used for debugging.  This
opcode causes the xFileControl method to write the current state of
the lock (one of 
<a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_NONE</a>, 
<a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_SHARED</a>,

<a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_RESERVED</a>, 
<a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_PENDING</a>, or 
<a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_EXCLUSIVE</a>)
into an integer that the pArg argument points to. This capability
is used during testing and only needs to be supported when SQLITE_TEST
is defined.
</p>
<hr>
<a name="sqlite3_blob"></a>
<h2>A Handle To An Open BLOB</h2>
<blockquote><pre>
typedef struct sqlite3_blob sqlite3_blob;

</pre></blockquote>
<p>
An instance of this object represents an open BLOB on which
incremental I/O can be preformed.
Objects of this type are created by

<a href="#sqlite3_blob_open">sqlite3_blob_open()</a> and destroyed by 
<a href="#sqlite3_blob_close">sqlite3_blob_close()</a>.
The 
<a href="#sqlite3_blob_read">sqlite3_blob_read()</a> and 
<a href="#sqlite3_blob_write">sqlite3_blob_write()</a> interfaces
can be used to read or write small subsections of the blob.
The 
<a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a> interface returns the size of the
blob in bytes.
</p>
<hr>
<a name="sqlite3_context"></a>
<h2>SQL Function Context Object</h2>
<blockquote><pre>
typedef struct sqlite3_context sqlite3_context;

</pre></blockquote>
<p>
The context in which an SQL function executes is stored in an
sqlite3_context object.  A pointer to an sqlite3_context
object is always first parameter to application-defined SQL functions.
</p>
<hr>
<a name="sqlite3_file"></a>
<h2>OS Interface Open File Handle</h2>
<blockquote><pre>
typedef struct sqlite3_file sqlite3_file;
struct sqlite3_file {
  const struct sqlite3_io_methods *pMethods;  /* Methods for an open file */
};

</pre></blockquote>
<p>
An 
<a href="#sqlite3_file">sqlite3_file</a> object represents an open file in the OS
interface layer.  Individual OS interface implementations will
want to subclass this object by appending additional fields
for their own use.  The pMethods entry is a pointer to an

<a href="#sqlite3_io_methods">sqlite3_io_methods</a> object that defines methods for performing
I/O operations on the open file.
</p>
<hr>
<a name="sqlite3_io_methods"></a>
<h2>OS Interface File Virtual Methods Object</h2>
<blockquote><pre>
typedef struct sqlite3_io_methods sqlite3_io_methods;
struct sqlite3_io_methods {
  int iVersion;
  int (*xClose)(sqlite3_file*);
  int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
  int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
  int (*xSync)(sqlite3_file*, int flags);
  int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
  int (*xLock)(sqlite3_file*, int);
  int (*xUnlock)(sqlite3_file*, int);
  int (*xCheckReservedLock)(sqlite3_file*);
  int (*xFileControl)(sqlite3_file*, int op, void *pArg);
  int (*xSectorSize)(sqlite3_file*);
  int (*xDeviceCharacteristics)(sqlite3_file*);
  /* Additional methods may be added in future releases */
};

</pre></blockquote>
<p>
Every file opened by the 
<a href="#sqlite3_vfs">sqlite3_vfs</a> xOpen method contains a pointer to
an instance of this object.  This object defines the
methods used to perform various operations against the open file.</p>

<p>The flags argument to xSync may be one of 
<a href="#SQLITE_SYNC_DATAONLY">SQLITE_SYNC_NORMAL</a> or

<a href="#SQLITE_SYNC_DATAONLY">SQLITE_SYNC_FULL</a>.  The first choice is the normal fsync().
OS-X style fullsync.  The SQLITE_SYNC_DATA flag may be ORed in to
indicate that only the data of the file and not its inode needs to be
synced.</p>

<p>The integer values to xLock() and xUnlock() are one of
<ul>
<li> 
<a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_NONE</a>,
<li> 
<a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_SHARED</a>,
<li> 
<a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_RESERVED</a>,
<li> 
<a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_PENDING</a>, or
<li> 
<a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_EXCLUSIVE</a>.
</ul>
xLock() increases the lock. xUnlock() decreases the lock.
The xCheckReservedLock() method looks
to see if any database connection, either in this
process or in some other process, is holding an RESERVED,
PENDING, or EXCLUSIVE lock on the file.  It returns true
if such a lock exists and false if not.</p>

<p>The xFileControl() method is a generic interface that allows custom
VFS implementations to directly control an open file using the

<a href="#sqlite3_file_control">sqlite3_file_control()</a> interface.  The second "op" argument
is an integer opcode.   The third
argument is a generic pointer which is intended to be a pointer
to a structure that may contain arguments or space in which to
write return values.  Potential uses for xFileControl() might be
functions to enable blocking locks with timeouts, to change the
locking strategy (for example to use dot-file locks), to inquire
about the status of a lock, or to break stale locks.  The SQLite
core reserves opcodes less than 100 for its own use.
A 
<a href="#SQLITE_FCNTL_LOCKSTATE">list of opcodes</a> less than 100 is available.
Applications that define a custom xFileControl method should use opcodes
greater than 100 to avoid conflicts.</p>

<p>The xSectorSize() method returns the sector size of the
device that underlies the file.  The sector size is the
minimum write that can be performed without disturbing
other bytes in the file.  The xDeviceCharacteristics()
method returns a bit vector describing behaviors of the
underlying device:</p>

<p><ul>
<li> 
<a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC</a>
<li> 
<a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC512</a>
<li> 
<a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC1K</a>
<li> 
<a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC2K</a>
<li> 
<a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC4K</a>
<li> 
<a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC8K</a>
<li> 
<a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC16K</a>
<li> 
<a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC32K</a>
<li> 
<a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC64K</a>
<li> 
<a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_SAFE_APPEND</a>
<li> 
<a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_SEQUENTIAL</a>