Small. Fast. Reliable.
Choose any three.

SQLite C接口

设置SQL函数的结果

void sqlite3_result_blob(sqlite3_context *,const void *,int,void(*)(void *));
void sqlite3_result_blob64(sqlite3_context *,const void *,
                           sqlite3_uint64,void(*)(void *));
void sqlite3_result_double(sqlite3_context *,double);
无效sqlite3_result_error(sqlite3_context *,const char *,int);
void sqlite3_result_error16(sqlite3_context *,const void *,int);
无效sqlite3_result_error_toobig(sqlite3_context *);
无效sqlite3_result_error_nomem(sqlite3_context *);
无效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 *));
无效sqlite3_result_text64(sqlite3_context *,const char *,sqlite3_uint64,
                           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_pointer(sqlite3_context *,void *,const char *,void(*)(void *));
void sqlite3_result_zeroblob(sqlite3_context *,int n);
int sqlite3_result_zeroblob64(sqlite3_context *,sqlite3_uint64 n);

这些例程由实现SQL函数和聚合的xFunc或xFinal回调使用。有关 其他信息,请参见 sqlite3_create_function()sqlite3_create_function16()

这些函数的工作方式与参数绑定系列的功能非常相似,该函数用于将值绑定到准备好的语句中的主机参数。有关其他信息,请参考SQL参数文档。

sqlite3_result_blob()接口将应用程序定义的函数的结果设置为BLOB,其内容由第二个参数指向,并且为N个字节长,其中N为第三个参数。

sqlite3_result_zeroblob(C,N)和sqlite3_result_zeroblob64(C,N)接口将应用程序定义函数的结果设置为BLOB,其中包含所有零字节和N个字节。

sqlite3_result_double()接口将应用程序定义的函数的结果设置为其第二个参数指定的浮点值。

sqlite3_result_error()和sqlite3_result_error16()函数导致已实现的SQL函数引发异常。SQLite使用sqlite3_result_error()或sqlite3_result_error16()的第二个参数指向的字符串作为错误消息的文本。SQLite将来自sqlite3_result_error()的错误消息字符串解释为UTF-8。SQLite使用与sqlite3_bind_text16()相同的字节顺序确定规则,将sqlite3_result_error16()中的字符串解释为UTF-16。。如果sqlite3_result_error()或sqlite3_result_error16()的第三个参数为负,则SQLite会将直到第一个零字符的所有文本作为错误消息。如果sqlite3_result_error()或sqlite3_result_error16()的第三个参数为非负数,则SQLite从第二个参数中获取那么多字节(不是字符)作为错误消息。sqlite3_result_error()和sqlite3_result_error16()例程在返回错误消息之前对其进行私有复制。因此,调用函数可以在返回文本后取消分配或修改文本,而不会造成损害。sqlite3_result_error_code()函数更改SQLite由于函数错误而返回的错误代码。默认情况下,错误代码为SQLITE_ERROR。

sqlite3_result_error_toobig()接口使SQLite抛出错误,指示字符串或BLOB太长而无法表示。

sqlite3_result_error_nomem()接口使SQLite抛出错误,指示内存分配失败。

sqlite3_result_int()接口将应用程序定义的函数的返回值设置为第二个参数中给出的32位带符号整数值。sqlite3_result_int64()接口将应用程序定义的函数的返回值设置为第二个参数中给出的64位有符号整数值。

sqlite3_result_null()接口将应用程序定义的函数的返回值设置为NULL。

sqlite3_result_text(),sqlite3_result_text16(),sqlite3_result_text16le()和sqlite3_result_text16be()接口将应用程序定义函数的返回值设置为文本字符串,该文本字符串表示为UTF-8,UTF-16本机字节顺序,UTF-分别为16个小字节序或UTF-16大字节序。sqlite3_result_text64()接口将应用程序定义的函数的返回值设置为文本字符串,该字符串由第五个(也是最后一个)参数指定的编码,该参数必须是SQLITE_UTF8SQLITE_UTF16SQLITE_UTF16BESQLITE_UTF16LE之一。SQLite从sqlite3_result_text *接口的第二个参数获取应用程序的文本结果。如果sqlite3_result_text *接口的第3个参数为负,则SQLite从第2个参数到第一个零字符获取结果文本。如果sqlite3_result_text *接口的第3个参数为非负数,则将第2个参数所指向的文本字节(不是字符)作为应用程序定义的函数结果。如果第3个参数为非负数,则它必须是NUL终止处的字符串在NUL终止符出现的字符串中的字节偏移量。如果字符串中出现的任何NUL字符的字节偏移小于第3个参数的值,那么结果字符串将包含嵌入式NUL,并且对带有嵌入式NUL的字符串进行运算的表达式的结果是不确定的。如果sqlite3_result_text *接口或sqlite3_result_blob的第4个参数是非NULL指针,则SQLite在使用完该结果后将调用该函数作为文本或BLOB结果的析构函数。如果sqlite3_result_text *接口或sqlite3_result_blob的第四个参数是特殊常量SQLITE_STATIC,则SQLite会假定文本或BLOB结果位于常量空间中,并且不复制参数的内容,也不会在其内容上调用析构函数完成使用该结果。sqlite3_malloc()返回之前。

对于sqlite3_result_text16(),sqlite3_result_text16le()和sqlite3_result_text16be()例程,对于sqlite3_result_text64()例程,当编码不是UTF8时,如果输入的UTF16以字节顺序标记(BOM,U + FEFF)开头,则BOM是从字符串中删除后,其余字符串将根据BOM表指定的字节顺序进行解释。BOM文本开头指定的字节顺序将覆盖接口过程指定的字节顺序。因此,例如,如果调用sqlite3_result_text16le()以字节0xfe,0xff(大端字节序标记)开头的文本,则将跳过输入的前两个字节,而将其余输入解释为UTF16BE文本。

对于向sqlite3_result_text16(),sqlite3_result_text16be(),sqlite3_result_text16le()和sqlite3_result_text64()例程输入的UTF16文本,如果文本包含无效的UTF16字符,则无效字符可能会转换为Unicode替换字符U + FFFD。

sqlite3_result_value()接口将应用程序定义的函数的结果设置为第二个参数指定的不受保护的sqlite3_value对象的副本 。sqlite3_result_value()接口复制sqlite3_value, 以便在sqlite3_result_value()返回无害后,参数中指定的sqlite3_value可以更改或释放。甲保护sqlite3_value对象总是可以用在一个 无保护sqlite3_value需要对象,因此任一种sqlite3_value对象可以与该接口时使用。

sqlite3_result_pointer(C,P,T,D)接口将结果设置为SQL NULL值,就像sqlite3_result_null(C)一样,不同之处在于它还将主机语言指针P或类型T与该NULL值相关联,从而使指针可以使用sqlite3_value_pointer()应用程序定义的SQL函数中检索 。如果D参数不为NULL,则它是指向P参数的析构函数的指针。当SQLite用P结尾时,SQLite调用D作为唯一参数。D参数应该是静态字符串,最好是字符串文字。sqlite3_result_pointer()例程是为SQLite 3.20.0添加的指针传递接口的一部分。

如果这些例程是在不同于包含接收sqlite3_context指针的应用程序定义函数的线程中的另一线程中调用的,则结果是不确定的。

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