Привязка значений к подготовленным инструкциям

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 до значения параметра SQLITE_LIMIT_VARIABLE_NUMBER функции sqlite3_limit() (значение по умолчанию: 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 или SQLITE_UTF8_ZT, либо в кодировке UTF16 в противном случае.

Порядок байтов входного текста UTF16 определяется меткой порядка байтов (BOM, U+FEFF), обнаруженной в первом символе и удаляемой, либо, если BOM отсутствует, соответствует собственному порядку байтов хост-компьютера для sqlite3_bind_text16() или порядку байтов, указанному в шестом параметре для 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 или строки после того, как SQLite закончит их использовать. Он вызывается для освобождения BLOB или строки, даже если вызов API привязки завершается ошибкой, за исключением случаев, когда третий параметр — указатель NULL или четвёртый параметр отрицателен. (2) Можно передать специальную константу SQLITE_STATIC, чтобы указать, что приложение несёт ответственность за освобождение объекта. В этом случае объект и переданный указатель на него должны оставаться действительными до завершения подготовки инструкции или до привязки другого значения к тому же параметру SQL — в зависимости от того, что произойдёт раньше. (3) Можно передать константу SQLITE_TRANSIENT, чтобы указать, что объект необходимо скопировать до возврата из sqlite3_bind_*(). До этого момента объект и указатель на него должны оставаться действительными. После этого SQLite будет управлять временем жизни собственной копии.

Шестой аргумент (аргумент E) функции sqlite3_bind_text64(S,K,Z,N,D,E) должен иметь одно из значений SQLITE_UTF8, SQLITE_UTF8_ZT, SQLITE_UTF16, SQLITE_UTF16BE или SQLITE_UTF16LE, указывающих кодировку текста в третьем параметре Z. Специальное значение SQLITE_UTF8_ZT означает, что строковый аргумент закодирован в UTF-8 и завершён нулём. Иными словами, SQLITE_UTF8_ZT означает, что массив Z выделен как минимум для N+1 байта и байт Z[N] равен нулю. Если аргумент E функции sqlite3_bind_text64(S,K,Z,N,D,E) не соответствует ни одному из перечисленных выше допустимых значений или кодировка текста отличается от кодировки, указанной шестым параметром, поведение не определено.

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

Процедура sqlite3_bind_pointer(S,I,P,T,D) задаёт для I-го параметра в подготовленной инструкции S значение SQL NULL, но также связывает его с указателем P типа T. D — это либо указатель NULL, либо указатель на функцию-деструктор для P. Когда SQLite закончит использовать P, она вызовет деструктор D с единственным аргументом P, даже если вызов sqlite3_bind_pointer() завершится ошибкой. Из-за исторической особенности проектирования результаты не определены, если D равен SQLITE_TRANSIENT. Параметр T должен быть статической строкой, предпочтительно строковым литералом. Процедура sqlite3_bind_pointer() является частью интерфейса передачи указателей, добавленного в 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().

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