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

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 используется несколько раз, у вторых и последующих случаев есть тот же самый индекс, как первое возникновение. Индекс для названных параметров может искаться, используя sqlite3_bind_parameter_index() API. Индекс для параметров "?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, то это должен быть указатель на правильно построенную последовательность unicode, которая является UTF8, если шестой параметр SQLITE_UTF8, или UTF16 иначе.

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

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

Пятый аргумент BLOB и интерфейсам привязки последовательности управляет или указывает на целую жизнь объекта, на который ссылается третий параметр. Эти три варианта существуют: (1) деструктор А, чтобы избавиться от BLOB или последовательности после завершения работы с ним. Это вызывают, чтобы избавиться от 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 использует установленную сумму памяти (просто целое число, чтобы хранить его размер), в то время как это обрабатывается. Zeroblob предназначаются, чтобы служить заполнителями для BLOB, содержание которых позже написано, используя возрастающий BLOB I/O. Отрицательная величина для 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() является частью интерфейса прохождения указателя, добавленного в SQLite 3.20.0.

Если любой из sqlite3_bind_*() вызовут с NULL для подготовленного запроса или с подготовленным запросом0, для которого 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().