求索阁

/******************************************************************************

** This file is an amalgamation of many separate C source files from SQLite

** version 3.14.1.  By combining all the individual C code files into this

** single large file, the entire code can be compiled as a single translation

** unit.  This allows many compilers to do optimizations that would not be

** possible if the files were compiled separately.  Performance improvements

** of 5% or more are commonly seen when SQLite is compiled as a single

** translation unit.

**

** This file is all you need to compile SQLite.  To use SQLite in other

** programs, you need this file and the "sqlite3.h" header file that defines

** the programming interface to the SQLite library.  (If you do not have

** the "sqlite3.h" header file at hand, you will find a copy embedded within

** the text of this file.  Search for "Begin file sqlite3.h" to find the start

** of the embedded sqlite3.h header file.) Additional code files may be needed

** if you want a wrapper to interface SQLite with your choice of programming

** language. The code for the "sqlite3" command-line shell is also in a

** separate file. This file contains only code for the core SQLite library.

*/

#define SQLITE_CORE 1            //定义内核参数

#define SQLITE_AMALGAMATION 1    //定义合并参数(为1)，版本为合并后的源代码

#ifndef SQLITE_PRIVATE            //定义SQLITE代码的私有部分(即static)

# define SQLITE_PRIVATE static

#endif

/************** Begin file sqliteInt.h ***************************************/

/*

** 2001 September 15

**

** The author disclaims copyright to this source code.  In place of

** a legal notice, here is a blessing:

**

**    May you do good and not evil.

**    May you find forgiveness for yourself and forgive others.

**    May you share freely, never taking more than you give.

**

*************************************************************************

** Internal interface definitions for SQLite.

**

*/

#ifndef SQLITEINT_H    //定义SQLITE内部接口，定义头文件

#define SQLITEINT_H

……

/************** Include msvc.h in the middle of sqliteInt.h ******************/

……

/************** Continuing where we left off in sqliteInt.h ******************/

/*

** 如果基础操作系统支持，可用#define开启大于2G的单个文件支持

** These #defines should enable >2GB file support on POSIX if the

** underlying operating system supports it.  If the OS lacks

** large file support, or if the OS is windows, these should be no-ops.

**

** _LARGEFILE_SOURCE宏必须在任何#include前使用

** Ticket #2739:  The _LARGEFILE_SOURCE macro must appear before any

** system #includes.  Hence, this block of code must be the very first

** code in all source files.

**

** 在编译命令行使用SQLITE_DISABLE_LFS可禁止大文件支持

** Large file support can be disabled using the -DSQLITE_DISABLE_LFS switch

** on the compiler command line.  This is necessary if you are compiling

** on a recent machine (ex: Red Hat 7.2) but you want your code to work

** on an older machine (ex: Red Hat 6.0).  If you compile on Red Hat 7.2

** without this option, LFS is enable.  But LFS does not exist in the kernel

** in Red Hat 6.0, so the code won't work.  Hence, for maximum binary

** portability you should omit LFS.

**

** The previous paragraph was written in 2005.  (This paragraph is written

** on 2008-11-28.) These days, all Linux kernels support large files, so

** you should probably leave LFS enabled.  But some embedded platforms might

** lack LFS in which case the SQLITE_DISABLE_LFS macro might still be useful.

**

** Similar is true for Mac OS X.  LFS is only supported on Mac OS X 9 and later.

*/

#ifndef SQLITE_DISABLE_LFS        //如果没禁止大文件支持，则定义相关常量

# define _LARGE_FILE       1

# ifndef _FILE_OFFSET_BITS

#   define _FILE_OFFSET_BITS 64

# endif

# define _LARGEFILE_SOURCE 1

#endif

/* What version of GCC is being used.  0 means GCC is not being used */

#ifdef __GNUC__

# define GCC_VERSION (__GNUC__*1000000+__GNUC_MINOR__*1000+__GNUC_PATCHLEVEL__)

#else

# define GCC_VERSION 0

#endif

/* Needed for various definitions... */

#if defined(__GNUC__) && !defined(_GNU_SOURCE)

# define _GNU_SOURCE

#endif

#if defined(__OpenBSD__) && !defined(_BSD_SOURCE)

# define _BSD_SOURCE

#endif

/*

** For MinGW, check to see if we can include the header file containing its

** version information, among other things.  Normally, this internal MinGW

** header file would [only] be included automatically by other MinGW header

** files; however, the contained version information is now required by this

** header file to work around binary compatibility issues (see below) and

** this is the only known way to reliably obtain it.  This entire #if block

** would be completely unnecessary if there was any other way of detecting

** MinGW via their preprocessor (e.g. if they customized their GCC to define

** some MinGW-specific macros).  When compiling for MinGW, either the

** _HAVE_MINGW_H or _HAVE__MINGW_H (note the extra underscore) macro must be

** defined; otherwise, detection of conditions specific to MinGW will be

** disabled.

*/

#if defined(_HAVE_MINGW_H)

# include "mingw.h"

#elif defined(_HAVE__MINGW_H)

# include "_mingw.h"

#endif

/*

** For MinGW version 4.x (and higher), check to see if the _USE_32BIT_TIME_T

** define is required to maintain binary compatibility with the MSVC runtime

** library in use (e.g. for Windows XP).

*/

#if !defined(_USE_32BIT_TIME_T) && !defined(_USE_64BIT_TIME_T) && \

    defined(_WIN32) && !defined(_WIN64) && \

    defined(__MINGW_MAJOR_VERSION) && __MINGW_MAJOR_VERSION >= 4 && \

    defined(__MSVCRT__)

# define _USE_32BIT_TIME_T

#endif

/* The public SQLite interface.  The _FILE_OFFSET_BITS macro must appear

** first in QNX.  Also, the _USE_32BIT_TIME_T macro must appear first for

** MinGW.

*/

/************** Include sqlite3.h in the middle of sqliteInt.h ***************/

/************** Begin file sqlite3.h *****************************************/

// 在sqliteInt.h中包含sqlite3.h 

/*

** 2001 September 15

**

** The author disclaims copyright to this source code.  In place of

** a legal notice, here is a blessing:

**

**    May you do good and not evil.

**    May you find forgiveness for yourself and forgive others.

**    May you share freely, never taking more than you give.

**

*************************************************************************

** sqlite库的客户端接口，如果在这个文件中没有出现过某个C函数、结构、数据类型、或常量定义

** 那么它是不公开的SQLITE的API，不会声明随时有可能改变，也不能做为使用SQLITE开发的参考

** This header file defines the interface that the SQLite library

** presents to client programs.  If a C-function, structure, datatype,

** or constant definition does not appear in this file, then it is

** not a published API of SQLite, is subject to change without

** notice, and should not be referenced by programs that use SQLite.

** 有些定义被标明experimental(实验性的)，这些接口不久会被加入SQLITE

** 虽然不希望改变实验性接口，会保留较小改变的权力，使用in the wild标明的地方要谨慎改变

**

** Some of the definitions that are in this file are marked as

** "experimental".  Experimental interfaces are normally new

** features recently added to SQLite.  We do not anticipate changes

** to experimental interfaces but reserve the right to make minor changes

** if experience from use "in the wild" suggest such changes are prudent.

** SQLITE的官方C语言API文档从注解生成，这个文件在SQLITE接口操作方面具有权威

**

** The official C-language API documentation for SQLite is derived

** from comments in this file.  This file is the authoritative source

** on how SQLite interfaces are supposed to operate.

** 构造管理文件是sqlite.h.in，makefile对这个文件（比如嵌入式版本中）做较小改动，build过程中其名改为sqlite3.h

**

** The name of this file under configuration management is "sqlite.h.in".

** The makefile makes some minor changes to this file (such as inserting

** the version number) and changes its name to "sqlite3.h" as

** part of the build process.

*/

#ifndef SQLITE3_H

#define SQLITE3_H

#include <stdarg.h>     /* Needed for the definition of va_list * SQLITE接口需要va_list定义 */

/*

** Make sure we can call this stuff from C++.

*/

/*

** extern声明的函数和变量可以在本模块或其他模块中使用。 

** extern "C"包含双重含义，其一：被它修饰的目标是“extern”的；其二：被它修饰的目标是“C”的。

** extern "C"仅被使用在C++调用C程序情况，C不能使用。

** #if 0把它屏蔽了，如果使用C++编译器，可以打开该选项 

** 比如test.cpp(C++源码文件)需要调用myc.h这个C头文件中用extern声明的函数，可以如下书写: 

**

** extern "C" 

** { 

**    #include "myc.h" 

** }

*/

#if 0

extern "C" {

#endif

/*

** Provide the ability to override linkage features of the interface.

*/

//定义extern的宏，可使用SQLITE_EXTERN来完成extern功能 

#ifndef SQLITE_EXTERN

# define SQLITE_EXTERN extern

#endif

//定义SQLITE_API宏

#ifndef SQLITE_API

# define SQLITE_API __declspec(dllexport)

#endif

#ifndef SQLITE_CDECL

# define SQLITE_CDECL

#endif

#ifndef SQLITE_APICALL

# define SQLITE_APICALL

#endif

#ifndef SQLITE_STDCALL

# define SQLITE_STDCALL SQLITE_APICALL

#endif

#ifndef SQLITE_CALLBACK

# define SQLITE_CALLBACK

#endif

#ifndef SQLITE_SYSAPI

# define SQLITE_SYSAPI

#endif

/*

** no-op宏经常在接口前标记那些实验性的和不推荐的接口。

** 新应用程序最好不使用不推荐的接口，它们支持向后兼容。程序员必须意识到实验性接口会在某个版本中改变

** These no-op macros are used in front of interfaces to mark those

** interfaces as either deprecated or experimental.  New applications

** should not use deprecated interfaces - they are supported for backwards

** compatibility only.  Application writers should be aware that

** experimental interfaces are subject to change in point releases.

** 这些宏在他们需要时，能实现编译器魔法compiler magic警告信息，编译器魔法最终产生BUG报告，编译器会试着使用noop宏。

**

** These macros used to resolve to various kinds of compiler magic that

** would generate warning messages when they were used.  But that

** compiler magic ended up generating such a flurry of bug reports

** that we have taken it all out and gone back to using simple

** noop macros.

*/

#define SQLITE_DEPRECATED

#define SQLITE_EXPERIMENTAL

/*

** Ensure these symbols were not defined by some previous header file.

*/

// 如果SQLITE_VERSION、SQLITE_VERSION_NUMBER标志已经定义，则取消

#ifdef SQLITE_VERSION

# undef SQLITE_VERSION

#endif

#ifdef SQLITE_VERSION_NUMBER

# undef SQLITE_VERSION_NUMBER

#endif

/*

** CAPI3REF: Compile-Time Library Version Numbers

**

** SQLITE_VERSION 宏为版本号，X.Y.Z的SQLITE版本号中,X是主版本号，Y是次版本号，Z是发行号

** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header

** evaluates to a string literal that is the SQLite version in the

** format "X.Y.Z" where X is the major version number (always 3 for

** SQLite3) and Y is the minor version number and Z is the release number.)^

** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer

** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same

** numbers used in [SQLITE_VERSION].)^

**

** SQLITE_VERSION_NUMBER根据SQLITE_VERSION中版本号计算一个整数（X*1000000 + Y*1000 + Z）

** The SQLITE_VERSION_NUMBER for any given release of SQLite will also

** be larger than the release from which it is derived.  Either Y will

** be held constant and Z will be incremented or else Y will be incremented

** and Z will be reset to zero.

**

** Since version 3.6.18, SQLite source code has been stored in the

** <a href="http://www.fossil-scm.org/">Fossil configuration management

** system</a>.  ^The SQLITE_SOURCE_ID macro evaluates to

** a string which identifies a particular check-in of SQLite

** within its configuration management system.  ^The SQLITE_SOURCE_ID

** string contains the date and time of the check-in (UTC) and an SHA1

** hash of the entire source tree.

** SQLITE_SOURCE_ID 为一个字符串，为SQLITE配置管理系统中的check-in详情包含check-in的日期和时间以及整个源码树的SHA1哈希

**

** See also: [sqlite3_libversion()],

** [sqlite3_libversion_number()], [sqlite3_sourceid()],

** [sqlite_version()] and [sqlite_source_id()].

*/

//定义版本号，并计算SQLITE_VERSION_NUMBER

#define SQLITE_VERSION        "3.14.1"

#define SQLITE_VERSION_NUMBER 3014001

#define SQLITE_SOURCE_ID      "2016-08-11 18:53:32 a12d8059770df4bca59e321c266410344242bf7b"

/*

** CAPI3REF: Run-Time Library Version Numbers

** KEYWORDS: sqlite3_version, sqlite3_sourceid

**

** 这些接口通过库而不是头文件提供了SQLITE_VERSION、SQLITE_VERSION_NUMBER以**及SQLITE_SOURCE_ID宏的相同信息

** These interfaces provide the same information as the [SQLITE_VERSION],

** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros

** but are associated with the library instead of the header file.  ^(Cautious

** programmers might include assert() statements in their application to

** verify that values returned by these interfaces match the macros in

** the header, and thus ensure that the application is

** compiled with matching library and header files.

**

** 可小心地通过包含以下的assert()声明，在应用程序核实匹配头文件中宏的这些接口，以确保应用程序使用相匹配的库和头文件编译

** <blockquote><pre>

** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );

** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );

** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );

** </pre></blockquote>)^

**

** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]

** macro.  ^The sqlite3_libversion() function returns a pointer to the

** to the sqlite3_version[] string constant.  The sqlite3_libversion()

** function is provided for use in DLLs since DLL users usually do not have

** direct access to string constants within the DLL.  ^The

** sqlite3_libversion_number() function returns an integer equal to

** [SQLITE_VERSION_NUMBER].  ^The sqlite3_sourceid() function returns

** a pointer to a string constant whose value is the same as the

** [SQLITE_SOURCE_ID] C preprocessor macro.

**

** See also: [sqlite_version()] and [sqlite_source_id()].

*/

SQLITE_API const char sqlite3_version[] = SQLITE_VERSION;

SQLITE_API const char *SQLITE_STDCALL sqlite3_libversion(void);

SQLITE_API const char *SQLITE_STDCALL sqlite3_sourceid(void);

SQLITE_API int SQLITE_STDCALL sqlite3_libversion_number(void);

//SQLITE_VERSION 宏定义了版本号，在本源码包中定义为"3.14.1"

//sqlite3_version[]为前面定义的SQLITE_VERSION宏的内容，即版本号

//sqlite3_libversion()返回指向sqlite3_version[]字符数组常量的指针

//sqlite3_sourceid()返回一个指向SQLITE_SOURCE_ID宏内容的指针

//sqlite3_libversion_number()返回SQLITE_VERSION_NUMBER宏定义的版本号

/*

** CAPI3REF: Run-Time Library Compilation Options Diagnostics

**

** ^The sqlite3_compileoption_used() function returns 0 or 1

** indicating whether the specified option was defined at

** compile time.  ^The SQLITE_ prefix may be omitted from the

** option name passed to sqlite3_compileoption_used().

** sqlite3_compileoption_used()返回0和1,指示编译时是否有定义的选项 

**

** sqlite3_compileoption_get()允许正在起作用的编译时定义的选项列表，返回N次编译时的选项字符串

** ^The sqlite3_compileoption_get() function allows iterating

** over the list of options that were defined at compile time by

** returning the N-th compile time option string.  ^If N is out of range,

** sqlite3_compileoption_get() returns a NULL pointer.  ^The SQLITE_

** prefix is omitted from any strings returned by

** sqlite3_compileoption_get().

**

** 如果 N过界，sqlite3_compileoption_get()返回NULL指针

** ^Support for the diagnostic functions sqlite3_compileoption_used()

** and sqlite3_compileoption_get() may be omitted by specifying the

** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.

**

** 编译时定义SQLITE_OMIT_COMPILEOPTION_DIAGS选项，将忽略sqlite3_compileoption_used()和 sqlite3_compileoption_get()这2个诊断函数

** See also: SQL functions [sqlite_compileoption_used()] and

** [sqlite_compileoption_get()] and the [compile_options pragma].

*/

#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS

SQLITE_API int SQLITE_STDCALL sqlite3_compileoption_used(const char *zOptName);

SQLITE_API const char *SQLITE_STDCALL sqlite3_compileoption_get(int N);

#endif

/*

** 库线程安全

** CAPI3REF: Test To See If The Library Is Threadsafe

**

** SQLITE_THREADSAFE预处理宏编译时选项设为0,则忽略SQLITE的互斥代码，此时，sqlite3_threadsafe()返回0

** ^The sqlite3_threadsafe() function returns zero if and only if

** SQLite was compiled with mutexing code omitted due to the

** [SQLITE_THREADSAFE] compile-time option being set to 0.

** SQLITE可在有互斥和没有互斥情况下编译，当SQLITE_THREADSAFE宏是1或2**时，互斥被允许，SQLITE是线程安全的。

** 该宏为0时，不使用互斥，超过一个线程同时使用SQLite是不安全的

**

** SQLite can be compiled with or without mutexes.  When

** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes

** are enabled and SQLite is threadsafe.  When the

** [SQLITE_THREADSAFE] macro is 0,

** the mutexes are omitted.  Without the mutexes, it is not safe

** to use SQLite concurrently from more than one thread.

** 允许互斥，将会产生一些可预见的后果。如果速度是第一位的，最好是禁止互斥，对于最好安全性而言，互斥要开启，默认的行为是互斥开启。

**

** Enabling mutexes incurs a measurable performance penalty.

** So if speed is of utmost importance, it makes sense to disable

** the mutexes.  But for maximum safety, mutexes should be enabled.

** ^The default behavior is for mutexes to be enabled.

** 这些接口被应用程序使用，确认该SQLITE版本编译链接时是否使用sqlite_threadsafe宏

**

** This interface can be used by an application to make sure that the

** version of SQLite that it is linking against was compiled with

** the desired setting of the [SQLITE_THREADSAFE] macro.

** 该接口仅在编译时，互斥设置了SQLITE_THREADSAFE标志时才报告，如果SQLITE使用SQLITE_THREADSAFE=1或=2的方式编译，互斥被允许

** 但通过SQLITE_CONFIG_SINGLETHREAD、SQLITE_CONFIG_MULTITHREAD能部分或完全禁止对sqlite3_config()的调用

**

** This interface only reports on the compile-time mutex setting

** of the [SQLITE_THREADSAFE] flag.  If SQLite is compiled with

** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but

** can be fully or partially disabled using a call to [sqlite3_config()]

** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],

** or [SQLITE_CONFIG_SERIALIZED].

** sqlite3_threadsafe()函数的返回值仅指示编译时设置了线程安全不能被sqlite3_config()可在运行时改变

** ^(The return value of the sqlite3_threadsafe() function shows only the compile-time setting of

** thread safety, not any run-time changes to that setting made by

** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()

** is unchanged by calls to sqlite3_config().)^

** 调用sqlite3_config()不能改变sqlite3_threadsafe()返回值

**

** See the [threading mode] documentation for additional information.

*/

SQLITE_API int SQLITE_STDCALL sqlite3_threadsafe(void);

/*

** 数据库连接句柄

** CAPI3REF: Database Connection Handle

** KEYWORDS: {database connection} {database connections}

** 关键字：{database connection} {database connections}

** 每个打开的SQLite数据库做为一个指针出现，该指针指向隐藏的sqlite3结构的实例，建议将sqlite3指针视为对象

** sqlite3_open()、sqlite3_open16()、sqlite3_open_v2()接口是这个对象的构造器，sqlite3_close()是析构器

**

** Each open SQLite database is represented by a pointer to an instance of

** the opaque structure named "sqlite3".  It is useful to think of an sqlite3

** pointer as an object.  The [sqlite3_open()], [sqlite3_open16()], and

** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]

** and [sqlite3_close_v2()] are its destructors. 

** 还有一些其它接口sqlite3_prepare_v2()、sqlite3_create_function()、sqlite3_busy_timeout()为sqlite3对象的方法

**

** There are many other interfaces (such as

** [sqlite3_prepare_v2()], [sqlite3_create_function()], and

** [sqlite3_busy_timeout()] to name but three) that are methods on an

** sqlite3 object.

*/

typedef struct sqlite3 sqlite3;

/*

** CAPI3REF: 64-Bit Integer Types

** KEYWORDS: sqlite_int64 sqlite_uint64

** 64位整数类型关键字：sqlite_int64 sqlite_uint64

**

** Because there is no cross-platform way to specify 64-bit integer types

** SQLite includes typedefs for 64-bit signed and unsigned integers.

** 没有跨平台的方法定义64位整数，SQLite包括64位有符号和无符号整数

**

** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.

** sqlite3_int64和sqlite3_uint64是首选类型，sqlite_int64和sqlite_uint64仅支持向后兼容性

** The sqlite_int64 and sqlite_uint64 types are supported for backwards

** compatibility only.

**

** sqlite3_int64和sqlite_int64类型的范围在-922337203685477580和+9223372036854775807之间

** sqlite3_uint64和sqlite_uint64在0和+18446744073709551615之间

**

** ^The sqlite3_int64 and sqlite_int64 types can store integer values

** between -9223372036854775808 and +9223372036854775807 inclusive.  ^The

** sqlite3_uint64 and sqlite_uint64 types can store integer values

** between 0 and +18446744073709551615 inclusive.

*/

//以下根据前面定义的宏，定义sqlite_int64、sqlite_uint64、sqlite3_int64、sqlite_uint64实际使用的类型

#ifdef SQLITE_INT64_TYPE

  typedef SQLITE_INT64_TYPE sqlite_int64;

  typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;

#elif defined(_MSC_VER) || defined(__BORLANDC__)

  typedef __int64 sqlite_int64;

  typedef unsigned __int64 sqlite_uint64;

#else

  typedef long long int sqlite_int64;

  typedef unsigned long long int sqlite_uint64;

#endif

typedef sqlite_int64 sqlite3_int64;

typedef sqlite_uint64 sqlite3_uint64;

/*

** 如果处理器没有符点支持，则用sqlite3_int64整数替代

** If compiling for a processor that lacks floating point support,

** substitute integer for floating-point.

*/

#ifdef SQLITE_OMIT_FLOATING_POINT

# define double sqlite3_int64

#endif

/*

** CAPI3REF: Closing A Database Connection

** DESTRUCTOR: sqlite3

**

** 关闭数据库连接，如果sqlite3对象成功卸载,所有相关资源被释放sqlite3sqlite3_close()返回SQLITE_OK

**

** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors

** for the [sqlite3] object.

** ^Calls to sqlite3_close() and sqlite3_close_v2() return [SQLITE_OK] if

** the [sqlite3] object is successfully destroyed and all associated

** resources are deallocated.

**

** ^If the database connection is associated with unfinalized prepared

** statements or unfinished sqlite3_backup objects then sqlite3_close()

** will leave the database connection open and return [SQLITE_BUSY].

** ^If sqlite3_close_v2() is called with unfinalized prepared statements

** and/or unfinished sqlite3_backups, then the database connection becomes

** an unusable "zombie" which will automatically be deallocated when the

** last prepared statement is finalized or the last sqlite3_backup is

** finished.  The sqlite3_close_v2() interface is intended for use with

** host languages that are garbage collected, and where the order in which

** destructors are called is arbitrary.

**

** 应用程序必须在关闭sqlite3对象前，[sqlite3_finalize | finalize]所有的与该对象相关的[prepared statements]

** 必须[sqlite3_blob_close | close]所有的与该对象相关的[BLOB handles] (BLOB大二进制句柄)

**

** Applications should [sqlite3_finalize | finalize] all [prepared statements],

** [sqlite3_blob_close | close] all [BLOB handles], and

** [sqlite3_backup_finish | finish] all [sqlite3_backup] objects associated

** with the [sqlite3] object prior to attempting to close the object.  ^If

** sqlite3_close_v2() is called on a [database connection] that still has

** outstanding [prepared statements], [BLOB handles], and/or

** [sqlite3_backup] objects then it returns [SQLITE_OK] and the deallocation

** of resources is deferred until all [prepared statements], [BLOB handles],

** and [sqlite3_backup] objects are also destroyed.

**

** 如果sqlite3_close()在[database connection]数据库连接被调用，该数据库连接中仍有显式的[prepared statements][BLOB handles]，则返回SQLITE_BUSY

**

** 当事务打开时，调用sqlite3_close()，事务自动回滚

**

** ^If an [sqlite3] object is destroyed while a transaction is open,

** the transaction is automatically rolled back.

**

** sqlite3_close(C)的C参数可以是NULL指针或从sqlite3_open()、sqlite3_**open16()、sqlite3_open_v2()获取的[sqlite3]对象指针

** 使用NULL参数调用sqlite3_close()为没负作用的空操作

**

** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)]

** must be either a NULL

** pointer or an [sqlite3] object pointer obtained

** from [sqlite3_open()], [sqlite3_open16()], or

** [sqlite3_open_v2()], and not previously closed.

** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer

** argument is a harmless no-op.

*/

SQLITE_API int SQLITE_STDCALL sqlite3_close(sqlite3*);

SQLITE_API int SQLITE_STDCALL sqlite3_close_v2(sqlite3*);

/*

** The type for a callback function.

** This is legacy and deprecated.  It is included for historical

** compatibility and is not documented.

*/

//回调函数，不赞成这种旧版本遗留下来的机制，它被包含进来，为了历史兼容性，没有相关证实

typedef int (*sqlite3_callback)(void*,int,char**, char**);

/*

** 查询执行接口

** CAPI3REF: One-Step Query Execution Interface

** METHOD: sqlite3

**

** The sqlite3_exec() interface is a convenience wrapper around

** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],

** that allows an application to run multiple statements of SQL

** without having to use a lot of C code.

**

** sqlite3_exec()接口包装了[sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()]

** 方便使用，允许应用程序执行多语句的SQL，无使用大量C代码

**

** sqlite3_exec()符合UTF8编码要求，用分号分隔的SQL语句为它的第二个参数

** database connection数据库连接为第一个参数，做为第三个参数的回调函数如果非空，则SQL执行结果的每一行都会调用该函数

**

** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,

** semicolon-separate SQL statements passed into its 2nd argument,

** in the context of the [database connection] passed in as its 1st

** argument.  ^If the callback function of the 3rd argument to

** sqlite3_exec() is not NULL, then it is invoked for each result row

** coming out of the evaluated SQL statements.  ^The 4th argument to

** sqlite3_exec() is relayed through to the 1st argument of each

** callback invocation.  ^If the callback pointer to sqlite3_exec()

** is NULL, then no callback is ever invoked and result rows are

** ignored.

**

** ^If an error occurs while evaluating the SQL statements passed into

** sqlite3_exec(), then execution of the current statement stops and

** subsequent statements are skipped.  ^If the 5th parameter to sqlite3_exec()

** is not NULL then any error message is written into memory obtained

** from [sqlite3_malloc()] and passed back through the 5th parameter.

** To avoid memory leaks, the application should invoke [sqlite3_free()]

** on error message strings returned through the 5th parameter of

** sqlite3_exec() after the error message string is no longer needed.

** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors

** occur, then sqlite3_exec() sets the pointer in its 5th parameter to

** NULL before returning.

**

** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()

** routine returns SQLITE_ABORT without invoking the callback again and

** without running any subsequent SQL statements.

**

** ^The 2nd argument to the sqlite3_exec() callback function is the

** number of columns in the result.  ^The 3rd argument to the sqlite3_exec()

** callback is an array of pointers to strings obtained as if from

** [sqlite3_column_text()], one for each column.  ^If an element of a

** result row is NULL then the corresponding string pointer for the

** sqlite3_exec() callback is a NULL pointer.  ^The 4th argument to the

** sqlite3_exec() callback is an array of pointers to strings where each

** entry represents the name of corresponding result column as obtained

** from [sqlite3_column_name()].

**

** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer

** to an empty string, or a pointer that contains only whitespace and/or

** SQL comments, then no SQL statements are evaluated and the database

** is not changed.

**

** Restrictions:

**

** <ul>

** <li> The application must ensure that the 1st parameter to sqlite3_exec()

**      is a valid and open [database connection].

** <li> The application must not close the [database connection] specified by

**      the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.

** <li> The application must not modify the SQL statement text passed into

**      the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.

** </ul>

*/

SQLITE_API int SQLITE_STDCALL sqlite3_exec(

  sqlite3*,                                  /* An open database */

  const char *sql,                           /* SQL to be evaluated */

  int (*callback)(void*,int,char**,char**),  /* Callback function */

  void *,                                    /* 1st argument to callback */

  char **errmsg                              /* Error msg written here */

);