Sqlite 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*));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*));

Estas funciones (conocidas colectivamente como “rutinas de creación de funciones”) se utilizan para agregar funciones o agregados SQL o para redefinir el comportamiento de funciones o agregados SQL existentes. Las únicas diferencias entre las tres rutinas “sqlite3_create_function *” son 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 devolución de llamada de destructor para el puntero de datos de la aplicación. La función sqlite3_create_window_function () es similar, pero permite al usuario proporcionar las funciones de devolución de llamada adicionales necesarias para las funciones de ventana agregadas.

El primer parámetro es la conexión de la base de datos a la que se agregará la función SQL. Si una aplicación utiliza más de una conexión de base de datos, las funciones SQL definidas por la aplicación deben agregarse a cada conexión de base de datos por separado.

El segundo parámetro es el nombre de la función SQL que se va a crear o redefinir. La longitud del nombre está limitada a 255 bytes en una representación UTF-8, sin incluir el terminador cero. Tenga en cuenta que el límite de longitud del nombre está en bytes UTF-8, no en caracteres ni bytes UTF-16. Cualquier intento de crear una función con un nombre más largo resultará en la devolución de SQLITE_MISUSE.

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

El cuarto parámetro, eTextRep, especifica qué texto codificado prefiere esta función SQL para sus parámetros. La aplicación debe establecer este parámetro en SQLITE_UTF16LE si la implementación de la función invoca sqlite3_value_text16le () en una entrada, o SQLITE_UTF16BE si la implementación invoca sqlite3_value_text16be () en una entrada, o SQLITE_UTF16 si se usa sqlite3_value_text16 () o SQLITE_UTF8 de lo contrario. La misma función SQL puede registrarse varias veces utilizando diferentes codificaciones de texto preferidas, con diferentes implementaciones para cada codificación. Cuando hay disponibles múltiples implementaciones de la misma función, SQLite elegirá la que implique la menor cantidad de conversión de datos.

Opcionalmente, el cuarto parámetro se puede aplicar en OR con SQLITE_DETERMINISTIC para señalar que la función siempre devolverá el mismo resultado dadas las mismas entradas dentro de una sola declaración SQL. La mayoría de las funciones de SQL son deterministas. La función SQL aleatoria () incorporada es un ejemplo de una función que no es determinista. El planificador de consultas SQLite puede realizar optimizaciones adicionales en funciones deterministas, por lo que se recomienda el uso del indicador SQLITE_DETERMINISTIC siempre que sea posible.

El cuarto parámetro también puede incluir opcionalmente el indicador SQLITE_DIRECTONLY, que si está presente evita que la función sea invocada desde VIEWs, TRIGGER, restricciones CHECK, expresiones de columna generadas, expresiones de índice o la cláusula WHERE de índices parciales.

Para mayor seguridad, se recomienda el indicador SQLITE_DIRECTONLY para todas las funciones SQL definidas por la aplicación que no necesitan ser utilizadas dentro de desencadenadores, vista, restricciones CHECK u otros elementos del esquema de la base de datos. Estos indicadores se recomiendan especialmente para funciones SQL que tienen efectos secundarios o revelan el estado interno de la aplicación. Sin esta bandera, un atacante podría modificar el esquema de un archivo de base de datos para incluir invocaciones de la función con parámetros elegidos por el atacante, que la aplicación ejecutará cuando se abra y lea el archivo de base de datos.

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 ().

Los parámetros sexto, séptimo y octavo pasados ​​a las tres funciones “sqlite3_create_function *”, xFunc, xStep y xFinal, son indicadores de funciones en lenguaje C que implementan la función SQL o agregado. Una función de SQL escalar requiere una implementación de la devolución de llamada xFunc solamente; Los punteros NULL deben pasarse como parámetros xStep y xFinal. Una función SQL agregada requiere una implementación de xStep y xFinal y se debe pasar un puntero NULL para xFunc. Para eliminar una función SQL existente o un agregado, pase punteros NULL para las tres devoluciones de llamada de función.

Los parámetros sexto, séptimo, octavo y noveno (xStep, xFinal, xValue y xInverse) pasados ​​a sqlite3_create_window_function son indicadores de devoluciones de llamada en lenguaje C que implementan la nueva función. xStep y xFinal no deben ser NULL. xValue y xInverse pueden ser ambos NULL, en cuyo caso se crea una función agregada regular, o ambos deben ser no NULL, en cuyo caso la nueva función puede usarse como una función de ventana agregada o agregada. Más detalles sobre la implementación de funciones de ventana agregadas están disponibles aquí.

Si el parámetro final de sqlite3_create_function_v2 () o sqlite3_create_window_function () no es NULL, entonces es un destructor para el puntero de datos de la aplicación. El destructor se invoca cuando se elimina la función, ya sea por sobrecarga o cuando se cierra la conexión a la base de datos. El destructor también se invoca si falla la llamada a sqlite3_create_function_v2 (). Cuando se invoca la devolución de llamada del destructor, se le pasa un único argumento que es una copia del puntero de datos de la aplicación, que era el quinto parámetro de sqlite3_create_function_v2 ().

Se permite registrar múltiples implementaciones de las mismas funciones con el mismo nombre pero con diferentes números de argumentos o diferentes codificaciones de texto preferidas. SQLite usará la implementación que más se acerque a la forma en que se usa la función SQL. Una implementación de función con un parámetro nArg no negativo es una mejor coincidencia que una implementación de función con un nArg negativo. Una función en la que la codificación de texto preferida coincide con la codificación de la base de datos es mejor que una función en la que 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 función donde la diferencia de codificación es entre UTF8 y UTF16.

Las funciones integradas pueden estar sobrecargadas por las nuevas funciones definidas por la aplicación.

Una función definida por la aplicación puede llamar a otras interfaces SQLite. Sin embargo, dichas llamadas no deben cerrar la conexión de la base de datos ni finalizar o restablecer la instrucción preparada en la que se ejecuta la función.

Consulte también las listas de objetos, constantes y funciones.