sqlite.h


Asignar el resultado de una función SQL

void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
void sqlite3_result_double(sqlite3_context*, double);
void sqlite3_result_error(sqlite3_context*, const char*, int);
void sqlite3_result_error16(sqlite3_context*, const void*, int);
void sqlite3_result_error_toobig(sqlite3_context*);
void sqlite3_result_error_nomem(sqlite3_context*);
void sqlite3_result_error_code(sqlite3_context*, int);
void sqlite3_result_int(sqlite3_context*, int);
void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
void sqlite3_result_null(sqlite3_context*);
void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
void sqlite3_result_zeroblob(sqlite3_context*, int n);

Estas funciones se usan por las retrollamadas xFunc y xFinal que implementan funciones y agregados SQL. Ver sqlite3_create_function() y sqlite3_create_function16() para información adicional.

Estas funciones trabajan de un modo muy parecido a la famila de funciones de enlace de parámetros que se usan para asociar parámetros del host en sentencias preparadas.

La función sqlite3_result_blob() asigna el resultado de una función definida por la aplicación para ser el BLOB cuyo contenido es apuntado por el segundo parámetro y que tiene N bytes de longitud, donde N es el tercer parámetro.

La función sqlite3_result_zeroblob() asigna el resultado de la función definida por la aplicación para ser un BLOB que contenga N bytes, todos con el valor cero y N bytes de longitud, donde N es el valor del segundo parámetro.

La función sqlite3_result_double() asigna el resultado desde una función definida por la aplicación para que sea un valor en punto flotante especificado por su segundo argumento.

Las funciones sqlite3_result_error() y sqlite3_result_error16() hacen que la función SQL implementada provoque una excepción. SQLite usa la cadena apuntada por el segundo parámetro de sqlite3_result_error() o sqlite3_result_error16() como el texto de un mensaje de error. SQLite interpreta la cadena de mensaje de error de sqlite3_result_error() como UTF-8. SQLite interpreta la cadena de sqlite3_result_error16() como UTF-16 en orden de bytes nativo. Si el tercer parámetro para sqlite3_result_error() o sqlite3_result_error16() es negativo SQLite toma como mensaje de error todo el texto hasta que encuentre el primer carácter nulo. Si el tercer parámetro de sqlite3_result_error() o sqlite3_result_error16() es no negativo SQLite toma esos bytes (no caracteres) del segundo parámetro como mensaje de error. Las funciones sqlite3_result_error() y sqlite3_result_error16() hacen una copia privada del texto del mensaje de error antes de regresar. Por lo tanto, la función que llama puede liberar el texto después de que retornen sin daño alguno. La función sqlite3_result_error_code() cambia el código de error retornado por SQLite como un resultado de un error en una función. Por defecto, el código de error es SQLITE_ERROR. Una llamada subsiguiente a sqlite3_result_error() o sqlite3_result_error16() resetea el código de error a SQLITE_ERROR.

La función sqlite3_result_toobig() hace que SQLite lance un error indicando que una cadena o un BLOB es demasiado largo para representarlo.

La función sqlite3_result_nomem() hace que SQLite lance un error indicando que una asignación de memoria ha fallado.

La función sqlite3_result_int() establece el valor de retorno de la función definida por la aplicación para que sea un valor de 32 bits con signo dado en el segundo argumento. La función sqlite3_result_int64() establece el valor de retorno de la función definida por la aplicación para que sea un entero con signo de 64 bits dado en el segundo parámetro.

La función sqlite3_result_null() establece el valor de retorno de la función definida por la a aplicación a NULL.

Las funciones sqlite3_result_text(), sqlite3_result_text16(), sqlite3_result_text16le() y sqlite3_result_text16be() asignan el valor de retorno de la función definida por la aplicación para ser una cadena de texto representada en UTF-8, UTF-16 en orden de bytes nativo, UTF-16 little endian o UTF-16 big endian, respectivamente. SQLite toma el el resultado de texto desde la aplicación del segundo parámetro de las funciones sqlite3_result_text*. Si el tercer parámetro es negativo, entonces SQLite toma caracteres del texto del segundo parámetro hasta encontrar el primer carácter nulo. Si el tercer parámetro de sqlite3_result_text* no es negativo, entonces se toma ese número de bytes(no caracteres) del texto apuntado por el segundo parámetro como resultado de la función definida por la aplicación. Si el tercer parámetro es no negativo, entonces debe ser un desplazamiento de bytes en la cadena donde el terminador nulo debería aparecer si la cadena fuera terminada en nulo. Si algún carácter nulo aparece en la cadena en un desplazamiento de bytes que es menor del valor del tercer parámetro, entonces la cadena resultante podrá contener NULs embebidos y el resultado de las expresiones que operan en cadenas con NULs embebidos es indefinido. Si el cuarto parámetro de sqlite3_result_text* o sqlite3_result_blob es un puntero no nulo, SQLite llama a esa función como el destructor del resultado de texto o BLOB cuando ha finalizado de usar ese resultado. Si el cuarto parámetro de sqlite3_result_text* o sqlite3_result_blob es la constante especial SQLITE_STATIC, SQLite asume que el resultado de texto o BLOB está en el espacio de constantes y no copia el contenido del parámetro ni llama al destructor del contenido cuando ha terminado de usar ese resultado. Si el cuarto parámetro del sqlite3_result_text* o sqlite3_result_blob es la constante especial SQLITE_TRANSIENT SQLite hace una copia del resultado en el espacio obtenido de sqlite3_malloc() antes de retornar.

La función sqlite3_result_value() asigna el resultado de la aplicación definida por la aplicación para que se una copia del objeto no protegido sqlite3_value especificado por el segundo parámetro. La función sqlite3_result_value() hace una copia de sqlite3_value de modo que el sqlite3_value especificado en el parámetro puede cambiar o ser liberado despues de que sqlite3_result_value() regrese sin daño alguno. Un objeto sqlite3_value protegido puede ser siempre usado donde se requiera un objeto sqlite3_value no protegido, de modo que cualquier tipo de objeto sqlite3_value puede ser usado con esta función.

Si estas funciones se invocan desde un hilo diferente del que contiene la función definida por la aplicación que recibe el puntero a sqlite3_context, el resultado es indefinido.