小. 快速. 可靠.
选择任意三个.

SQLite C Interface

Opening A New Database Connection

int sqlite3_open(
  const char *filename,   /* Database filename (UTF-8) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);
int sqlite3_open16(
  const void *filename,   /* Database filename (UTF-16) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);
int sqlite3_open_v2(
  const char *filename,   /* Database filename (UTF-8) */
  sqlite3 **ppDb,         /* OUT: SQLite db handle */
  int flags,              /* Flags */
  const char *zVfs        /* Name of VFS module to use */
);

这些例程打开由filename参数指定的SQLite数据库文件. filename参数对于sqlite3_open()和sqlite3_open_v2()解释为UTF-8,对于sqlite3_open16()则以本机字节顺序解释为UTF-16. 即使发生错误,通常也会在* ppDb中返回数据库连接句柄. 唯一的例外是,如果SQLite无法分配内存来容纳sqlite3对象,则将一个NULL写入* ppDb而不是指向sqlite3对象的指针. 如果成功打开(和/或创建)数据库,则返回SQLITE_OK . 否则,将返回错误代码 . sqlite3_errmsg()sqlite3_errmsg16()例程可用于获取任何sqlite3_open()例程失败后的错误的英语描述.

对于使用sqlite3_open()或sqlite3_open_v2()创建的数据库,默认编码为UTF-8. 使用sqlite3_open16()创建的数据库的默认编码为本地字节顺序的UTF-16.

无论打开时是否发生错误,与数据库连接句柄关联的资源都应通过在不再需要时将其传递给sqlite3_close()来释放.

sqlite3_open_v2()接口的工作方式类似于sqlite3_open(),不同之处在于它接受两个附加参数来对新数据库连接进行附加控制. sqlite3_open_v2()的flags参数必须至少包括以下三个标志组合之一:

SQLITE_OPEN_READONLY
数据库以只读模式打开. 如果数据库尚不存在,则返回错误.

SQLITE_OPEN_READWRITE
如果可能,将打开数据库以进行读取或写入,或者仅在文件受操作系统写保护的情况下才读取数据库. 无论哪种情况,数据库都必须已经存在,否则将返回错误.

SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE
将打开数据库以供读取和写入,如果数据库尚不存在,则会创建该数据库. 这是始终用于sqlite3_open()和sqlite3_open16()的行为.

除了必需的标志之外,还支持以下可选标志:

SQLITE_OPEN_URI
The filename can be interpreted as a URI if this flag is set.

SQLITE_OPEN_MEMORY
该数据库将作为内存数据库打开. 如果启用了共享缓存模式,则使用"文件名"自变量命名数据库,如果启用了共享缓存模式,则否则将忽略"文件名".

SQLITE_OPEN_NOMUTEX
新的数据库连接将使用"多线程" 线程模式 . 这意味着,只要每个线程使用不同的数据库连接 ,就可以允许单独的线程同时使用SQLite.

SQLITE_OPEN_FULLMUTEX
新的数据库连接将使用"序列化" 线程模式 . 这意味着多个线程可以安全地尝试同时使用同一数据库连接. (Mutexes会阻止任何实际的并发,但是在这种模式下进行尝试没有任何危害.)

SQLITE_OPEN_SHAREDCACHE
将打开启用共享缓存的数据库,从而覆盖sqlite3_enable_shared_cache()提供的默认共享缓存设置.

SQLITE_OPEN_PRIVATECACHE
打开数据库时禁用了共享缓存 ,将覆盖sqlite3_enable_shared_cache()提供的默认共享缓存设置.

SQLITE_OPEN_NOFOLLOW
数据库文件名不允许是符号链接

如果sqlite3_open_v2()的第三个参数不是上面显示的必需组合之一,可以选择与其他SQLITE_OPEN_ *位组合,则该行为是不确定的.

sqlite3_open_v2()的第四个参数是sqlite3_vfs对象的名称,该对象定义新数据库连接应使用的操作系统接口. 如果第四个参数是NULL指针,则使用默认的sqlite3_vfs对象.

如果文件名是":memory:",则将为连接创建一个私有的临时内存数据库. 关闭数据库连接后,此内存数据库将消失. 将来的SQLite版本可能会使用以":"字符开头的其他特殊文件名. 建议当数据库文件名实际上确实以":"字符开头时,应在文件名前添加路径名(例如" ./"),以避免歧义.

如果文件名是一个空字符串,则将创建一个私有的临时磁盘数据库. 关闭数据库连接后,该私有数据库将被自动删除.

URI Filenames

如果启用了URI文件名解释,并且filename参数以" file:"开头,则文件名将解释为URI. 如果在sqlite3_open_v2()的第三个参数中设置了SQLITE_OPEN_URI标志,或者已通过将SQLITE_CONFIG_URI选项与sqlite3_config()方法一起使用或通过SQLITE_USE_URI编译时选项进行了全局启用,则启用URI文件名解释. URI文件名解释默认情况下处于关闭状态,但是SQLite的未来版本可能默认情况下启用URI文件名解释. 有关更多信息,请参见" URI文件名 ".

URI文件名根据RFC 3986进行解析.如果URI包含授权,则它必须是空字符串或字符串" localhost". 如果权限不是空字符串或" localhost",则将错误返回给调用方. URI的片段部分(如果存在)将被忽略.

SQLite使用URI的路径部分作为包含数据库的磁盘文件的名称. 如果路径以" /"字符开头,则将其解释为绝对路径. 如果路径不是以" /"开头(表示从URI中省略了权限部分),则该路径将被解释为相对路径. 在Windows上,绝对路径的第一部分是驱动器规范(例如" C:").

URI的查询组件可能包含由SQLite本身或由自定义VFS实现解释的参数. SQLite及其内置的VFS解释以下查询参数:

在URI的查询组件中指定未知参数不是错误. SQLite的未来版本可能会了解其他查询参数. 有关更多信息,请参见" 对SQLite具有特殊含义的查询参数 ".

URI filename examples

URI文件名 Results
file:data.db 在当前目录中打开文件" data.db".
file:/home/fred/data.db
file:///home/fred/data.db
file://localhost/home/fred/data.db
打开数据库文件" /home/fred/data.db".
file://darkstar/home/fred/data.db 一个错误. "暗星"不是公认的权威.
file:///C:/Documents%20and%20Settings/fred/Desktop/data.db 仅限Windows:在驱动器C:的fred桌面上打开文件" data.db". 请注意,在此示例中转义%20并非绝对必要-可以在URI文件名中直接使用空格字符.
file:data.db?mode=ro&cache=private 在当前目录中打开文件" data.db"以进行只读访问. 无论默认情况下是否启用共享缓存模式,都应使用专用缓存.
file:/home/fred/data.db?vfs=unix-dotfile 打开文件" /home/fred/data.db". 使用特殊的VFS" unix-dotfile",它使用点文件代替posix咨询锁定.
file:data.db?mode=readonly 一个错误. " readonly"不是" mode"参数的有效选项.

URI的路径和查询组件支持URI十六进制转义序列(%HH). 十六进制转义序列由百分号-"%"-后面紧跟两个指定十六进制值的十六进制数字组成. 在解释URI文件名的路径或查询成分之前,它们使用UTF-8进行编码,并且所有十六进制转义序列都被包含相应八位位组的单个字节替换. 如果此过程生成无效的UTF-8编码,则结果不确定.

Windows用户注意:用于sqlite3_open()和sqlite3_open_v2()的filename参数的编码必须为UTF-8,而不是当前定义的任何代码页. 在将包含国际字符的文件名传递到sqlite3_open()或sqlite3_open_v2()之前,必须先将其转换为UTF-8.

Windows运行时用户注意:必须在调用sqlite3_open()或sqlite3_open_v2()之前设置临时目录. 否则,要求使用临时文件的各种功能可能会失败.

另请参见: sqlite3_temp_directory

另请参见对象常量函数的列表 .

by  ICOPY.SITE