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 */ );
Это открывает файл базы данных SQLite, как определено аргументом имени файла. Аргумент имени файла интерпретируется как UTF-8 для sqlite3_open() и sqlite3_open_v2() или UTF-16 в родном порядке байтов для sqlite3_open16(). Обработчик соединения с базой данных обычно возвращается в *ppDb, даже если ошибка происходит. Единственное исключение это если SQLite не может ассигновать память, чтобы хранить объект sqlite3, NULL впишут в *ppDb вместо указателя на объект sqlite3. Если база данных открыта (и/или создана) успешно, то вернется SQLITE_OK. Иначе вернется код ошибки. sqlite3_errmsg() или sqlite3_errmsg16() может использоваться, чтобы получить английское языковое описание ошибки после неудачи любого из sqlite3_open().
Кодировка по умолчанию будет UTF-8 для баз данных, созданных, используя sqlite3_open() или sqlite3_open_v2(). Кодировка по умолчанию для баз данных, созданных, используя sqlite3_open16(), это UTF-16 в родном порядке байт.
Происходит ли ошибка при открытии, ресурсы, связанные с обработчиком соединения с базой данных, должны быть высвобождены, передав его в sqlite3_close(), когда он больше не требуется.
sqlite3_open_v2() работает аналогично sqlite3_open() за исключением того, что он принимает два дополнительных параметра для дополнительного контроля над новым соединением с базой данных. Параметр флагов sqlite3_open_v2() должен включать, как минимум, одну из следующих трех комбинаций флага:
В дополнение к необходимым флагам также поддерживаются следующие дополнительные флаги:
Если 3-й параметр sqlite3_open_v2() не является одной из необходимых комбинаций, показанных выше, произвольно объединенной с другими SQLITE_OPEN_* bits, поведение не определено. Исторические версии SQLite тихо игнорировали избыточные биты в параметре флагов sqlite3_open_v2(), однако то поведение не могло бы быть осуществлено в будущих версиях SQLite и таким образом приложения не должны полагаться на него. Отметьте в особенности, что флаг SQLITE_OPEN_EXCLUSIVE ничего не делает в sqlite3_open_v2(). SQLITE_OPEN_EXCLUSIVE НЕ заставляют открытие терпеть неудачу, если база данных уже существует. SQLITE_OPEN_EXCLUSIVE предназначается для использования только интерфейсом VFS, но не sqlite3_open_v2().
Четвертый параметр sqlite3_open_v2() является названием объекта sqlite3_vfs, который определяет интерфейс операционной системы, который должно использовать новое соединение с базой данных. Если четвертый параметр NULL, тогда применяется умолчание объекта sqlite3_vfs.
Если имя файла ":memory:", частная, временная база данных в памяти создается для связи. Эта база данных в памяти исчезнет, когда соединение с базой данных будет закрыто. Будущие версии SQLite могли бы использовать дополнительные специальные имена файлов, которые начинаются с ":". Рекомендуется, когда имя файла базы данных на самом деле начинается с ":", вы должны поставить префикс имени файла с таким путем, как "./", чтобы избежать двусмысленности.
Если имя файла будет пустой строкой, то частная, временная база данных на диске будет создана. Эта частная база данных будет автоматически удалена, как только соединение с базой данных закрывается.
Если имена файлов URI позволены и аргумент имени файла начинается с "file:", тогда имя файла интерпретируется как URI. Интерпретация имени файла URI позволена, если флаг SQLITE_OPEN_URI установлен в третьем аргументе sqlite3_open_v2() или если это было позволено глобально, используя выбор SQLITE_CONFIG_URI в методе sqlite3_config() или опцией компиляции SQLITE_USE_URI. Интерпретация имени файла URI выключена по умолчанию, но будущие выпуски SQLite могли бы позволить интерпретацию имени файла URI по умолчанию. См. здесь подробности.
Имена файлов URI разобраны согласно RFC 3986. Если URI содержит авторизацию, то это должна быть пустая строка или последовательность "localhost", иначе ошибка возвращена. Компонент фрагмента URI, если есть проигнорирован.
SQLite использует компонент контура URI как название дискового файла, который содержит базу данных. Если путь начинается с '/', то это интерпретируется как абсолютный путь. Если путь не начинается с '/' (подразумевается, что часть секции авторизации опущена в URI), тогда путь интерпретируется как относительный. В Windows первый компонент абсолютного пути это спецификация привода (например, "C:").
Компонент запроса URI может содержать параметры, которые интерпретируются самим SQLite или реализацией VFS. SQLite и его встроенный VFS интерпретируют следующие параметры запроса:
Определение неизвестного параметра в компоненте запроса URI не является ошибкой. Будущие версии SQLite могли бы понять дополнительные параметры запроса. См. здесь подробности.
URI | Результат |
---|---|
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 | Ошибка. "darkstar" не признанная авторизация. |
file:///C:/Documents%20and%20Settings/fred/Desktop/data.db | Только Windows: Откройте файл "data.db" рабочего стола fred на диске C:. Обратите внимание на то, что экранировка %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". Используйте "ro" вместо этого: "file:data.db?mode=ro". |
Шестнадцатеричные escape-последовательности URI (%HH) поддерживаются в пути и запрашивают компоненты URI. Шестнадцатеричная escape-последовательность состоит из знака процента "%", сопровождаемого точно двумя шестнадцатеричными цифрами, определяющими значение октета. Прежде чем путь или компоненты запроса имени файла URI интерпретируются, они закодированы, используя UTF-8 и все шестнадцатеричные escape-последовательности, заменены единственным байтом, содержащим соответствующий октет. Если этот процесс производит недействительное кодирование UTF-8, результаты не определены.
Замечание для Windows: кодирование, используемое для аргумента имени файла sqlite3_open() и sqlite3_open_v2() должно быть UTF-8, независимо от того, какая кодовая страница в настоящее время определяется. Имена файлов, содержащие международные символы, должны быть преобразованы в UTF-8 до прохождения их в sqlite3_open() или sqlite3_open_v2().
Замечание для Windows Runtime: временный каталог должен быть установлен до запроса sqlite3_open() или sqlite3_open_v2(). Иначе различные особенности, которые требуют использования временных файлов, могут потерпеть неудачу.
См. также: sqlite3_temp_directory.