Updates to the C-language API documents for version 3.0. (CVS 1840)

FossilOrigin-Name: 814c58d470922d77cfcc6c4d5d26c1ec4c28ca60

manifest

@@ -1,5 +1,5 @@
-C Minor\scoding\senhancements.\s(CVS\s1839)
+C Updates\sto\sthe\sC-language\sAPI\sdocuments\sfor\sversion\s3.0.\s(CVS\s1840)
-D 2004-07-21T02:53:30
+D 2004-07-21T14:07:58
 F Makefile.in 4a5e570a9e2d35b09c31b3cf01b78cea764ade4b
 F Makefile.linux-gcc a9e5a0d309fa7c38e7c14d3ecf7690879d3a5457
 F README f1de682fbbd94899d50aca13d387d1b3fd3be2dd
@@ -206,7 +206,7 @@ F www/arch2.gif 49c6bb36160f03ca2b89eaa5bfb1f560c7d68ee7
 F www/audit.tcl 90e09d580f79c7efec0c7d6f447b7ec5c2dce5c0
 F www/c_interface.tcl 2176519fc2bd2d2cf6fe74fd806fc2d8362de2c8
 F www/capi3.tcl 5c1cb163f4d2a54e2d0e22dcc399dd71245c8b89
-F www/capi3ref.tcl ae6c0ed88f601119c15de964b7b4b2f8c9b05831
+F www/capi3ref.tcl 32371dc2c0816a0ee6b3b3396852243e4da9bf86
 F www/changes.tcl 536d9919db834ad545dc8c3820105e613b092394
 F www/common.tcl f786e6be86fb2627ceb30e770e9efa83b9c67a3a
 F www/conflict.tcl fb8a2ba83746c7fdfd9e52fa7f6aaf5c422b8246
@@ -237,7 +237,7 @@ F www/tclsqlite.tcl 19191cf2a1010eaeff74c51d83fd5f5a4d899075
 F www/vdbe.tcl 59288db1ac5c0616296b26dce071c36cb611dfe9
 F www/version3.tcl 092a01f5ef430d2c4acc0ae558d74c4bb89638a0
 F www/whentouse.tcl a8335bce47cc2fddb07f19052cb0cb4d9129a8e4
-P ec8bfa3891dbf0f3172e31cf322974c03f9af59a
+P 65c3af74c16c9fe0341b1e7e6d029927503f7404
-R 9e5a169fd77b5347506f033f7c0bac3e
+R 86f621dbcf22f7ac329aac2fafa03b69
 U drh
-Z 16e953d85e2aa59a57853642a9ecf96b
+Z 622f440ec16a414813d23dde7141b3ba

manifest.uuid

@@ -1 +1 @@
-65c3af74c16c9fe0341b1e7e6d029927503f7404
+814c58d470922d77cfcc6c4d5d26c1ec4c28ca60

www/capi3ref.tcl

@@ -1,4 +1,4 @@
-set rcsid {$Id: capi3ref.tcl,v 1.5 2004/06/19 08:18:27 danielk1977 Exp $}
+set rcsid {$Id: capi3ref.tcl,v 1.6 2004/07/21 14:07:58 drh Exp $}
 source common.tcl
 header {C/C++ Interface For SQLite Version 3}
 puts {
@@ -226,7 +226,18 @@ int sqlite3_column_type(sqlite3_stmt*, int iCol);
  index of 0.
 
  If the SQL statement is not currently point to a valid row, or if the
- the colulmn index is out of range, the result is undefined.
+ the column index is out of range, the result is undefined.
+
+ If the result is a BLOB then the sqlite3_column_bytes() routine returns
+ the number of bytes in that BLOB.  No type conversions occur.
+ If the result is a string (or a number since a number can be converted
+ into a string) then sqlite3_column_bytes() converts
+ the value into a UTF-8 string and returns
+ the number of bytes in the resulting string.  The value returned does
+ not include the \\000 terminator at the end of the string.  The
+ sqlite3_column_bytes16() routine converts the value into a UTF-16
+ encoding and returns the number of bytes (not characters) in the
+ resulting string.  The \\u0000 terminator is not included in this count.
 
  These routines attempt to convert the value where appropriate.  For
  example, if the internal representation is FLOAT and a text result
@@ -234,7 +245,8 @@ int sqlite3_column_type(sqlite3_stmt*, int iCol);
  automatically.  The following table details the conversions that
  are applied:
 
- <table broder=1>
+<blockquote>
+<table border="1">
 <tr><th>Internal Type</th><th>Requested Type</th><th>Conversion</th></tr>
 <tr><td> NULL    </td><td> INTEGER</td><td>Result is 0</td></tr>
 <tr><td> NULL </td><td>    FLOAT </td><td> Result is 0.0</td></tr>
@@ -251,8 +263,9 @@ int sqlite3_column_type(sqlite3_stmt*, int iCol);
 <tr><td> TEXT </td><td>    BLOB </td><td>  No change</td></tr>
 <tr><td> BLOB </td><td>    INTEGER</td><td>Convert to TEXT then use atoi()</td></tr>
 <tr><td> BLOB </td><td>    FLOAT </td><td> Convert to TEXT then use atof()</td></tr>
-<tr><td> BLOB </td><td>    TEXT </td><td>  Add a \000 terminator if needed</td></tr>
+<tr><td> BLOB </td><td>    TEXT </td><td>  Add a \\000 terminator if needed</td></tr>
 </table>
+</blockquote>
 }
 
 api {} {
@@ -687,8 +700,8 @@ char *sqlite3_vmprintf(const char*, va_list);
 
  All of the usual printf formatting options apply.  In addition, there
  is a "%q" option.  %q works like %s in that it substitutes a null-terminated
- string from the argument list.  But %q also doubles every '\'' character.
+ string from the argument list.  But %q also doubles every '\\'' character.
- %q is designed for use inside a string literal.  By doubling each '\''
+ %q is designed for use inside a string literal.  By doubling each '\\''
  character it escapes that character and allows it to be inserted into
  the string.
 
@@ -705,7 +718,7 @@ char *sqlite3_vmprintf(const char*, va_list);
        callback1, 0, 0, zText);
   </pre></blockquote>
 
- Because the %q format string is used, the '\'' character in zText
+ Because the %q format string is used, the '\\'' character in zText
  is escaped and the SQL generated is as follows:
 
  <blockquote><pre>
@@ -894,8 +907,8 @@ int sqlite3_set_authorizer(
 } {
  This routine registers a callback with the SQLite library.  The
  callback is invoked (at compile-time, not at run-time) for each
- attempt to access a column of a table in the database.  The callback
+ attempt to access a column of a table in the database.  The callback should
- returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire
+ return SQLITE_OK if access is allowed, SQLITE_DENY if the entire
  SQL statement should be aborted with an error and SQLITE_IGNORE
  if the column should be treated as a NULL value.
 
@@ -910,7 +923,12 @@ int sqlite3_set_authorizer(
  input SQL code.
 
  The return value of the authorization function should be one of the
- constants SQLITE_DENY or SQLITE_IGNORE.
+ constants SQLITE_OK, SQLITE_DENY, or SQLITE_IGNORE.
+
+ The intent of this routine is to allow applications to safely execute
+ user-entered SQL.  An appropriate callback can deny the user-entered
+ SQL access certain operations (ex: anything that changes the database)
+ or to deny access to certain tables or columns within the database.
 }
 
 api {} {
@@ -982,9 +1000,12 @@ int sqlite3_value_type(sqlite3_value*);
  This group of routines returns information about parameters to
  a user-defined function.  Function implementations use these routines
  to access their parameters.  These routines are the same as the
- sqlite3_column_* routines except that these routines take a single
+ sqlite3_column_... routines except that these routines take a single
  sqlite3_value* pointer instead of an sqlite3_stmt* and an integer
  column number.
+
+ See the documentation under sqlite3_column_blob for additional
+ information.
 }
 
 set n 0