SQLite C Interface - Opening A New Database Connection

intsqlite3_open(
constchar*filename,/*Databasefilename(UTF-8)*/
sqlite3**ppDb/*OUT:SQLitedbhandle*/
);
intsqlite3_open16(
constvoid*filename,/*Databasefilename(UTF-16)*/
sqlite3**ppDb/*OUT:SQLitedbhandle*/
);
intsqlite3_open_v2(
constchar*filename,/*Databasefilename(UTF-8)*/
sqlite3**ppDb,/*OUT:SQLitedbhandle*/
intflags,/*Flags*/
constchar*zVfs/*NameofVFSmoduletouse*/
);

These routines open an SQLite database file whose name is given by the filename argument. The filename argument is interpreted as UTF-8 for sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte order for sqlite3_open16(). A database connection handle is usually returned in *ppDb,even if an error occurs. The only exception is that if SQLite is unable to allocate memory to hold the sqlite3 object,a NULL will be written into *ppDb instead of a pointer to the sqlite3 object. If the database is opened (and/or created) successfully,then SQLITE_OK is returned. Otherwise an error code is returned. The sqlite3_errmsg() or sqlite3_errmsg16() routines can be used to obtain an English language description of the error.

这些例程打开filename参数提供的SQLite数据库文件。对于sqlite3_open()和sqlite3_open_v2()，filename参数按UTF-8解释；对于sqlite3_open16()，按本机字节序的UTF-16解释。数据库连接句柄在*ppDb中返回，即使有错误发生。唯一的例外是，如果SQLite无法给sqlite3对象分配内存时，*ppDb将被写入NULL而不是sqlite3对象的指针。如果数据库被成功打开（和/或创建），则返回SQLITE_OK。否则返回错误码。sqlite3_errmsg()或sqlite3_errmsg16()例程可以用于获取错误的英文描述。

The default encoding for the database will be UTF-8 if sqlite3_open() or sqlite3_open_v2() is called and UTF-16 in the native byte order if sqlite3_open16() is used.

如果调用sqlite3_open()或sqlite3_open_v2()，数据库的默认编码将是UTF-8；如果使用sqlite3_open16()，则是本机字节序的UTF-16。

Whether or not an error occurs when it is opened,resources associated with the database connection handle should be released by passing it to sqlite3_close() when it is no longer required.

不管打开数据库的时候有没有错误发生，当不再需要它的时候，都应该将数据库连接句柄传递给sqlite3_close()来释放和它相关的资源。

The sqlite3_open_v2() interface works like sqlite3_open() except that it accepts two additional parameters for additional control over the new database connection. The flags parameter can take one of the following three values,optionally combined with the SQLITE_OPEN_NOMUTEX or SQLITE_OPEN_FULLMUTEX flags:

• SQLITE_OPEN_READONLY
  The database is opened in read-only mode. If the database does not already exist,an error is returned.
• SQLITE_OPEN_READWRITE
  The database is opened for reading and writing if possible,or reading only if the file is write protected by the operating system. In either case the database must already exist,otherwise an error is returned.
• SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE
  The database is opened for reading and writing,and is creates it if it does not already exist. This is the behavior that is always used for sqlite3_open() and sqlite3_open16().

sqlite3_open_v2()接口和sqlite3_open()的工作方式类似，但它接受两个额外的参数控制新的数据库连接。flags参数可以是下列三个值之一，并且可以选择性的组合SQLITE_OPEN_NOMUTEX或SQLITE_OPEN_FULLMUTEX标记：

• SQLITE_OPEN_READONLY
  数据库以只读方式打开。如果数据库还不存在，返回错误。
• SQLITE_OPEN_READWRITE
  如果可能的话，数据库以读写方式打开，或者如果该文件被操作系统保护，则以只读方式打开。在这两种情况下数据库都必须已经存在，否则返回错误。
• SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE
  数据库以读写方式打开，如果还不存在则创建它。这是sqlite3_open()和sqlite3_open16()总是使用的行为。

If the 3rd parameter to sqlite3_open_v2() is not one of the combinations shown above or one of the combinations shown above combined with the SQLITE_OPEN_NOMUTEX or SQLITE_OPEN_FULLMUTEX flags,then the behavior is undefined.

如果sqlite3_open_v2()的第3个参数不是上面所示的组合之一或上面所示的组合与SQLITE_OPEN_NOMUTEX或SQLITE_OPEN_FULLMUTEX的组合，则行为未定义。

If the SQLITE_OPEN_NOMUTEX flag is set,then the database connection opens in the multi-thread threading mode as long as the single-thread mode has not been set at compile-time or start-time. If the SQLITE_OPEN_FULLMUTEX flag is set then the database connection opens in the serialized threading mode unless single-thread was previously selected at compile-time or start-time.

如果设置了SQLITE_OPEN_NOMUTEX，只要没有在编译期或开始时设置单线程模式，数据库连接就以多线程线程模式打开。如果设置了SQLITE_OPEN_FULLMUTEX ，那么数据库连接以串行线程模式打开，除非之前在编译期或开始时选择了单线程。

If the filename is ":memory:",then a private,temporary in-memory database is created for the connection. This in-memory database will vanish when the database connection is closed. Future versions of SQLite might make use of additional special filenames that begin with the ":" character. It is recommended that when a database filename actually does begin with a ":" character you should prefix the filename with a pathname such as "./" to avoid ambiguity.

如果文件名是“:memory:”，那么为这个连接创建私有的、内存数据库。当数据库连接关闭时，这个内存数据库将不复存在。未来版本的SQLite可能使用以“:”开始的其他特殊文件名。当数据库文件名确实以“:”字符开始时，建议在文件名钱添加路径名前缀（例如“./”）来避免歧义。

If the filename is an empty string,temporary on-disk database will be created. This private database will be automatically deleted as soon as the database connection is closed.

如果文件名是空字符串，那么将创建私有的、临时磁盘数据库。只要数据库连接被关闭，这个私有数据库就会被自动删除。

The fourth parameter to sqlite3_open_v2() is the name of the sqlite3_vfs object that defines the operating system interface that the new database connection should use. If the fourth parameter is a NULL pointer then the default sqlite3_vfs object is used.

sqlite3_open_v2() 的第4个参数是sqlite3_vfs对象的名字，它定义了新数据连接应当使用的操作系统接口。如果第4个参数是NULL指针，则使用默认的sqlite3_vfs对象。

Note to Windows users: The encoding used for the filename argument of sqlite3_open() and sqlite3_open_v2() must be UTF-8,not whatever codepage is currently defined. Filenames containing international characters must be converted to UTF-8 prior to passing them into sqlite3_open() or sqlite3_open_v2().

Windows用户注意：sqlite3_open()和sqlite_open_v2()的文件名参数编码必须是UTF-8。包含国际字符的文件名必须在传递给sqlite_open()或sqlite_open_v2()之前被转换为UTF-8。