Установление Результата 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*,sqlite3_uint64,
                           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 little endian и UTF-16 big endian. Интерфейс sqlite3_result_text64() устанавливает значение возврата функции, определенной приложением, в текстовую строку в кодировке, указанной пятым (и последним) параметром, который должен быть одним из SQLITE_UTF8, SQLITE_UTF16, SQLITE_UTF16BE или SQLITE_UTF16LE. SQLite берет текстовый результат от приложения из второго параметра интерфейсов sqlite3_result_text*. Если третий параметр любого из интерфейсов sqlite3_result_text*, кроме sqlite3_result_text64(), отрицателен, то SQLite вычисляет длину строки, ищет в втором параметре первый нулевой символ. Если третий параметр интерфейсов sqlite3_result_text* неотрицателен, тогда столько байт (а не символов) текста, на который указывает второй параметр, принимается как результат функции, определенной приложением. Если третий параметр неотрицателен, то он должен быть смещением в байтах в строке, где бы появился терминатор NUL, если бы строка была NUL-законченной. Если какие-либо нулевые символы встречаются в строке в смещении байта, меньшем значения третьего параметра, то результирующая строка будет содержать вложенные NUL-символы, а результат выражений, работающих со строками с вложенными NUL-символами, не определен. Если четвертый параметр интерфейсов 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(), когда кодировка не UTF8, если входной UTF16 начинается с маркера порядка байтов (BOM, U+FEFF), то BOM удаляется из строки, и остальная часть строки интерпретируется в соответствии с порядком байтов, указанным BOM. Порядок байтов, указанный BOM в начале текста, переопределяет порядок байтов, указанный процедурой интерфейса. Например, если sqlite3_result_text16le() вызывается с текстом, начинающимся с байтов 0xfe, 0xff (маркер порядка байтов big-endian), то первые два байта входных данных пропускаются, а оставшиеся входные данные интерпретируются как UTF16BE-текст.

Для входного текста UTF16 для процедур sqlite3_result_text16(), sqlite3_result_text16be(), sqlite3_result_text16le() и sqlite3_result_text64(), если текст содержит недопустимые символы UTF16, недопустимые символы могут быть преобразованы в универсальный заполнитель, 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), за исключением того, что он также связывает указатель языка хоста P или тип T с этим значением NULL таким образом, что указатель может быть извлечен в определенной приложением SQL-функции с помощью sqlite3_value_pointer(). Если параметр D не равен NULL, то он является указателем на деструктор для параметра P. SQLite вызывает D с P в качестве единственного аргумента, когда SQLite завершает работу с P. Параметр T должен быть статической строкой и предпочтительно строковым литералом. Процедура sqlite3_result_pointer() является частью интерфейса передачи указателей, добавленного для SQLite 3.20.0.

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

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