Создайте или пересмотрите функции SQL

int sqlite3_create_function(sqlite3 *db, const char *zFunctionName,
                            int nArg, int eTextRep, void *pApp,
                            void (*xFunc)(sqlite3_context*,int,
                            sqlite3_value**),
                            void (*xStep)(sqlite3_context*,int,
                            sqlite3_value**),
                            void (*xFinal)(sqlite3_context*));
int sqlite3_create_function16(sqlite3 *db, const void *zFunctionName,
                              int nArg, int eTextRep, void *pApp,
                              void (*xFunc)(sqlite3_context*,int,
                              sqlite3_value**),
                              void (*xStep)(sqlite3_context*,int,
                              sqlite3_value**),
                              void (*xFinal)(sqlite3_context*));
int sqlite3_create_function_v2(sqlite3 *db, const char *zFunctionName,
                               int nArg, int eTextRep, void *pApp,
                               void (*xFunc)(sqlite3_context*,int,
                               sqlite3_value**),
                               void (*xStep)(sqlite3_context*,int,
                               sqlite3_value**),
                               void (*xFinal)(sqlite3_context*),
                               void(*xDestroy)(void*));
int sqlite3_create_window_function(sqlite3 *db, const char *zFunctionName,
                                   int nArg, int eTextRep, void *pApp,
                                   void (*xStep)(sqlite3_context*,int,
                                   sqlite3_value**),
                                   void (*xFinal)(sqlite3_context*),
                                   void (*xValue)(sqlite3_context*),
                                   void (*xInverse)(sqlite3_context*,
                                   int,sqlite3_value**),
                                   void(*xDestroy)(void*));

Эти функции (коллективно известны как "режимы создания функции") используются, чтобы добавить функции SQL или совокупности или пересмотреть поведение существующих функций SQL или совокупностей. Единственными различиями между тремя "sqlite3_create_function*" является текстовое кодирование, ожидаемое для второго параметра (название создаваемой функции) и присутствие или отсутствие отзыва деструктора для указателя данных приложения. Функция sqlite3_create_window_function() подобна, но позволяет пользователю поставлять дополнительные функции обратного вызова, необходимые совокупным функциям окна.

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

Второй параметр это название функции SQL, которая будет создана или пересмотрена. Длина имени ограничивается 255 байтами в представлении UTF-8, не считая нулевого терминатора. Обратите внимание на то, что предел длины имени задан в байтах UTF-8, а не знаках или байтах UTF-16. Любая попытка создать функцию с более длинным именем приведет к возврату SQLITE_MISUSE.

Третий параметр (nArg) является количеством аргументов, которые функция SQL или совокупность берут. Если этот параметр -1, функция SQL или совокупность могут взять любое количество параметров между 0 и пределом sqlite3_limit( SQLITE_LIMIT_FUNCTION_ARG). Если третий параметр меньше -1 или больше 127, поведение не определено.

Четвертый параметр, eTextRep, определяет то, что текст, кодирующий эту функцию SQL, предпочитает для ее параметров. Приложение должно установить этот параметр в SQLITE_UTF16LE, если реализация функции вызывает sqlite3_value_text16le() на входе, SQLITE_UTF16BE, если внедрение вызывает sqlite3_value_text16be(), SQLITE_UTF16, если sqlite3_value_text16() используется, или SQLITE_UTF8 иначе. Та же самая функция SQL может быть зарегистрирована многократно, используя различное предпочтительное текстовое кодирование с различными внедрениями для каждого кодирования. Когда многократные внедрения той же самой функции будут доступны, SQLite выберет тот, который включает наименьшее количество преобразований объема данных.

Четвертый параметр может произвольно быть OR с SQLITE_DETERMINISTIC, чтобы сигнализировать, что функция будет всегда возвращать тот же самый результат, имея те же самые данные в единственном SQL-операторе. Большинство функций SQL детерминировано. Встроенная функция SQL random() это пример функции, которая не детерминирована. Планировщик запроса SQLite в состоянии выполнить дополнительную оптимизацию на детерминированных функциях, таким образом, использование флага SQLITE_DETERMINISTIC рекомендуется, если это возможно.

Четвертый параметр может также произвольно включать флаг SQLITE_DIRECTONLY, который, если есть, препятствует тому, чтобы функция была вызвана из VIEW, TRIGGER, ограничения CHECK, выражения создания колонки, выражения индекса или оператора Where частичных индексов.

Для лучшей безопасности флаг SQLITE_DIRECTONLY рекомендуется для всех определенные приложением функции SQL, которые не должны использоваться в VIEW, TRIGGER, ограничениях CHECK или других элементах схемы базы данных. Это особенно рекомендуется для функций SQL, которые имеют побочные эффекты или показывают статус внутреннего приложения. Без этого флага нападавший мог бы быть в состоянии изменить схему файла базы данных, чтобы включать вызовы функции с параметрами, выбранными нападавшим, когда файл базы данных будет открыт и читается.

Пятый параметр это произвольный указатель. Внедрение функции может получить доступ к этому указателю, используя sqlite3_user_data().

Шестые, седьмые и восьмые параметры, переданные трем функциям, это xFunc, xStep и xFinal, являются указателями на функции языка C, которые осуществляют функцию SQL или совокупность. Скалярная функция SQL требует внедрения только отзыва xFunc, NULL должен быть передан как параметры xStep и xFinal. Совокупная функция SQL требует внедрения xStep и xFinal, NULL должен быть передан для xFunc. Чтобы удалить существующую функцию SQL или совокупность, передайте NULL для всех трех отзывов функции.

Шестые, седьмые, восьмые и девятые параметры (xStep, xFinal, xValue и xInverse) для sqlite3_create_window_function это указатели на отзывы языка C, которые осуществляют новую функцию. xStep и xFinal должны оба быть не NULL. xValue и xInverse могут или оба быть NULL (в этом случае регулярная агрегатная функция создается) или должны оба быть не NULL (в этом случае новая функция может использоваться в качестве совокупной или в качестве совокупной функции окна). Больше деталей относительно внедрения совокупных функций окна доступно здесь.

Если заключительным параметром sqlite3_create_function_v2() или sqlite3_create_window_function() будет не NULL, то это деструктор для указателя данных приложения. Деструктор вызван, когда функция удалена, будучи перегруженной или когда соединение с базой данных закрывается. Деструктор также вызван, если запрос sqlite3_create_function_v2() неудачен. Когда отзыв деструктора вызван, ему передается отдельный аргумент, который является копией указателя данных приложения, который был пятым параметром sqlite3_create_function_v2().

Разрешено зарегистрировать многократные внедрения тех же самых функций с тем же самым именем, но с отличающимися числами аргументов или с отличающимся предпочтительным текстовым кодированием. SQLite будет использовать внедрение, которое наиболее соответствует пути, которым используется функция SQL. Реализация функции с неотрицательным параметром nArg это лучшее соответствие, чем реализация функции с отрицательным nArg. Функция, где предпочтительный текст, кодирующий, соответствует кодированию базы данных, является лучшим соответствием, чем функция, где кодирование отличается. Функция, где различие в кодировании между UTF16le и UTF16be, является более близким соответствием, чем функция, где различие в кодировании между UTF8 и UTF16.

Встроенные функции могут быть перегружены новыми определенными приложением функциями.

Определенные приложением функции могут вызвать другие интерфейсы SQLite. Однако, такие вызовы не должны закрывать соединение с базой данных, завершать или перезагружать подготовленный запрос, в котором работает функция.