Symisc Systems

Libcox C/C++ API Reference - Libcox Handle


Star Follow @symisc

Syntax

int libcox_config(libcox *pHandle,int nOp,...);


Configure a working Libcox handle.

Description

This routine is used to configure a libcox handle obtained by a prior successful call to libcox_init().
The second argument to libcox_config() is an integer configuration option that determines what property of the handle is to be configured. Subsequent arguments vary depending on the configuration option in the second argument. The default configuration is recommended for most applications and so this routine is usually not necessary. Here is a list of allowed configuration options:

Command

Expected Arguments

Description

LIBCOX_CONFIG_OUTPUT_CONSUMER

Two Arguments:
int (*xConsumer)(libcox_value *pOut,void *pUserData),
void *pUserData;

This option is used to install a result output consumer callback. That is, an user defined function responsible of consuming the return value of the executed commands (i.e. date, uname, pwd, cd, etc.). This option accepts two arguments:
The first argument is a pointer to the user defined function responsible of consuming the return value of the executed command. This callback must accept two arguments. The first argument is a pointer to the return value of the executed command and the last argument is an arbitrary user pointer forwarded verbatim by the engine to the callback as its last argument.
Note: The engine will invoke this callback each time it have something to output especially if multiple commands are executed using a single call to libcox_exec() (semi-colon separated commands) . Refer to the implementation of the libcox Shell for an example of an output consumer callback.

LIBCOX_CONFIG_ERR_LOG

Two Arguments:
const char **pzPtr, int *pLen;

The error log is stored in an internal buffer. When something goes wrong while executing a command, a human-readable error message is generated to help clients diagnostic the problem. This option can be used to point to that buffer. The first argument is a pointer address to a const char *. The second argument is an optional pointer to an integer. When set (i.e. not null), the integer value will hold the length of the error log in bytes.


Parameters

pHandle

Libcox Handle obtained a prior successful call to libcox_init().

nOp

An integer configuration option that determines what property of the libcox handle is to be configured.


Return value

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


See also

libcox_exec, libcox_release, libcox_exec_result_destroy, libcox_init.