capi3ref.html

这是sqlite3.56的文档。拿来给大家阅读使用

method returns a Julian Day Number for the current date and
time.
</p>
<hr>
<a name="sqlite3_aggregate_context"></a>
<h2>Obtain Aggregate Function Context</h2>
<blockquote><pre>
void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);

</pre></blockquote>
<p>
The implementation of aggregate SQL functions use this routine to allocate
a structure for storing their state.
 The first time the sqlite3_aggregate_context() routine is
is called for a particular aggregate, SQLite allocates nBytes of memory
zeros that memory, and returns a pointer to it.
 On second and subsequent calls to sqlite3_aggregate_context()
for the same aggregate function index, the same buffer is returned.
The implementation
of the aggregate can use the returned buffer to accumulate data.</p>

<p> SQLite automatically frees the allocated buffer when the aggregate
query concludes.</p>

<p>The first parameter should be a copy of the

<a href="#sqlite3_context">SQL function context</a> that is the first
parameter to the callback routine that implements the aggregate
function.</p>

<p>This routine must be called from the same thread in which
the aggregate SQL function is running.
</p>
<hr>
<a name="sqlite3_auto_extension"></a>
<h2>Make Arrangements To Automatically Load An Extension</h2>
<blockquote><pre>
int sqlite3_auto_extension(void *xEntryPoint);

</pre></blockquote>
<p>
 This function
registers an extension entry point that is automatically invoked
whenever a new database connection is opened using

<a href="#sqlite3_open">sqlite3_open()</a>, 
<a href="#sqlite3_open">sqlite3_open16()</a>, or 
<a href="#sqlite3_open">sqlite3_open_v2()</a>.</p>

<p>This API can be invoked at program startup in order to register
one or more statically linked extensions that will be available
to all new database connections.</p>

<p> Duplicate extensions are detected so calling this routine multiple
times with the same extension is harmless.</p>

<p> This routine stores a pointer to the extension in an array
that is obtained from sqlite_malloc(). If you run a memory leak
checker on your program and it reports a leak because of this
array, then invoke 
<a href="#sqlite3_reset_auto_extension">sqlite3_reset_auto_extension()</a> prior
to shutdown to free the memory.</p>

<p> Automatic extensions apply across all threads.</p>

<p>This interface is experimental and is subject to change or
removal in future releases of SQLite.
</p>
<hr>
<a name="sqlite3_bind_parameter_count"></a>
<h2>Number Of SQL Parameters</h2>
<blockquote><pre>
int sqlite3_bind_parameter_count(sqlite3_stmt*);

</pre></blockquote>
<p>
This routine can be used to find the number of SQL parameters
in a prepared statement.  SQL parameters are tokens of the
form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
place-holders for values that are 
<a href="#sqlite3_bind_blob">bound</a>
to the parameters at a later time.</p>

<p>This routine actually returns the index of the largest parameter.
For all forms except ?NNN, this will correspond to the number of
unique parameters.  If parameters of the ?NNN are used, there may
be gaps in the list.</p>

<p>See also: 
<a href="#sqlite3_bind_blob">sqlite3_bind()</a>,

<a href="#sqlite3_bind_parameter_name">sqlite3_bind_parameter_name()</a>, and

<a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index()</a>.</p>

<p><h3>Invariants:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">F13601</td> 
<td valign="top">
The 
<a href="#sqlite3_bind_parameter_count">sqlite3_bind_parameter_count(S)</a> interface returns
the largest index of all SQL parameters in the

<a href="#sqlite3_stmt">prepared statement</a> S, or 0 if S
contains no SQL parameters.</td></tr>
</table>
</p>
<hr>
<a name="sqlite3_bind_parameter_index"></a>
<h2>Index Of A Parameter With A Given Name</h2>
<blockquote><pre>
int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);

</pre></blockquote>
<p>
Return the index of an SQL parameter given its name.  The
index value returned is suitable for use as the second
parameter to 
<a href="#sqlite3_bind_blob">sqlite3_bind()</a>.  A zero
is returned if no matching parameter is found.  The parameter
name must be given in UTF-8 even if the original statement
was prepared from UTF-16 text using 
<a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a>.</p>

<p>See also: 
<a href="#sqlite3_bind_blob">sqlite3_bind()</a>,

<a href="#sqlite3_bind_parameter_count">sqlite3_bind_parameter_count()</a>, and

<a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index()</a>.</p>

<p><h3>Invariants:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">F13641</td> 
<td valign="top">
The 
<a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index(S,N)</a> interface returns
the index of SQL parameter in 
<a href="#sqlite3_stmt">prepared statement</a>
S whose name matches the UTF-8 string N, or 0 if there is
no match.</td></tr>
</table>
</p>
<hr>
<a name="sqlite3_bind_parameter_name"></a>
<h2>Name Of A Host Parameter</h2>
<blockquote><pre>
const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);

</pre></blockquote>
<p>
This routine returns a pointer to the name of the n-th
SQL parameter in a 
<a href="#sqlite3_stmt">prepared statement</a>.
SQL parameters of the form ":AAA" or "@AAA" or "$AAA" 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.</p>

<p>The first host parameter has an index of 1, not 0.</p>

<p>If the value n is out of range or if the n-th parameter is
nameless, then NULL is returned.  The returned string is
always in the UTF-8 encoding even if the named parameter was
originally specified as UTF-16 in 
<a href="#sqlite3_prepare">sqlite3_prepare16()</a> or

<a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a>.</p>

<p>See also: 
<a href="#sqlite3_bind_blob">sqlite3_bind()</a>,

<a href="#sqlite3_bind_parameter_count">sqlite3_bind_parameter_count()</a>, and

<a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index()</a>.</p>

<p><h3>Invariants:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">F13621</td> 
<td valign="top">
The 
<a href="#sqlite3_bind_parameter_name">sqlite3_bind_parameter_name(S,N)</a> interface returns
a UTF-8 rendering of the name of the SQL parameter in

<a href="#sqlite3_stmt">prepared statement</a> S having index N, or
NULL if there is no SQL parameter with index N or if the
parameter with index N is an anonymous parameter "?" or
a numbered parameter "?NNN".</td></tr>
</table>
</p>
<hr>
<a name="sqlite3_blob_bytes"></a>
<h2>Return The Size Of An Open BLOB</h2>
<blockquote><pre>
int sqlite3_blob_bytes(sqlite3_blob *);

</pre></blockquote>
<p>
 Return the size in bytes of the blob accessible via the open

<a href="#sqlite3_blob">blob-handle</a> passed as an argument.
</p>
<hr>
<a name="sqlite3_blob_close"></a>
<h2>Close A BLOB Handle</h2>
<blockquote><pre>
int sqlite3_blob_close(sqlite3_blob *);

</pre></blockquote>
<p>
Close an open 
<a href="#sqlite3_blob">blob handle</a>.</p>

<p> Closing a BLOB shall cause the current transaction to commit
if there are no other BLOBs, no pending prepared statements, and the
database connection is in autocommit mode.
 If any writes were made to the BLOB, they might be held in cache
until the close operation if they will fit.
Closing the BLOB often forces the changes
out to disk and so if any I/O errors occur, they will likely occur
at the time when the BLOB is closed. Any errors that occur during
closing are reported as a non-zero return value.</p>

<p> The BLOB is closed unconditionally.  Even if this routine returns
an error code, the BLOB is still closed.
</p>
<hr>
<a name="sqlite3_blob_open"></a>
<h2>Open A BLOB For Incremental I/O</h2>
<blockquote><pre>
int sqlite3_blob_open(
  sqlite3*,
  const char *zDb,
  const char *zTable,
  const char *zColumn,
  sqlite3_int64 iRow,
  int flags,
  sqlite3_blob **ppBlob
);

</pre></blockquote>
<p>
 This interfaces opens a 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:</p>

<p><pre>
SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;
</pre></p>

<p> If the flags parameter is non-zero, the blob is opened for
read and write access. If it is zero, the blob is opened for read
access.</p>

<p> On success, 
<a href="#SQLITE_ABORT">SQLITE_OK</a> is returned and the new

<a href="#sqlite3_blob">blob handle</a> is written to *ppBlob.
 Otherwise an error code is returned and
any value written to *ppBlob should not be used by the caller.
 This function sets the database-handle error code and message
accessible via 
<a href="#sqlite3_errcode">sqlite3_errcode()</a> and 
<a href="#sqlite3_errcode">sqlite3_errmsg()</a>.
<font color="red">(TODO: We should go through and mark all interfaces that behave this
way with a similar statement)</font>
</p>
<hr>
<a name="sqlite3_blob_read"></a>
<h2>Read Data From A BLOB Incrementally</h2>
<blockquote><pre>
int sqlite3_blob_read(sqlite3_blob *, void *z, int n, int iOffset);

</pre></blockquote>
<p>
This function is used to read data from an open

<a href="#sqlite3_blob">blob-handle</a> into a caller supplied buffer.
 n bytes of data are copied into buffer
z from the open blob, starting at offset iOffset.</p>

<p> If offset iOffset is less than n bytes from the end of the blob,

<a href="#SQLITE_ABORT">SQLITE_ERROR</a> is returned and no data is read. If n is
less than zero 
<a href="#SQLITE_ABORT">SQLITE_ERROR</a> is returned and no data is read.</p>

<p> On success, SQLITE_OK is returned. Otherwise, an

<a href="#SQLITE_ABORT">error code</a> or an 
<a href="#SQLITE_IOERR_BLOCKED">extended error code</a> is returned.
</p>
<hr>
<a name="sqlite3_blob_write"></a>
<h2>Write Data Into A BLOB Incrementally</h2>
<blockquote><pre>
int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);

</pre></blockquote>
<p>
This function is used to write data into an open

<a href="#sqlite3_blob">blob-handle</a> from a user supplied buffer.
 n bytes of data are copied from the buffer
pointed to by z into the open blob, starting at offset iOffset.</p>

<p> If the 
<a href="#sqlite3_blob">blob-handle</a> passed as the first argument
was not opened for writing (the flags parameter to 
<a href="#sqlite3_blob_open">sqlite3_blob_open()</a>
was zero), this function returns 
<a href="#SQLITE_ABORT">SQLITE_READONLY</a>.</p>

<p> This function may only modify the contents of the blob; it is
not possible to increase the size of a blob using this API.
 If offset iOffset is less than n bytes from the end of the blob,

<a href="#SQLITE_ABORT">SQLITE_ERROR</a> is returned and no data is written. If n is
less than zero 
<a href="#SQLITE_ABORT">SQLITE_ERROR</a> is returned and no data is written.</p>

<p> On success, SQLITE_OK is returned. Otherwise, an

<a href="#SQLITE_ABORT">error code</a> or an 
<a href="#SQLITE_IOERR_BLOCKED">extended error code</a> is returned.
</p>
<hr>
<a name="sqlite3_busy_handler"></a>
<h2>Register A Callback To Handle SQLITE_BUSY Errors</h2>
<blockquote><pre>
int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);

</pre></blockquote>
<p>
This routine identifies a callback function that might be
invoked whenever an attempt is made to open a database table
that another thread or process has locked.
If the busy callback is NULL, then 
<a href="#SQLITE_ABORT">SQLITE_BUSY</a>
or 
<a href="#SQLITE_IOERR_BLOCKED">SQLITE_IOERR_BLOCKED</a>
is returned immediately upon encountering the lock.
If the busy callback is not NULL, then the
callback will be invoked with two arguments.  The
first argument to the handler is a copy of the void* pointer which
is the third argument to this routine.  The second argument to
the handler is the number of times that the busy handler has
been invoked for this locking event.   If the
busy callback returns 0, then no additional attempts are made to
access the database and 
<a href="#SQLITE_ABORT">SQLITE_BUSY</a> or 
<a href="#SQLITE_IOERR_BLOCKED">SQLITE_IOERR_BLOCKED</a> is returned.
If the callback returns non-zero, then another attempt
is made to open the database for reading and the cycle repeats.</p>

<p>The presence of a busy handler does not guarantee that
it will be invoked when there is lock contention.
If SQLite determines that invoking the busy handler could result in
a deadlock, it will go ahead and return 
<a href="#SQLITE_ABORT">SQLITE_BUSY</a> or

<a href="#SQLITE_IOERR_BLOCKED">SQLITE_IOERR_BLOCKED</a> instead of invoking the
busy handler.
Consider a scenario where one process is holding a read lock that
it is trying to promote to a reserved lock and
a second process is holding a reserved lock that it is trying
to promote to an exclusive lock.  The first process cannot proceed
because it is blocked by the second and the second process cannot
proceed because it is blocked by the first.  If both processes
invoke the busy handlers, neither will make any progress.  Therefore,
SQLite returns 
<a href="#SQLITE_ABORT">SQLITE_BUSY</a> for the first process, hoping that this
will induce the first process to release its read lock and allow
the second process to proceed.</p>

<p>The default busy callback is NULL.</p>

<p>The 
<a href="#SQLITE_ABORT">SQLITE_BUSY</a> error is converted to 
<a href="#SQLITE_IOERR_BLOCKED">SQLITE_IOERR_BLOCKED</a>