From 422b3024e2df5dccaee35fb8a7e29adf16308ec4 Mon Sep 17 00:00:00 2001 From: drh Date: Wed, 21 Jul 2004 14:07:57 +0000 Subject: [PATCH] Updates to the C-language API documents for version 3.0. (CVS 1840) FossilOrigin-Name: 814c58d470922d77cfcc6c4d5d26c1ec4c28ca60 --- manifest | 12 ++++++------ manifest.uuid | 2 +- www/capi3ref.tcl | 43 ++++++++++++++++++++++++++++++++----------- 3 files changed, 39 insertions(+), 18 deletions(-) diff --git a/manifest b/manifest index ff2422192b..1a0bb68e29 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Minor\scoding\senhancements.\s(CVS\s1839) -D 2004-07-21T02:53:30 +C Updates\sto\sthe\sC-language\sAPI\sdocuments\sfor\sversion\s3.0.\s(CVS\s1840) +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 -R 9e5a169fd77b5347506f033f7c0bac3e +P 65c3af74c16c9fe0341b1e7e6d029927503f7404 +R 86f621dbcf22f7ac329aac2fafa03b69 U drh -Z 16e953d85e2aa59a57853642a9ecf96b +Z 622f440ec16a414813d23dde7141b3ba diff --git a/manifest.uuid b/manifest.uuid index 1c23b86524..2336e65068 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -65c3af74c16c9fe0341b1e7e6d029927503f7404 \ No newline at end of file +814c58d470922d77cfcc6c4d5d26c1ec4c28ca60 \ No newline at end of file diff --git a/www/capi3ref.tcl b/www/capi3ref.tcl index 4678b78f08..c1a7cd26f9 100644 --- a/www/capi3ref.tcl +++ b/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: - +
+
@@ -251,8 +263,9 @@ int sqlite3_column_type(sqlite3_stmt*, int iCol); - +
Internal TypeRequested TypeConversion
NULL INTEGERResult is 0
NULL FLOAT Result is 0.0
TEXT BLOB No change
BLOB INTEGERConvert to TEXT then use atoi()
BLOB FLOAT Convert to TEXT then use atof()
BLOB TEXT Add a \000 terminator if needed
BLOB TEXT Add a \\000 terminator if needed
+ } 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. - %q is designed for use inside a string literal. By doubling each '\'' + string from the argument list. But %q also doubles every '\\'' character. + %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); - 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: 
@@ -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
- returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire
+ attempt to access a column of a table in the database.  The callback should
+ 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