Crear o redefinir funciones 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*)
);

Estas funciones (colectivamente conocidas como "rutinas para la creación de funciones") se usan para añadir funciones SQL o agregados o para redefinir el comportamiento de funciones o agregados SQL existentes. La única diferencia entre estas funciones es la codificación de texto esperada para el segundo parámetro (el nombre de la función que se está creando) y la presencia o ausencia de una retrollamada de destrucción para el puntero a los datos de la aplicación.

El primer parámetro es la conexión de la base de datps a la que se añadirá la función SQL. Si una aplicación usa más de una conexión de base de datos, entonces la función SQL definida por la aplicación debe ser añadida a cada conexión por separado.

El segundo parámetro es el nombre de la función SQL a crear o redefinir. La longitud del nombre está limitada a 255 bytes en representación UTF-8, sin incluir el terminador nulo. Tener en cuenta que la limitación de longitud es en bytes UTF-8, no caracteres ni bytes UTF-16. Cualquier intento de crear una función con un nombre más largo producirá un error SQLITE_MISUSE.

El tercer parámetro nArg, es el número de argumentos que la función a agregado SQL toma. Si este parámetro es -1, entonces la función o agregado SQL podrá tomar cualquier número de argumentos entre 0 y el límite asignado por sqlite3_limit(SQLITE_LIMIT_FUNCTION_ARG). Si el tercer parámetro es menor que -1 o mayor que 127 entonces el comportamiento queda indefinido.

El cuarto parámetro, eTextRep, especifica que codificación de texto prefiere esta función SQL para sus parámetros. Todas las implementaciones de funciones SQL deben ser capaces de trabajar con UTF-8, UTF-16le o UTF-16be. Pero algunas implementaciones pueden ser más eficientes con una codificación que con otra. Una aplicación puede invocar a sqlite3_create_function() o sqlite3_create_function16() muchas veces con la misma función pero con diferentes valores de eTextRep. Cuando están disponibles múltiples implementaciones de la misma función, SQLite elegirá aquella que implique la menor cantidad de conversiones de datos. Si sólo hay una implementación que no se preocupa de qué codificación de texto se usa, entonces del cuarto argumento debe ser SQLITE_ANY.

El quinto parámetro es un puntero arbitrario. La implementación de la función puede obtener acceso a este puntero usando sqlite3_user_data().

El sexto, séptimo y octavo parámetros, xFunc, xStep y xFinal, son punteros a funciones en lenguaje C que implementan funciones o agregados SQL. Una función SQL escalar sólo requiere una implementación de la retrollamada xFunc; se deben pasar punteros NULL como parámetros xStep y xFinal. Una función agregada SQL requiere una implementación de xStep y xFinal y se debe pasar un puntero NULL para xFunc. Para borrar una función SQL o agregada, pasar punteros NULL para las tres funciones de retrollamada.

Si el noveno parámetro para sqlite3_create_function_v2() no es NULL, entonces es el destructor para el puntero de datos de la aplicación. El destructor es invocado cuando la función es borrada, ya sea porque estar sobrecargada o cuandos e cierra la conexión con la base de datos. El destructor se invoca también si la llamada a sqlite3_create_function_v2() falla. Cuando el destructor de la retrollamada del décimo parámetro es invocado, se pasa un único argumento que es una copia del puntero de datos de la aplicación que se usó como quinto parámetro en sqlite3_create_function_v2().

Está permitido registrar múltiples implementaciones de las mismas funciones con el mismo nombre pero cada una con diferente número de argumentos o diferentes preferencias para codificación de texto. SQLite usará la implementación que mejor coincida con el modo en que la función SQL se use. Una implementación de función con un parámetro nArg no negativo es una coincidencia mejor que una con un valor nArg negativo. Una función donde la codificación preferente de texto coincida con la codificación de la base de datos es mejor coincidencia que una función donde la codificación es diferente. Una función donde la diferencia de codificación es entre UTF16le y UTF16be es una coincidencia más cercana que una donde la diferencia es entre UTF8 y UTF16.

Las funciones internas pueden ser sobrecargadas por nuevas funciones definidas por la aplicación.

Una función definida por la aplicación puede llamar a otras funciones del API SQLite. Sin embargo, esas llamadas no deben cerrar la conexión de la base de datos ni finalizar o resetear la sentencia preparada en la que se está ejecutando la función.