const void *sqlite3_column_blob(sqlite3_stmt*,int iCol);double sqlite3_column_double(sqlite3_stmt*,int iCol);int sqlite3_column_int(sqlite3_stmt*,int iCol);
sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*,int iCol);
const unsignedchar*sqlite3_column_text(sqlite3_stmt*,int iCol);
const void *sqlite3_column_text16(sqlite3_stmt*,int iCol);
sqlite3_value *sqlite3_column_value(sqlite3_stmt*,int iCol);int sqlite3_column_bytes(sqlite3_stmt*,int iCol);int sqlite3_column_bytes16(sqlite3_stmt*,int iCol);int sqlite3_column_type(sqlite3_stmt*,int iCol);

Resumen:

 
sqlite3_column_blob
→
BLOB result 


sqlite3_column_double
→
REAL result 


sqlite3_column_int
→
32-bitINTEGER result 


sqlite3_column_int64
→
64-bitINTEGER result 


sqlite3_column_text
→
UTF-8TEXT result 


sqlite3_column_text16
→
UTF-16TEXT result 


sqlite3_column_value
→
The result as an unprotected sqlite3_value object. 


 
 
 


sqlite3_column_bytes
→
Size of a BLOBor a UTF-8TEXT result in bytes 



sqlite3_column_bytes16  
→ 
Size of UTF-16TEXTin bytes 


sqlite3_column_type
→
Default datatype of the result

Detalles:

Estas rutinas devuelven información sobre una sola columna de la fila de resultados actual de una consulta. En todos los casos, el primer argumento es un puntero a la declaración preparada que se está evaluando (el sqlite3_stmt * que se devolvió de sqlite3_prepare_v2 () o una de sus variantes) y el segundo argumento es el índice de la columna para la que se debe devolver la información. . La columna más a la izquierda del conjunto de resultados tiene el índice 0. El número de columnas en el resultado se puede determinar usando sqlite3_column_count ().

Si la instrucción SQL no apunta actualmente a una fila válida, o si el índice de la columna está fuera de rango, el resultado no está definido. Estas rutinas solo se pueden llamar cuando la llamada más reciente a sqlite3_step () ha devuelto SQLITE_ROW y ni sqlite3_reset () ni sqlite3_finalize () se han llamado posteriormente. Si alguna de estas rutinas se llama después de sqlite3_reset () o sqlite3_finalize () o después de que sqlite3_step () haya devuelto algo diferente a SQLITE_ROW, los resultados no están definidos. Si sqlite3_step () o sqlite3_reset () o sqlite3_finalize () se llaman desde un hilo diferente mientras cualquiera de estas rutinas está pendiente, entonces los resultados no están definidos.

Las primeras seis interfaces (_blob, _double, _int, _int64, _text y _text16) devuelven cada una el valor de una columna de resultados en un formato de datos específico. Si la columna de resultado no está inicialmente en el formato solicitado (por ejemplo, si la consulta devuelve un número entero pero se usa la interfaz sqlite3_column_text () para extraer el valor), entonces se realiza una conversión automática de tipos.

La rutina sqlite3_column_type () devuelve el código de tipo de datos para el tipo de datos inicial de la columna de resultados. El valor devuelto es uno de SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB o SQLITE_NULL. El valor de retorno de sqlite3_column_type () se puede usar para decidir cuál de las primeras seis interfaces debe usarse para extraer el valor de la columna. El valor devuelto por sqlite3_column_type () solo es significativo si no se han producido conversiones automáticas de tipos para el valor en cuestión. Después de una conversión de tipo, el resultado de llamar a sqlite3_column_type () no está definido, aunque es inofensivo. Las versiones futuras de SQLite pueden cambiar el comportamiento de sqlite3_column_type () después de una conversión de tipo.

Si el resultado es un BLOB o un TEXTO string, entonces las interfaces sqlite3_column_bytes () o sqlite3_column_bytes16 () se pueden usar para determinar el tamaño de ese BLOB o string.

Si el resultado es un BLOB o UTF-8 string entonces la rutina sqlite3_column_bytes () devuelve el número de bytes en ese BLOB o string. Si el resultado es un UTF-16 string, luego sqlite3_column_bytes () convierte el string a UTF-8 y luego devuelve el número de bytes. Si el resultado es un valor numérico, entonces sqlite3_column_bytes () usa sqlite3_snprintf () para convertir ese valor en un UTF-8 string y devuelve el número de bytes en ese string. Si el resultado es NULL, entonces sqlite3_column_bytes () devuelve cero.

Si el resultado es un BLOB o UTF-16 string entonces la rutina sqlite3_column_bytes16 () devuelve el número de bytes en ese BLOB o string. Si el resultado es un UTF-8 string, luego sqlite3_column_bytes16 () convierte el string a UTF-16 y luego devuelve el número de bytes. Si el resultado es un valor numérico, entonces sqlite3_column_bytes16 () usa sqlite3_snprintf () para convertir ese valor en un UTF-16 string y devuelve el número de bytes en ese string. Si el resultado es NULL, entonces sqlite3_column_bytes16 () devuelve cero.

Los valores devueltos por sqlite3_column_bytes () y sqlite3_column_bytes16 () no incluyen los terminadores cero al final del string. Para mayor claridad: los valores devueltos por sqlite3_column_bytes () y sqlite3_column_bytes16 () son el número de bytes en el string, no el número de caracteres.

Las cadenas devueltas por sqlite3_column_text () y sqlite3_column_text16 (), incluso las cadenas vacías, siempre terminan en cero. El valor de retorno de sqlite3_column_blob () para un BLOB de longitud cero es un puntero NULL.

Advertencia: El objeto devuelto por sqlite3_column_value () es un objeto sqlite3_value no protegido. En un entorno multiproceso, un objeto sqlite3_value no protegido solo se puede utilizar de forma segura con sqlite3_bind_value () y sqlite3_result_value (). Si el objeto sqlite3_value no protegido devuelto por sqlite3_column_value () se usa de cualquier otra forma, incluidas las llamadas a rutinas como sqlite3_value_int (), sqlite3_value_text () o sqlite3_value_bytes (), el comportamiento no es seguro para subprocesos. Por lo tanto, la interfaz sqlite3_column_value () normalmente solo es útil dentro de la implementación de funciones SQL definidas por la aplicación o tablas virtuales, no dentro del código de la aplicación de nivel superior.

Estas rutinas pueden intentar convertir el tipo de datos del resultado. Por ejemplo, si la representación interna es FLOAT y se solicita un resultado de texto, sqlite3_snprintf () se usa internamente para realizar la conversión automáticamente. La siguiente tabla detalla las conversiones que se aplican:

Interno
Escribe 		Solicitado
Escribe 		Conversión

NULO ENTERO El resultado es 0
NULO FLOTADOR El resultado es 0.0
NULO TEXTO El resultado es un puntero NULL
NULO GOTA El resultado es un puntero NULL
ENTERO FLOTADOR Convertir de entero a flotante
ENTERO TEXTO Representación ASCII del entero
ENTERO GOTA Igual que INTEGER-> TEXT
FLOTADOR ENTERO CAST a INTEGER
FLOTADOR TEXTO Representación ASCII del flotador
FLOTADOR GOTA CAST a BLOB
TEXTO ENTERO CAST a INTEGER
TEXTO FLOTADOR CAST a REAL
TEXTO GOTA Ningún cambio
GOTA ENTERO CAST a INTEGER
GOTA FLOTADOR CAST a REAL
GOTA TEXTO Agregue un terminador cero si es necesario

Tenga en cuenta que cuando se producen conversiones de tipos, los punteros devueltos por llamadas anteriores a sqlite3_column_blob (), sqlite3_column_text () y / o sqlite3_column_text16 () pueden invalidarse. Es posible que se produzcan conversiones de tipos e invalidaciones de punteros en los siguientes casos:

  • El contenido inicial es un BLOB y se llama a sqlite3_column_text () o sqlite3_column_text16 (). Es posible que deba agregarse un terminador cero al string.
  • El contenido inicial es texto UTF-8 y se llama a sqlite3_column_bytes16 () o sqlite3_column_text16 (). El contenido debe convertirse a UTF-16.
  • El contenido inicial es texto UTF-16 y se llama a sqlite3_column_bytes () o sqlite3_column_text (). El contenido debe convertirse a UTF-8.

Las conversiones entre UTF-16be y UTF-16le siempre se realizan en el lugar y no invalidan un puntero anterior, aunque, por supuesto, el contenido del búfer al que el puntero anterior hace referencia habrá sido modificado. Otros tipos de conversión se realizan en el lugar cuando es posible, pero a veces no son posibles y en esos casos se invalidan los punteros anteriores.

La política más segura es invocar estas rutinas de una de las siguientes formas:

  • sqlite3_column_text () seguido de sqlite3_column_bytes ()
  • sqlite3_column_blob () seguido de sqlite3_column_bytes ()
  • sqlite3_column_text16 () seguido de sqlite3_column_bytes16 ()

En otras palabras, primero debe llamar a sqlite3_column_text (), sqlite3_column_blob () o sqlite3_column_text16 () para forzar el resultado en el formato deseado, luego invocar sqlite3_column_bytes () o sqlite3_column_bytes16 () para encontrar el tamaño del resultado. No mezcle llamadas a sqlite3_column_text () o sqlite3_column_blob () con llamadas a sqlite3_column_bytes16 (), y no mezcle llamadas a sqlite3_column_text16 () con llamadas a sqlite3_column_bytes ().

Los punteros devueltos son válidos hasta que se produzca una conversión de tipo como se describe anteriormente, o hasta que se llame a sqlite3_step () o sqlite3_reset () o sqlite3_finalize (). El espacio de memoria utilizado para contener cadenas y BLOB se libera automáticamente. No pase los punteros devueltos por sqlite3_column_blob (), sqlite3_column_text (), etc. a sqlite3_free ().

Siempre que los parámetros de entrada sean correctos, estas rutinas solo fallarán si se produce un error de memoria insuficiente durante una conversión de formato. Solo el siguiente subconjunto de interfaces está sujeto a errores de memoria insuficiente:

  • sqlite3_column_blob ()
  • sqlite3_column_text ()
  • sqlite3_column_text16 ()
  • sqlite3_column_bytes ()
  • sqlite3_column_bytes16 ()

Si se produce un error de memoria insuficiente, el valor de retorno de estas rutinas es el mismo que si la columna hubiera contenido un valor NULL de SQL. Los retornos SQL NULL válidos se pueden distinguir de los errores de memoria insuficiente invocando sqlite3_errcode () inmediatamente después de que se obtenga el valor de retorno sospechoso y antes de que se llame a cualquier otra interfaz SQLite en la misma conexión de base de datos.

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