UnQLite C/C++ API Reference - Setting The Result Of A Foreign Function.

Syntax

int unqlite_result_int(unqlite_context *pCtx,int iValue);

int unqlite_result_int64(unqlite_context *pCtx,unqlite_int64 iValue);

int unqlite_result_bool(unqlite_context *pCtx,int iBool);

int unqlite_result_double(unqlite_context *pCtx,double Value);

int unqlite_result_null(unqlite_context *pCtx);

int unqlite_result_string(unqlite_context *pCtx,const char *zString,int nLen);

int unqlite_result_string_format(unqlite_context *pCtx,const char *zFormat,...);

int unqlite_result_value(unqlite_context *pCtx,unqlite_value *pValue);

int unqlite_result_resource(unqlite_context *pCtx,void *pUserData);

Set the return value of a foreign function.

Description

These routines are used by the xFunc() callback that implement foreign UnQLite functions to return their computation result. See unqlite_create_function() for additional information.

These functions work very much like the unqlite_value_* family of functions used to populate UnQLite values.

The unqlite_result_int() interface sets the result from an application-defined function to be an integer value specified by its 2nd argument.

The unqlite_result_int64() interface sets the result from an application-defined function to be a 64-bit integer value specified by its 2nd argument.

The unqlite_result_double() interface sets the result from an application-defined function to be a floating point value specified by its 2nd argument.

The unqlite_result_bool() interface sets the result from an application-defined function to be a Boolean value (Only zero is assumed FALSE) specified by its 2nd argument.

The unqlite_result_null() interface sets the return value of the application-defined function to be NULL (default return value).

The unqlite_result_resource() interface sets the result from an application-defined function to be a resource value specified by its 2nd argument which is an arbitrary user pointer that can be extracted later using unqlite_value_to_resource().

The unqlite_result_value() interface sets the result from an application-defined function to be a copy of the unqlite_value obtained by a prior successful call to unqlite_context_new_scalar() or unqlite_context_new_array(). This is how JSON arrays and objects are returned (Download this C file for a working example).

The unqlite_result_string() interface sets the result from an application-defined function to be a string value whose content is specified by the 2nd argument.

Note that unqlite_result_string() accepts a third argument which is the length of the string to append. If the nLen argument is less than zero, then zString is read up to the first zero terminator. If nLen is non-negative, then it is the maximum number of bytes read from zString.

unqlite_result_string_format() is a work-alike of the "printf()" family of functions from the standard C library which is used to append a formatted string.

Note that the printf() implementation in the unqlite core is based on the one found in the SQLite3 source tree.

The unqlite_result_string() and unqlite_result_string_format() interfaces write their result to an internal buffer which grow automatically by successive calls to one of them (An append operation). That is, previously written data is not erased by the new call.

Example

unqlite_result_string(pCtx,"Welcome, current time is: ",-1);

unqlite_result_string_format(pCtx,"%02d:%02d:%02d",14,12,59);

The final return value of the foreign functions would look like this:

“Welcome, current time is: 14:12:59”

If these routines are called from within the different thread than the one containing the application-defined function that received the unqlite_context pointer, the results are undefined.

You can refer to the following guide for an introductory course to this interface and the foreign function mechanism in general.

Parameters

pCtx

Foreign function call context.

Return value

UNQLITE_OK is returned on success. Any other return value indicates failure.

Example

Compile this C file for a smart introduction to these interfaces.