Symisc Systems

Libcox C/C++ API Reference - Register a Foreign Command


Star Follow @symisc

Syntax

int libcox_register_command(

    libcox *pHandle,

    const char *zName,

    int (*xCmd)(libcox_context *pCtx,int argc,libcox_value **argv),

    void *pUserData

);


Register a foreign command.

Description

This interface known as foreign command creation routine is used to add new Libcox commands or to redefine the behavior of existing commands. After successful call to this routine, the installed command is available immediately and can be invoked from libcox_exec().

The first parameter is the Libcox handle to which the command is to be added. If an application uses more than one Libcox instance then application-defined commands must be added to each handle separately.

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

The third and most important parameter is a pointer to C-language function that implement the foreign command. This function must accept three parameters. The first parameter is a pointer to a libcox_context structure. This is the context in which the command executes.

The application-defined foreign function implementation will pass this pointer through into calls to dozens of interfaces, these includes: libcox_context_throw_error(), libcox_context_new_scalar(), libcox_context_user_data() and many more. The computation result (i.e: the return value) of the foreign command can be set via one of these interfaces:

libcox_result_int()
libcox_result_int64()
libcox_result_bool()
libcox_result_double()
libcox_result_null()
libcox_result_string()
libcox_result_value()
libcox_result_string_format()


If no call is made to one of these interfaces, then a NULL return value is assumed. The return value could be extracted later after successful return from libcox_exec().

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

libcox_context_throw_error(pCtx,LIBCOX_CTX_WARNING,"Unexpected number of arguments");

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

libcox_value_to_int()
libcox_value_to_bool()
libcox_value_to_int64()
libcox_value_to_double()
libcox_value_to_string()

The xCmd() implementation must return LIBCOX_OK on success. But if the callbacks wishes to abort processing, it must return LIBCOX_ABORT instead.

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

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


Parameters

pValue

A pointer to a valid Libcox handle.

zName

A pointer to a null terminated string holding the name of the foreign command to be deleted.

xCmd

A pointer to a C function performing the desired computation.

pUserData

Arbitrary user pointer which could be extracted later in the implementation of the foreign command via libcox_context_user_data().


Return value

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


See also

libcox_delete_command.