Установка результата SQL-функции

void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
void sqlite3_result_blob64(sqlite3_context*,const void*,
                           sqlite3_uint64,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_error_toobig(sqlite3_context*);
void sqlite3_result_error_nomem(sqlite3_context*);
void sqlite3_result_error_code(sqlite3_context*, int);
void sqlite3_result_int(sqlite3_context*, int);
void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
void sqlite3_result_null(sqlite3_context*);
void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
void sqlite3_result_text64(sqlite3_context*, const char *z, sqlite3_uint64 n,
                           void(*)(void*), unsigned char encoding);
void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
void sqlite3_result_pointer(sqlite3_context*, void*,const char*,void(*)(void*));
void sqlite3_result_zeroblob(sqlite3_context*, int n);
int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n);

Эти процедуры используются обратными вызовами xFunc или xFinal, реализующими SQL-функции и агрегаты. Дополнительные сведения см. в описаниях sqlite3_create_function() и sqlite3_create_function16().

Эти функции очень похожи на семейство функций привязки параметров, используемых для привязки значений к параметрам узла в подготовленных инструкциях. Дополнительные сведения см. в документации по параметрам SQL.

Интерфейс sqlite3_result_blob() задает результат определяемой приложением функции как BLOB, содержимое которого указывает второй параметр и длина которого составляет N байт, где N — третий параметр.

Интерфейсы sqlite3_result_zeroblob(C,N) и sqlite3_result_zeroblob64(C,N) задают результат определяемой приложением функции как BLOB размером N байт, содержащий только нулевые байты.

Интерфейс sqlite3_result_double() задает результат определяемой приложением функции как число с плавающей точкой, указанное вторым аргументом.

Функции sqlite3_result_error() и sqlite3_result_error16() заставляют реализованную SQL-функцию генерировать исключение. SQLite использует строку, на которую указывает второй параметр sqlite3_result_error() или sqlite3_result_error16(), в качестве текста сообщения об ошибке. SQLite интерпретирует строку сообщения об ошибке из sqlite3_result_error() как UTF-8. SQLite интерпретирует строку из sqlite3_result_error16() как UTF-16, используя те же правила определения порядка байтов, что и sqlite3_bind_text16(). Если третий параметр sqlite3_result_error() или sqlite3_result_error16() отрицателен, SQLite считает сообщением об ошибке весь текст до первого нулевого символа. Если третий параметр sqlite3_result_error() или sqlite3_result_error16() неотрицателен, SQLite берет из второго параметра указанное количество байтов (не символов) в качестве сообщения об ошибке. Перед возвратом процедуры sqlite3_result_error() и sqlite3_result_error16() создают собственную копию текста сообщения об ошибке. Поэтому вызывающая функция может освободить или изменить текст после их возврата без каких-либо последствий. Функция sqlite3_result_error_code() изменяет код ошибки, возвращаемый SQLite в результате ошибки в функции. По умолчанию код ошибки — SQLITE_ERROR. Последующий вызов sqlite3_result_error() или sqlite3_result_error16() сбрасывает код ошибки в SQLITE_ERROR.

Интерфейс sqlite3_result_error_toobig() заставляет SQLite выдать ошибку, указывающую, что строка или BLOB слишком велики для представления.

Интерфейс sqlite3_result_error_nomem() заставляет SQLite выдать ошибку, указывающую на сбой выделения памяти.

Интерфейс sqlite3_result_int() задает возвращаемое значение определяемой приложением функции как 32-разрядное целое число со знаком, указанное вторым аргументом. Интерфейс sqlite3_result_int64() задает возвращаемое значение определяемой приложением функции как 64-разрядное целое число со знаком, указанное вторым аргументом.

Интерфейс sqlite3_result_null() задает возвращаемое значение определяемой приложением функции как NULL.

Интерфейсы sqlite3_result_text(), sqlite3_result_text16(), sqlite3_result_text16le() и sqlite3_result_text16be() задают возвращаемое значение определяемой приложением функции как текстовую строку в кодировке UTF-8, UTF-16 с собственным порядком байтов, UTF-16 с порядком байтов от младшего к старшему или UTF-16 с порядком байтов от старшего к младшему соответственно. Интерфейс sqlite3_result_text64(C,Z,N,D,E) задает возвращаемое значение определяемой приложением функции как текстовую строку в кодировке, указанной параметром E, который должен быть одним из следующих значений: SQLITE_UTF8, SQLITE_UTF8_ZT, SQLITE_UTF16, SQLITE_UTF16BE или SQLITE_UTF16LE. Специальное значение SQLITE_UTF8_ZT означает, что результирующий текст представлен в UTF-8 и завершается нулевым байтом. Иными словами, SQLITE_UTF8_ZT означает, что массив Z содержит не менее N+1 байта и что Z[N] равен нулю. SQLite получает текстовый результат приложения из второго параметра интерфейсов sqlite3_result_text*. Если третий параметр любого интерфейса sqlite3_result_text*, кроме sqlite3_result_text64(), отрицателен, SQLite самостоятельно вычисляет длину строки, выполняя поиск первого нулевого символа во втором параметре. Если третий параметр интерфейсов sqlite3_result_text* неотрицателен, в качестве результата определяемой приложением функции используется указанное количество байтов (не символов) текста, на который указывает второй параметр. Если третий параметр неотрицателен, он должен указывать смещение в байтах внутри строки, в котором находился бы завершающий нулевой байт, если бы строка завершалась нулевым байтом. Если в строке встречаются нулевые символы со смещением в байтах, меньшим значения третьего параметра, результирующая строка будет содержать встроенные нулевые символы, а результат выражений, работающих со строками, содержащими встроенные нулевые символы, не определен. Если четвертый параметр интерфейсов sqlite3_result_text* или sqlite3_result_blob — указатель, отличный от NULL, SQLite вызывает указанную функцию как деструктор текстового результата или результата BLOB после завершения работы с ним. Если четвертый параметр интерфейсов sqlite3_result_text* или sqlite3_result_blob — специальная константа SQLITE_STATIC, SQLite предполагает, что текстовый результат или результат BLOB находится в постоянной области памяти, и не копирует содержимое параметра и не вызывает для него деструктор после завершения работы с результатом. Если четвертый параметр интерфейсов sqlite3_result_text* или sqlite3_result_blob — специальная константа SQLITE_TRANSIENT, SQLite перед возвратом создает копию результата в области памяти, выделенной с помощью sqlite3_malloc().

Для процедур sqlite3_result_text16(), sqlite3_result_text16le() и sqlite3_result_text16be(), а также для sqlite3_result_text64(), если кодировка не UTF-8, если входной текст UTF-16 начинается с маркера порядка байтов (BOM, U+FEFF), BOM удаляется из строки, а остальная часть строки интерпретируется в соответствии с порядком байтов, указанным в BOM. Порядок байтов, указанный в начале текста с помощью BOM, имеет приоритет над порядком байтов, заданным процедурой интерфейса. Так, например, если вызвать sqlite3_result_text16le() с текстом, начинающимся с байтов 0xfe, 0xff (BOM для порядка байтов от старшего к младшему), первые два входных байта пропускаются, а оставшаяся часть входных данных интерпретируется как текст UTF16BE.

Если входной текст UTF-16 для процедур sqlite3_result_text16(), sqlite3_result_text16be(), sqlite3_result_text16le() и sqlite3_result_text64() содержит недопустимые символы UTF-16, эти символы могут быть преобразованы в символ замены Unicode U+FFFD.

Интерфейс sqlite3_result_value() задает результат определяемой приложением функции как копию объекта незащищенного sqlite3_value, указанного вторым параметром. Интерфейс sqlite3_result_value() создает копию sqlite3_value, поэтому указанный в параметре sqlite3_value можно изменить или освободить после возврата sqlite3_result_value() без каких-либо последствий. Защищенный объект sqlite3_value всегда можно использовать там, где требуется незащищенный sqlite3_value, поэтому с этим интерфейсом можно использовать объект sqlite3_value любого из этих типов.

Интерфейс sqlite3_result_pointer(C,P,T,D) задает результат как значение SQL NULL, как и sqlite3_result_null(C), но также связывает с этим значением NULL указатель P или тип T из языка узла, чтобы этот указатель можно было получить внутри определяемой приложением SQL-функции с помощью sqlite3_value_pointer(). Если параметр D не равен NULL, он представляет собой указатель на деструктор для параметра P. Когда SQLite завершает работу с P, SQLite вызывает D, передавая P в качестве единственного аргумента. Параметр T должен быть статической строкой, предпочтительно строковым литералом. Процедура sqlite3_result_pointer() входит в состав интерфейса передачи указателей, добавленного в SQLite 3.20.0.

Если эти процедуры вызываются из потока, отличного от того, в котором находится определяемая приложением функция, получившая указатель sqlite3_context, результаты не определены.

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