Связывание значений с подготовленными запросами

int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,
                        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, sqlite3_int64);
int sqlite3_bind_null(sqlite3_stmt*, int);
int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));
int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
                         void(*)(void*), unsigned char encoding);
int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*));
int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);

В тексте SQL-запроса, вводимом в sqlite3_prepare_v2() и его вариантах, литералы могут быть заменены параметром, соответствующим одному из следующих шаблонов:

• ?
• ?NNN
• :VVV
• @VVV
• $VVV

В приведенных выше шаблонах NNN представляет целочисленную литерал, а VVV — буквенно-цифровой идентификатор. Значения этих параметров (также называемых «именами параметров хоста» или «параметрами SQL») можно задать с помощью функций sqlite3_bind_*, определённых здесь.

Первый аргумент функций sqlite3_bind_* всегда указывает на объект sqlite3_stmt, возвращённый из sqlite3_prepare_v2() или его вариантов.

Второй аргумент — это индекс параметра SQL, который нужно установить. Левый параметр SQL имеет индекс 1. Если один и тот же именованный параметр SQL используется более одного раза, то второе и последующие вхождения имеют тот же индекс, что и первое вхождение. Индекс именованных параметров можно найти с помощью API sqlite3_bind_parameter_index(), если это необходимо. Индекс параметров «?NNN» равен значению NNN. Значение NNN должно быть в пределах от 1 до параметра sqlite3_limit() SQLITE_LIMIT_VARIABLE_NUMBER (значение по умолчанию: 32766).

Третий аргумент — значение, которое нужно привязать к параметру. Если третий параметр функций sqlite3_bind_text(), sqlite3_bind_text16() или sqlite3_bind_blob() равен указателю NULL, то четвёртый параметр игнорируется, и результат будет таким же, как у sqlite3_bind_null(). Если третий параметр функции sqlite3_bind_text() не равен NULL, то он должен указывать на правильно сформированный текст UTF8. Если третий параметр функции sqlite3_bind_text16() не равен NULL, то он должен указывать на правильно сформированный текст UTF16. Если третий параметр функции sqlite3_bind_text64() не равен NULL, то он должен указывать на правильно сформированную строку Юникода, которая является UTF8, если шестой параметр равен SQLITE_UTF8, или UTF16 в противном случае.

Порядок байтов входного текста UTF16 определяется знаком порядка байтов (BOM, U+FEFF), найденным в первом символе, который удаляется, или в случае отсутствия BOM порядок байтов — это естественный порядок байтов хост-машины для sqlite3_bind_text16() или порядок байтов, указанный в шестом параметре для sqlite3_bind_text64(). Если входной текст UTF16 содержит некорректные символы Юникода, SQLite может изменить эти некорректные символы на символ замены Юникода: U+FFFD.

В тех функциях, которые имеют четвёртый аргумент, его значение — это количество байтов в параметре. Точнее, это количество байтов в значении, а не количество символов. Если четвёртый параметр функций sqlite3_bind_text() или sqlite3_bind_text16() имеет отрицательное значение, то длина строки — это количество байтов до первого нулевого терминатора. Если четвёртый параметр функции sqlite3_bind_blob() имеет отрицательное значение, то поведение не определено. Если четвёртый параметр функций sqlite3_bind_text(), sqlite3_bind_text16() или sqlite3_bind_text64() имеет неотрицательное значение, то этот параметр должен содержать смещение байта, на котором находился бы нулевой терминатор, если бы строка была завершена нулевым терминатором. Если нулевые символы встречаются по смещениям байтов меньше, чем значение четвёртого параметра, то результирующее значение строки будет содержать вложенные нули. Результат выражений, включающих строки с вложенными нулями, не определён.

Пятый аргумент интерфейсов привязки BLOB и строк управляет или указывает на срок существования объекта, на который указывает третий параметр. Существуют три варианта: (1) Может быть передан деструктор для удаления BLOB или строки после завершения работы SQLite с ним. Он вызывается для удаления BLOB или строки, даже если вызов API привязки завершился неудачно, за исключением случая, когда третий параметр — указатель NULL или четвёртый параметр имеет отрицательное значение. (2) Может быть передано специальное значение SQLITE_STATIC, чтобы указать, что приложение несёт ответственность за удаление объекта. В этом случае объект и указатель на него должны оставаться действительными до тех пор, пока подготовленный запрос не будет завершён или тот же параметр SQL не будет привязан к чему-то другому, что произойдёт раньше. (3) Может быть передано значение SQLITE_TRANSIENT, чтобы указать, что объект должен быть скопирован перед возвратом из sqlite3_bind_*. Объект и указатель на него должны оставаться действительными до этого момента. SQLite затем управляет сроком существования своей частной копии.

Шестой аргумент функции sqlite3_bind_text64() должен быть одним из значений SQLITE_UTF8, SQLITE_UTF16, SQLITE_UTF16BE или SQLITE_UTF16LE, чтобы указать кодировку текста в третьем параметре. Если шестой аргумент функции sqlite3_bind_text64() не является одним из разрешённых значений, показанных выше, или если кодировка текста отличается от кодировки, указанной шестым параметром, то поведение не определено.

Функция sqlite3_bind_zeroblob() привязывает BLOB длиной N, заполненный нулями. Zeroblob использует фиксированный объём памяти (только целое число для хранения размера) во время обработки. Zeroblobs предназначены для использования в качестве заглушек для BLOB, чьё содержимое впоследствии записывается с помощью последовательных операций ввода-вывода BLOB. Отрицательное значение для zeroblob приводит к созданию BLOB нулевой длины.

Функция sqlite3_bind_pointer(S,I,P,T,D) приводит к тому, что I-й параметр в подготовленном запросе S имеет SQL-значение NULL, но также связан с указателем P типа T. D — это либо указатель NULL, либо указатель на функцию-деструктор для P. SQLite вызовет деструктор D с единственным аргументом P, когда закончит использовать P. Параметр T должен быть статической строкой, предпочтительно строковой литералом. Функция sqlite3_bind_pointer() является частью интерфейса передачи указателей pointer passing interface, добавленного для SQLite 3.20.0.

Если любая из функций sqlite3_bind_* вызывается с указателем NULL для подготовленного запроса или с подготовленным запросом, для которого функция sqlite3_step() была вызвана позже, чем sqlite3_reset(), то вызов вернёт SQLITE_MISUSE. Если любая функция sqlite3_bind_() передаёт подготовленный запрос, который был завершён, результат не определён и, вероятно, вреден.

Привязки не очищаются функцией sqlite3_reset(). Непривязанные параметры интерпретируются как NULL.

Функции sqlite3_bind_* возвращают SQLITE_OK при успешном выполнении или код ошибки, если что-то пойдёт не так. SQLITE_TOOBIG может быть возвращён, если размер строки или BLOB превышает пределы, наложенные sqlite3_limit(SQLITE_LIMIT_LENGTH) или SQLITE_MAX_LENGTH. SQLITE_RANGE возвращается, если индекс параметра находится за пределами допустимого диапазона. SQLITE_NOMEM возвращается, если функция malloc() завершается неудачно.

См. также: sqlite3_bind_parameter_count(), sqlite3_bind_parameter_name() и sqlite3_bind_parameter_index().

См. также списки Объектов, Констант и Функций.