Setting The Result Of An SQL Function

这些例程由实现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)接口将应用程序定义函数的结果设置为包含全零字节和N字节大小的BLOB。

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_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()或sqlite3_result_error16()将错误代码重置为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_UTF8，SQLITE_UTF16，SQLITE_UTF16BE或SQLITE_UTF16LE之一。SQLite从sqlite3_result_text *接口的第二个参数中获取来自应用程序的文本结果。如果sqlite3_result_text *接口的第三个参数是负数，那么SQLite将通过第一个零字符从第二个参数中获取结果文本。如果sqlite3_result_text *接口的第三个参数是非负数，则第二个参数指向的文本的字节数（非字符）将被视为应用程序定义的函数结果。如果第三个参数是非负数，那么它必须是NUL终止符出现的字符串的字节偏移量，如果NUL终止的字符串。如果在小于第三个参数的字节偏移量的字符串中出现任何NUL字符，则结果字符串将包含嵌入式NUL，并且对具有嵌入式NUL的字符串操作的表达式的结果是未定义的。如果sqlite3_result_text * interfaces或sqlite3_result_blob的第四个参数是非空指针，则SQLite在完成使用该结果时将该函数作为文本或BLOB结果的析构函数调用。如果sqlite3_result_text * interfaces或sqlite3_result_blob的第四个参数是特殊常量SQLITE_STATIC，则SQLite会假定文本或BLOB结果位于恒定空间中，并且不会复制参数的内容，也不会在内容具有相应的内容时调用析构函数完成使用该结果。如果sqlite3_result_text * interfaces或sqlite3_result_blob的第4个参数是特殊常量SQLITE_TRANSIENT，则SQLite在返回之前将结果的副本作为从sqlite3_malloc()获取的空间的副本。

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作为其唯一参数.T参数应该是一个静态字符串，最好是一个字符串文字。sqlite3_result_pointer()例程是为SQLite 3.20.0添加的指针传递接口的一部分。

如果这些例程是在不同于包含接收sqlite3_context指针的应用程序定义函数的线程中调用的，那么结果是未定义的。