From: drh <drh@noemail.net>
Date: Tue, 13 Jun 2006 15:12:21 +0000 (+0000)
Subject: Improved comments and documentation of sqlite3_load_extension(). (CVS 3229)
X-Git-Tag: version-3.6.10~2938
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=70df4fe6c28ea518935ec94889d3bc9b53a49be7;p=thirdparty%2Fsqlite.git

Improved comments and documentation of sqlite3_load_extension(). (CVS 3229)

FossilOrigin-Name: 0bcec95963603270ee053c83b1f6960b2029d378
---

diff --git a/manifest b/manifest
index 23ef221aef..519a9ea55f 100644
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Add\sthe\stentative\ssqlite3_allocate_queryplan()\sAPI.\s(CVS\s3228)
-D 2006-06-13T15:00:55
+C Improved\scomments\sand\sdocumentation\sof\ssqlite3_load_extension().\s(CVS\s3229)
+D 2006-06-13T15:12:21
 F Makefile.in 56fd6261e83f60724e6dcd764e06ab68cbd53909
 F Makefile.linux-gcc 74ba0eadf88748a9ce3fd03d2a3ede2e6715baec
 F README 9c4e2d6706bdcc3efdd773ce752a8cdab4f90028
@@ -48,7 +48,7 @@ F src/hash.c 449f3d6620193aa557f5d86cbc5cc6b87702b185
 F src/hash.h 1b3f7e2609141fd571f62199fc38687d262e9564
 F src/insert.c 2c3eeb4bcde13c1006824ef14953c2fdad31cf36
 F src/legacy.c fa15d505dd4e45044177ee4d1c6aeaf8c836d390
-F src/loadext.c d0fadf55c55144334a879a32e346c0204658e882
+F src/loadext.c 0215a9c83b7f720aba30f06f183fe6fb3c56a009
 F src/main.c f4397bf95216496e49db2153789788f4b1207b91
 F src/md5.c c5fdfa5c2593eaee2e32a5ce6c6927c986eaf217
 F src/os.c 59f05de8c5777c34876607114a2fbe55ae578235
@@ -71,7 +71,7 @@ F src/printf.c 7029e5f7344a478394a02c52837ff296ee1ab240
 F src/random.c d40f8d356cecbd351ccfab6eaedd7ec1b54f5261
 F src/select.c 38eda11d950ed5e631ea9054f84a4a8b9e9b39d8
 F src/server.c 087b92a39d883e3fa113cae259d64e4c7438bc96
-F src/shell.c 55bf6335dae7146f7a300039f5d6bb35010f1996
+F src/shell.c ad73192b30a338a58fe81183d4a5d5a1d4e51d36
 F src/sqlite.h.in 92cbeeacf040bffe109057d3af2db9dc63db8a67
 F src/sqlite3ext.h 127bd394c8eea481f2ac9b754bf399dbfc818b75
 F src/sqliteInt.h 91cc3603fe2e1be18d52490a2fa65ed9640fb338
@@ -363,7 +363,7 @@ F www/tclsqlite.tcl bb0d1357328a42b1993d78573e587c6dcbc964b9
 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0
 F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b
 F www/whentouse.tcl 97e2b5cd296f7d8057e11f44427dea8a4c2db513
-P 0f4657ea69314e49bc7c9faf9a653ef072f5082d
-R b1fdb74ba8eeb04baf985a2eb223a6b1
-U danielk1977
-Z f48f6df0484e720f46ed17f757e9f5ce
+P 7a3e97f76b1f4f97a04f7c5a9daa400402b2ff25
+R 99814ab55d5388c50dbc5b5d45b55362
+U drh
+Z 9e34725cf1a9f7698b5b20c0e7a693ad
diff --git a/manifest.uuid b/manifest.uuid
index 7e48217efa..69bf2f3307 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-7a3e97f76b1f4f97a04f7c5a9daa400402b2ff25
\ No newline at end of file
+0bcec95963603270ee053c83b1f6960b2029d378
\ No newline at end of file
diff --git a/src/loadext.c b/src/loadext.c
index 569c723597..da9e978f0a 100644
--- a/src/loadext.c
+++ b/src/loadext.c
@@ -20,6 +20,11 @@
 #include <string.h>
 #include <ctype.h>
 
+/*
+** Some API routines are omitted when various features are
+** excluded from a build of SQLite.  Substitute a NULL pointer
+** for any missing APIs.
+*/
 #ifndef SQLITE_ENABLE_COLUMN_METADATA
 # define sqlite3_column_database_name   0
 # define sqlite3_column_database_name16 0
@@ -30,6 +35,21 @@
 # define sqlite3_table_column_metadata  0
 #endif
 
+/*
+** The following structure contains pointers to all SQLite API routines.
+** A pointer to this structure is passed into extensions when they are
+** loaded so that the extension can make calls back into the SQLite
+** library.
+**
+** When adding new APIs, add them to the bottom of this structure
+** in order to preserve backwards compatibility.
+**
+** Extensions that use newer APIs should first call the
+** sqlite3_libversion_number() to make sure that the API they
+** intend to use is supported by the library.  Extensions should
+** also check to make sure that the pointer to the function is
+** not NULL before calling it.
+*/
 const sqlite3_api_routines sqlite3_api = {
   sqlite3_aggregate_context,
   sqlite3_aggregate_count,
@@ -140,10 +160,20 @@ const sqlite3_api_routines sqlite3_api = {
   sqlite3_value_text16le,
   sqlite3_value_type,
   sqlite3_vmprintf,
+  /*
+  ** The original API set ends here.  All extensions can call any
+  ** of the APIs above provided that the pointer is not NULL.  But
+  ** before calling APIs that follow, extension should check the
+  ** sqlite3_libversion_number() to make sure they are dealing with
+  ** a library that is new enough to support that API.
+  *************************************************************************
+  */
 };
 
-
- #if defined(_WIN32) || defined(WIN32) || defined(__MINGW32__) || defined(__BORLANDC__)
+/*
+** The windows implementation of shared-library loaders
+*/
+#if defined(_WIN32) || defined(WIN32) || defined(__MINGW32__) || defined(__BORLANDC__)
 # include <windows.h>
 # define SQLITE_LIBRARY_TYPE     HANDLE
 # define SQLITE_OPEN_LIBRARY(A)  LoadLibrary(A)
@@ -152,7 +182,7 @@ const sqlite3_api_routines sqlite3_api = {
 #endif /* windows */
 
 /*
-** Non-windows implementation of shared-library loaders
+** The unix implementation of shared-library loaders
 */
 #if defined(HAVE_DLOPEN) && !defined(SQLITE_LIBRARY_TYPE)
 # include <dlfcn.h>
@@ -268,8 +298,7 @@ int sqlite3_load_extension(
   return SQLITE_OK;
 #else
   if( pzErrMsg ){
-    *pzErrMsg = sqlite3_mprintf(
-                     "shared library loading not enabled for this build");
+    *pzErrMsg = sqlite3_mprintf("extension loading is disabled");
   }
   return SQLITE_ERROR;
 #endif
diff --git a/src/shell.c b/src/shell.c
index 68fa919077..fdb9c1a9ef 100644
--- a/src/shell.c
+++ b/src/shell.c
@@ -12,7 +12,7 @@
 ** This file contains code to implement the "sqlite" command line
 ** utility for accessing SQLite databases.
 **
-** $Id: shell.c,v 1.141 2006/06/12 12:57:46 drh Exp $
+** $Id: shell.c,v 1.142 2006/06/13 15:12:21 drh Exp $
 */
 #include <stdlib.h>
 #include <string.h>
@@ -763,7 +763,9 @@ static char zHelp[] =
   ".help                  Show this message\n"
   ".import FILE TABLE     Import data from FILE into TABLE\n"
   ".indices TABLE         Show names of all indices on TABLE\n"
+#ifndef SQLITE_OMIT_LOAD_EXTENSION
   ".load FILE ?ENTRY?     Load an extension library\n"
+#endif
   ".mode MODE ?TABLE?     Set output mode where MODE is one of:\n"
   "                         csv      Comma-separated values\n"
   "                         column   Left-aligned columns.  (See .width)\n"
@@ -1150,6 +1152,7 @@ static int do_meta_command(char *zLine, struct callback_data *p){
     }
   }else
 
+#ifndef SQLITE_OMIT_LOAD_EXTENSION
   if( c=='l' && strncmp(azArg[0], "load", n)==0 && nArg>=2 ){
     const char *zFile, *zProc;
     char *zErrMsg = 0;
@@ -1163,6 +1166,7 @@ static int do_meta_command(char *zLine, struct callback_data *p){
       sqlite3_free(zErrMsg);
     }
   }else
+#endif
 
   if( c=='m' && strncmp(azArg[0], "mode", n)==0 && nArg>=2 ){
     int n2 = strlen(azArg[1]);