UnQLite C/C++ API Reference - Foreign Function Mechanism.

Syntax

int unqlite_create_function(

unqlite_vm *pVm,

const char *zName,

int (*xFunc)(unqlite_context *pCtx,int argc,unqlite_value **argv),

void *pUserData

);

Install a foreign function and invoke it from the target Jx9 code.

Description

This interface known as foreign function creation routine is used to add Jx9 (via UnQLite API) functions or to redefine the behavior of existing Jx9 functions. After successful call to this routine, the installed function is available immediately and can be called from the target Jx9 code.

The first parameter is the virtual machine to which the Jx9 function is to be added. If an application uses more than one virtual machine then application-defined functions must be added to each virtual machine separately.

The second parameter is a pointer to a null terminated string holding the name of the Jx9 function to be created or redefined. A valid function name starts with a letter or underscore, followed by any number of letters, numbers, or underscores. Also note that functions names under Jx9 are case sensitive.

The third and most important parameter is a pointer to C-language function that implement the Jx9 function. This function must accept three parameters. The first parameter is a pointer to a unqlite_context structure. This is the context in which the foreign function executes. In other words, this parameter is the intermediate between the foreign function and the underlying virtual machine.

The application-defined foreign function implementation will pass this pointer through into calls to dozens of interfaces, these includes:

unqlite_context_output(), unqlite_context_throw_error(), unqlite_context_new_scalar(), unqlite_context_user_data(), unqlite_context_alloc_chunk() and many more.

The computation result (i.e: the return value) of the foreign function can be set via one of these interfaces:

unqlite_result_int()

unqlite_result_int64()

unqlite_result_bool()

unqlite_result_double()

unqlite_result_null()

unqlite_result_string()

unqlite_result_value()

unqlite_result_resource()

unqlite_result_string_format()

If no call is made to one of these interfaces, then a NULL return value is assumed.

The second parameter xFunc() takes is the total number of arguments passed to the foreign function. If the total number of arguments is not the expected one, the foreign functions can throw an error via unqlite_context_throw_error() as follow:

unqlite_context_throw_error(pCtx,UNQLITE_CTX_WARNING,"Unexpected number of arguments");

The last parameter xFunc() takes is an array of pointers to unqlite_value which represents function arguments. The implementation of the foreign functions can extract their contents via one of these interfaces:

unqlite_value_to_int()

unqlite_value_to_bool()

unqlite_value_to_int64()

unqlite_value_to_double()

unqlite_value_to_string()

unqlite_value_to_resource()

unqlite_value_compare()

The xFunc() implementation must return UNQLITE_OK on success. But if the callbacks wishes to abort processing (i.e: to stop program execution) and thus to emulate the exit() or die() Jx9 constructs, it must return UNQLITE_ABORT instead.

The fourth and last parameter is an arbitrary pointer. The implementation of the function can gain access to this pointer using unqlite_context_user_data(). Also note that foreign functions can store an arbitrary number of auxiliary private data in a stack-able manner via unqlite_context_push_aux_data().

Built-in functions may be overloaded by new application-defined functions. Note that Jx9 is shipped with more than 312 built-in functions installed using exactly this interface.

This function must be called before program execution via unqlite_vm_exec().

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

Parameters

pVm	A pointer to a UnQLite Virtual Machine.
zName	A pointer to a null terminated string holding the name of the foreign function.
xFunc	A pointer to a C function performing the desired computation.
pUserDara	Arbitrary user pointer which can be extracted later in the implementation of the foreign function via a call to unqlite_context_user_data().

Return value

UNQLITE_OK is returned on success. Any other return value typically (UNQLITE_NOMEM) indicates failure

Example

Compile this C file for a smart introduction to this interface.