Интерфейс C/C++ для SQLite Version 3

1.0. Обзор

SQLite version 3.0 это новая версия SQLite, полученная из кодовой базы SQLite 2.8.13, но с несовместимым форматом файла и API. Версия 3.0 SQLite была создана, чтобы ответить на спрос на следующие особенности:

• Поддержка UTF-16.
• Определимый пользователем текст, сопоставляющий последовательности.
• Способность сохранить BLOB в индексированных столбцах.

Было необходимо многое переделать в версии 3.0, чтобы реализовать эти опции, потому что каждая из них требует несовместимых изменений формата файла базы данных. Другие несовместимые изменения, такие как очистка API, были введены в то же время в соответствии с теорией, что лучше избавляться от ваших несовместимых изменений сразу.

API version 3.0 подобен версии 2.X API, но с некоторыми важными изменениями. Наиболее заметно, что префикс "sqlite_", который есть в начале всех API-функций и структур данных, изменяется на "sqlite3_". Это избегает беспорядка между двумя API и позволяет связывать SQLite 2.X и SQLite 3.0 в то же время.

Нет никакого соглашения по тому, каков тип данных C для последовательности UTF-16 должен быть. Поэтому SQLite использует универсальный тип void*, чтобы относиться к последовательностям UTF-16. Клиентское программное обеспечение может привести void* к любому типу данных, который подходит для их системы.

2.0. Интерфейс C/C++

API SQLite 3.0 включает 83 отдельных функции в дополнение к нескольким структурам данных и #defines. К счастью, интерфейс не так сложен, как его размер подразумевает. Простые программы могут все еще обойтись только 3 функциями: sqlite3_open(), sqlite3_exec() и sqlite3_close(). Больше контроля над выполнением ядра базы данных обеспечивается, используя sqlite3_prepare_v2(), чтобы собрать запрос SQLite в байт-код, и sqlite3_step(), чтобы выполнить этот байт-код. Набор функций с именами, начинающимися с sqlite3_column_, используется, чтобы извлечь информацию о наборе результатов запроса. Много функций интерфейса парные с версиями для UTF-8 и UTF-16. Есть коллекция функций, чтобы осуществить определенные пользователями функции SQL и пользовательский текст, сопоставляющий последовательности.

2.1. Открытие и закрытие базы данных

typedef struct sqlite3 sqlite3;
int sqlite3_open(const char*, sqlite3**);
int sqlite3_open16(const void*, sqlite3**);
int sqlite3_close(sqlite3*);
const char *sqlite3_errmsg(sqlite3*);
const void *sqlite3_errmsg16(sqlite3*);
int sqlite3_errcode(sqlite3*);

sqlite3_open() возвращает код ошибки целого числа, а не указатель на строуктуру sqlite3, как делала version 2 интерфейса. Различие между sqlite3_open() и sqlite3_open16() в том, что sqlite3_open16() берет UTF-16 (в порядке байтов хоста) для названия файла базы данных. Если новый файл базы данных должен быть создан, то sqlite3_open16() устанавливает представление внутреннего текста UTF-16, тогда как sqlite3_open() устанавливает текстовое представление UTF-8.

Открытие и/или создание файла базы данных отсрочено, пока файл на самом деле не будет необходим. Это позволяет задать варианты и параметры, такие как родное текстовое представление и размер страницы по умолчанию, используя заявления PRAGMA.

sqlite3_errcode() возвращает код результата для нового главного вызова API. sqlite3_errmsg() вернет англоязычное текстовое сообщение об ошибке для новой ошибки. Сообщение об ошибке представляется в UTF-8 и будет эфемерно: это может исчезнуть на следующем вызове любой API-функции SQLite. sqlite3_errmsg16() работает как sqlite3_errmsg() за исключением того, что это возвращает сообщение об ошибке, представленное как UTF-16 в порядке байтов хоста.

Коды ошибок для версии 3 SQLite неизменны от версии 2. Они следующие:

#define SQLITE_OK           0   /* Successful result */
#define SQLITE_ERROR        1   /* SQL error or missing database */
#define SQLITE_INTERNAL     2   /* An internal logic error in SQLite */
#define SQLITE_PERM         3   /* Access permission denied */
#define SQLITE_ABORT        4   /* Callback routine requested an abort */
#define SQLITE_BUSY         5   /* The database file is locked */
#define SQLITE_LOCKED       6   /* A table in the database is locked */
#define SQLITE_NOMEM        7   /* A malloc() failed */
#define SQLITE_READONLY     8   /* Attempt to write a readonly database */
#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite_interrupt() */
#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
#define SQLITE_NOTFOUND    12   /* (Internal Only) Table or record not found */
#define SQLITE_FULL        13   /* Insertion failed because database is full */
#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
#define SQLITE_PROTOCOL    15   /* Database lock protocol error */
#define SQLITE_EMPTY       16   /* (Internal Only) Database table is empty */
#define SQLITE_SCHEMA      17   /* The database schema changed */
#define SQLITE_TOOBIG      18   /* Too much data for one row of a table */
#define SQLITE_CONSTRAINT  19   /* Abort due to contraint violation */
#define SQLITE_MISMATCH    20   /* Data type mismatch */
#define SQLITE_MISUSE      21   /* Library used incorrectly */
#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
#define SQLITE_AUTH        23   /* Authorization denied */
#define SQLITE_ROW         100  /* sqlite_step() has another row ready */
#define SQLITE_DONE        101  /* sqlite_step() has finished executing */

2.2. Выполнение SQL-операторов

typedef int (*sqlite_callback)(void*,int,char**, char**);
int sqlite3_exec(sqlite3*, const char *sql, sqlite_callback, void*, char**);

Функция sqlite3_exec() работает как это сделано в версии 2 SQLite. Ноль или больше SQL-операторов, определенных во втором параметре, собраны и выполнены. Результаты запроса возвращены к отзыву.

В SQLite version 3 sqlite3_exec просто обертка вокруг вызовов интерфейса подготовленного запроса.

typedef struct sqlite3_stmt sqlite3_stmt;
int sqlite3_prepare(sqlite3*, const char*, int, sqlite3_stmt**, const char**);
int sqlite3_prepare16(sqlite3*, const void*, int,
                      sqlite3_stmt**, const void**);
int sqlite3_finalize(sqlite3_stmt*);
int sqlite3_reset(sqlite3_stmt*);

Интерфейс sqlite3_prepare собирает единственный SQL-оператор в байт-код для более позднего выполнения. Этот интерфейс теперь предпочтительный способ получить доступ к базе данных.

SQL-оператор это последовательность UTF-8 для sqlite3_prepare(). sqlite3_prepare16() работает так же за исключением того, что это ожидает последовательность UTF-16 как вход SQL. Только первый SQL-оператор во входной строке собран. Пятый параметр заполнен указателем на следующий (несобранный) запрос SQLite во входной строке, если таковой есть. sqlite3_finalize() освобождает подготовленный SQL-оператор. Все подготовленные запросы должны быть завершены, прежде чем база данных может быть закрыта. sqlite3_reset() перезагружает подготовленный SQL-оператор так, чтобы это могло быть выполнено снова.

SQL-оператор может содержать символы формы "?", "?nnn" или ":aaa", где "nnn" целое число и "aaa" является идентификатором. Такие символы представляют неуказанные литеральные значения (или "подстановочные знаки"), чтобы быть заполненными позже интерфейсом sqlite3_bind. У каждого подстановочного знака есть связанное число, которое является его последовательностью в запросе или "nnn" в случае формы "?nnn". Позволено для того же самого подстановочного знака быть несколько раз в том же самом SQL-операторе, в этом случае все экземпляры того подстановочного знака будут заполнены тем же самым значением. У несвязанных подстановочных знаков есть значение NULL.

int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
int sqlite3_bind_double(sqlite3_stmt*, int, double);
int sqlite3_bind_int(sqlite3_stmt*, int, int);
int sqlite3_bind_int64(sqlite3_stmt*, int, long long int);
int sqlite3_bind_null(sqlite3_stmt*, int);
int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);

Есть ассортимент функций sqlite3_bind, используемых, чтобы назначить значения на подстановочные знаки в подготовленном SQL-операторе. Несвязанные подстановочные знаки интерпретируются как NULL. Привязки не перезагружаются sqlite3_reset(). Но подстановочные знаки могут быть переназначены к новым значениям после sqlite3_reset().

После того, как SQL-оператор был подготовлен (и произвольно связан), он выполняется, используя:

int sqlite3_step(sqlite3_stmt*);

sqlite3_step() вернет SQLITE_ROW, если это возвращает единственную строку набора результатов или SQLITE_DONE, если выполнение закончено нормально или из-за ошибки. Это могло бы также возвратить SQLITE_BUSY, если это неспособно открыть файл базы данных. Если возвращаемое значение SQLITE_ROW, то следующие функции могут использоваться, чтобы извлечь информацию о строке набора результатов:

const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
int sqlite3_column_count(sqlite3_stmt*);
const char *sqlite3_column_decltype(sqlite3_stmt *, int iCol);
const void *sqlite3_column_decltype16(sqlite3_stmt *, int iCol);
double sqlite3_column_double(sqlite3_stmt*, int iCol);
int sqlite3_column_int(sqlite3_stmt*, int iCol);
long long int sqlite3_column_int64(sqlite3_stmt*, int iCol);
const char *sqlite3_column_name(sqlite3_stmt*, int iCol);
const void *sqlite3_column_name16(sqlite3_stmt*, int iCol);
const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
int sqlite3_column_type(sqlite3_stmt*, int iCol);

sqlite3_column_count() возвращает количество колонок в наборе результатов. sqlite3_column_count() можно вызвать в любое время после sqlite3_prepare_v2(). sqlite3_data_count() работает так же, как sqlite3_column_count() кроме того, что это работает только после sqlite3_step(). Если предыдущий вызов sqlite3_step() возвратил SQLITE_DONE или код ошибки, то sqlite3_data_count() вернет 0, тогда как sqlite3_column_count() продолжит возвращать количество колонок в наборе результатов.

Возвращенные данные исследованы, используя другие функции sqlite3_column_***(), все из которых берут номер столбца в качестве их второго параметра. Колонки внесены в указатель слева направо, начиная с 0. Обратите внимание на то, что это отличается от параметров, которые внесены в указатель, начиная с единицы.

sqlite3_column_type() возвращает тип данных для значения в колонке N. Возвращаемое значение одно из:

#define SQLITE_INTEGER  1
#define SQLITE_FLOAT    2
#define SQLITE_TEXT     3
#define SQLITE_BLOB     4
#define SQLITE_NULL     5

sqlite3_column_decltype() возвращает текст, который является заявленным типом колонки в CREATE TABLE. Для выражения тип возвращения пустая строка. sqlite3_column_name() возвращает название колонки N. sqlite3_column_bytes() возвращает число байтов в колонке, которая имеет тип BLOB или число байтов в строке TEXT в UTF-8. sqlite3_column_bytes16() возвращает то же самое значение для BLOB, но TEXT исходит из UTF-16. sqlite3_column_blob() вернет данные BLOB. sqlite3_column_text() вернет данные TEXT как UTF-8. sqlite3_column_text16() вернет данные TEXT как UTF-16. sqlite3_column_int() вернет данные INTEGER в формате текущего хоста. sqlite3_column_int64() вернет данные 64-bit INTEGER. Finally, sqlite3_column_double() вернет данные с плавающей точкой.

Необязательно получать данные в формате, определенном sqlite3_column_type(). Если другой формат требуют, данные преобразовываются автоматически.

Преобразования формата данных могут лишить законной силы указатель, возвращенный предшествующими вызовами sqlite3_column_blob(), sqlite3_column_text() и/или sqlite3_column_text16(). Это бывает в следующих случаях:

• Начальное содержание BLOB и вызвана sqlite3_column_text() или sqlite3_column_text16(). Нулевой терминатор, возможно, должен быть добавлен к последовательности.

• Начальное содержание UTF-8 и вызвана sqlite3_column_bytes16() или sqlite3_column_text16(). Содержание должно быть преобразовано в UTF-16.

• Начальное содержание UTF-16 и вызвана sqlite3_column_bytes() или sqlite3_column_text(). Содержание должно быть преобразовано в UTF-8.

Обратите внимание на то, что преобразования между UTF-16be и UTF-16le всегда делаются на месте и не лишают законной силы обратный указатель, хотя, конечно, содержание буфера, на который указывает обратный указатель, будет изменено. Другие виды преобразования сделаны на месте, когда это возможно, но когда-то это невозможно, и в тех случаях обратные указатели лишены законной силы.

Самое безопасное и самое легкое, чтобы помнить политику: предположите что любой результат из

• sqlite3_column_blob()
,
• sqlite3_column_text()
или
• sqlite3_column_text16()

• sqlite3_column_bytes()
,
• sqlite3_column_bytes16()
,
• sqlite3_column_text()
или
• sqlite3_column_text16().

2.3. Определенные пользователями функции

Определенные пользователями функции могут быть созданы, используя следующий установленный порядок:

typedef struct sqlite3_value sqlite3_value;
int sqlite3_create_function(sqlite3 *, const char *zFunctionName, int nArg,
                            int eTextRep, void*,
                            void (*xFunc)(sqlite3_context*,int,
                                          sqlite3_value**),
                            void (*xStep)(sqlite3_context*,int,
                                          sqlite3_value**),
                            void (*xFinal)(sqlite3_context*));

int sqlite3_create_function16(sqlite3*, const void *zFunctionName,
                              int nArg, int eTextRep, void*,
                              void (*xFunc)(sqlite3_context*,int,
                                            sqlite3_value**),
                              void (*xStep)(sqlite3_context*,int,
                                            sqlite3_value**),
                              void (*xFinal)(sqlite3_context*));
#define SQLITE_UTF8     1
#define SQLITE_UTF16    2
#define SQLITE_UTF16BE  3
#define SQLITE_UTF16LE  4
#define SQLITE_ANY      5

nArg определяет количество аргументов функции. 0 указывает, что любое количество аргументов позволено. eTextRep определяет то, в чем текстовые значения представления, как ожидают, будут для аргументов этой функции. Значение этого параметра должно быть одним из параметров, определенных выше. Версия 3 SQLite позволяет многократные внедрения той же самой функции, используя различные текстовые представления. Ядро базы данных выбирает функцию по логике минимизации количества требуемых текстовых преобразований.

Нормальные функции определяют только xFunc и оставляют xStep и xFinal = NULL. Агрегатные функции определяют xStep и xFinal и оставляют xFunc = NULL. Нет отдельного sqlite3_create_aggregate() API.

Имя функции определяется в UTF-8. Отдельный sqlite3_create_function16() API работает аналогично sqlite_create_function() за исключением того, что имя функции определяется в порядке байтов хоста в UTF-16.

Заметьте, что параметры функций теперь указатели на структуры sqlite3_value вместо указателей на последовательности как в версии SQLite version 2.X. Следующий установленный порядок используется, чтобы извлечь полезную информацию из этих значений:

const void *sqlite3_value_blob(sqlite3_value*);
int sqlite3_value_bytes(sqlite3_value*);
int sqlite3_value_bytes16(sqlite3_value*);
double sqlite3_value_double(sqlite3_value*);
int sqlite3_value_int(sqlite3_value*);
long long int sqlite3_value_int64(sqlite3_value*);
const unsigned char *sqlite3_value_text(sqlite3_value*);
const void *sqlite3_value_text16(sqlite3_value*);
int sqlite3_value_type(sqlite3_value*);

Реализации функции используют следующий API, чтобы приобрести контекст и сообщить о результатах:

void *sqlite3_aggregate_context(sqlite3_context*, int nbyte);
void *sqlite3_user_data(sqlite3_context*);
void sqlite3_result_blob(sqlite3_context*, const void*, int n,
                         void(*)(void*));
void sqlite3_result_double(sqlite3_context*, double);
void sqlite3_result_error(sqlite3_context*, const char*, int);
void sqlite3_result_error16(sqlite3_context*, const void*, int);
void sqlite3_result_int(sqlite3_context*, int);
void sqlite3_result_int64(sqlite3_context*, long long int);
void sqlite3_result_null(sqlite3_context*);
void sqlite3_result_text(sqlite3_context*, const char*, int n, void(*)(void*));
void sqlite3_result_text16(sqlite3_context*, const void*, int n, void(*)(void*));
void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
void *sqlite3_get_auxdata(sqlite3_context*, int);
void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*));

2.4. Определенные пользователями последовательности сопоставления

Следующий установленный порядок используется, чтобы осуществить определенные пользователями последовательности сопоставления:

sqlite3_create_collation(sqlite3*, const char *zName, int eTextRep, void*,
                         int(*xCompare)(void*,int,const void*,int,const void*));
sqlite3_create_collation16(sqlite3*, const void *zName, int eTextRep, void*,
                           int(*xCompare)(void*,int,const void*,
                           int, const void*));
sqlite3_collation_needed(sqlite3*, void*,
                         void(*)(void*,sqlite3*,int eTextRep,const char*));
sqlite3_collation_needed16(sqlite3*, void*,
                           void(*)(void*,sqlite3*,int eTextRep,const void*));

sqlite3_create_collation() определяет имя последовательности сопоставления и функцию сравнения, чтобы осуществить ту последовательность сопоставления. Функция сравнения используется только для сравнения текстовых значений. eTextRep это одно из SQLITE_UTF8, SQLITE_UTF16LE, SQLITE_UTF16BE или SQLITE_ANY, чтобы определить, с каким текстовым представлением функция сравнения работает. Отдельные функции сравнения могут существовать для той же самой последовательности сопоставления для каждого из текстовых представлений UTF-8, UTF-16LE и UTF-16BE. sqlite3_create_collation16() работает подобно sqlite3_create_collation() за исключением того, что имя сопоставления определяется в порядке байтов хоста UTF-16 вместо UTF-8.

sqlite3_collation_needed() регистрирует отзыв, который вызовет ядро базы данных, если это столкнется с неизвестной последовательностью сопоставления. Отзыв может искать соответствующую функцию сравнения и вызвать по мере необходимости sqlite_3_create_collation(). Четвертый параметр отзыва это название последовательности сопоставления в UTF-8. Для sqlite3_collation_need16() отзыв посылает имя последовательности сопоставления в порядке байтов текущего хоста в UTF-16.