创建或重新定义SQL函数

Small. Fast. Reliable.
Choose any three.

SQLite C接口

创建或重新定义SQL函数

int sqlite3_create_function（
  sqlite3 * db，
  const char * zFunctionName，
  int nArg，
  int eTextRep，
  无效* pApp，
  无效（* xFunc）（sqlite3_context *，int，sqlite3_value **），
  无效（* xStep）（sqlite3_context *，int，sqlite3_value **），
  无效（* xFinal）（sqlite3_context *）
）;
int sqlite3_create_function16（
  sqlite3 * db，
  const void * zFunctionName，
  int nArg，
  int eTextRep，
  无效* pApp，
  无效（* xFunc）（sqlite3_context *，int，sqlite3_value **），
  无效（* xStep）（sqlite3_context *，int，sqlite3_value **），
  无效（* xFinal）（sqlite3_context *）
）;
int sqlite3_create_function_v2（
  sqlite3 * db，
  const char * zFunctionName，
  int nArg，
  int eTextRep，
  无效* pApp，
  无效（* xFunc）（sqlite3_context *，int，sqlite3_value **），
  无效（* xStep）（sqlite3_context *，int，sqlite3_value **），
  无效（* xFinal）（sqlite3_context *），
  void（* xDestroy）（void *）
）;
int sqlite3_create_window_function（
  sqlite3 * db，
  const char * zFunctionName，
  int nArg，
  int eTextRep，
  无效* pApp，
  无效（* xStep）（sqlite3_context *，int，sqlite3_value **），
  无效（* xFinal）（sqlite3_context *），
  无效（* xValue）（sqlite3_context *），
  无效（* xInverse）（sqlite3_context *，int，sqlite3_value **），
  void（* xDestroy）（void *）
）;

这些函数（统称为“函数创建例程”）用于添加SQL函数或聚合或重新定义现有SQL函数或聚合的行为。这三个“ sqlite3_create_function *”例程之间的唯一区别是，第二个参数（创建的函数的名称）的预期文本编码以及应用程序数据指针是否存在析构函数回调。函数sqlite3_create_window_function（）类似，但是允许用户提供聚合窗口函数所需的额外回调函数。

第一个参数是要添加SQL函数的数据库连接。如果一个应用程序使用多个数据库连接，则必须将应用程序定义的SQL函数分别添加到每个数据库连接中。

第二个参数是要创建或重新定义的SQL函数的名称。名称的长度以UTF-8表示形式限制为255个字节，不包括零终止符。请注意，名称长度限制以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 标志，如果存在该标志，则防止从VIEW，TRIGGER，CHECK约束，生成的列表达式，索引表达式或部分索引的WHERE子句中调用该函数。

为了获得最佳安全性，建议对不需要在触发器，视图，CHECK约束或数据库架构的其他元素内使用的所有应用程序定义的SQL函数建议使用SQLITE_DIRECTONLY标志。对于具有副作用或显示内部应用程序状态的SQL函数，特别建议使用此标志。如果没有此标志，攻击者可能能够修改数据库文件的架构，以包含具有攻击者选择的参数的函数调用，然后在打开和读取数据库文件时，应用程序将执行该调用。

第五个参数是任意指针。该函数的实现可以使用sqlite3_user_data（）来访问此指针。

传递给三个“ sqlite3_create_function *”函数xFunc，xStep和xFinal的第六，第七和第八个参数是指向实现SQL函数或集合的C语言函数的指针。标量SQL函数仅需要实现xFunc回调；NULL指针必须作为xStep和xFinal参数传递。聚合SQL函数需要xStep的实现，并且xFinal必须传递NULL指针。要删除现有的SQL函数或聚合，请为所有三个函数回调传递NULL指针。

传递给sqlite3_create_window_function的第六，第七，第八和第九个参数（xStep，xFinal，xValue和xInverse）是指向实现新功能的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接口。但是，此类调用不能关闭数据库连接，也不能最终确定或重置函数在其中运行的准备好的语句。

另请参见对象，常量和函数的列表。