Создание или переопределение 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 выберет ту, которая требует наименьшего количества преобразования данных.

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

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

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

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

Шестой, седьмой и восьмой параметры, передаваемые трём функциям «sqlite3_create_function*», 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. Однако такие вызовы не должны закрывать соединение с базой данных, завершать или сбрасывать подготовленное утверждение, в котором выполняется функция.

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