Next: mod-http, Previous: libcfg, Up: C API

### 5.8 libcli

#### 5.8.1 Overview

View lcov test coverage results on http://www.gnu.org/software/liquidwar6/coverage/src/lib/cli/index.html.

#### 5.8.2 API

— Function: int lw6cli_init (lw6cli_backend_t * backend)

> backend: backend to use

> Initializes a client backend. Must be performed before any other call.

> Return value: 1 on success, 0 on failure

— Function: void lw6cli_quit (lw6cli_backend_t * backend)

> backend: unitialize a cli backend

> Closes a cli, but does not free all ressources.

— Function: int lw6cli_process_oob (lw6cli_backend_t * backend, lw6nod_info_t * node_info, lw6cli_oob_data_t * oob_data)

> backend: backend to use

> node_info: information on the current node

> oob_data: data of the out-of-band request

> Processes the required out-of-band tasks, this typically, for a client, includes broadcasting. Depending on parameters passed in oob_data, might actually do a broadcast or simply call a given host and see what's the answer. A typicall exchange is PING then INFO and finally LIST. It's the responsability of the client to take the OOB initiative and contact the server.

> Return value: 1 on success, 0 on failure.

— Function: lw6cnx_connection_t * lw6cli_open (lw6cli_backend_t * backend, char * local_url, char * remote_url, char * remote_ip, int remote_port, char * password, u_int64_t local_id, u_int64_t remote_id, int dns_ok, int network_reliability, lw6cnx_recv_callback_t recv_callback_func, void * recv_callback_data)

> backend: backend to use

> local_url: our local public url

> remote_url: the remote url we want to connect to

> remote_ip: remote IP address

> remote_port: remote IP port

> password: password to use (if needed)

> local_id: our local id

> remote_id: the remote id

> dns_ok: wether the remote announced URL matches DNS information

> network_reliability: network reliability (the highest, the better)

> recv_callback_func: callback func to be called when data is received

> recv_callback_data: pointer on additionnal data to pass to callback func

> Opens a connection with a remote host. Be carefull with the implementation of `recv_callback_func`, it should be at least reentrant, and when it accesses shared data, use locks.

> Return value: new object.

— Function: void lw6cli_close (lw6cli_backend_t * backend, lw6cnx_connection_t * connection)

> backend: backend to use

> connection: connection to use

> Closes a connection, this will free the connection object.

> Return value: none.

— Function: int lw6cli_send (lw6cli_backend_t * backend, lw6cnx_connection_t * connection, u_int32_t physical_ticket_sig, u_int32_t logical_ticket_sig, u_int64_t logical_from_id, u_int64_t logical_to_id, char * message)

> backend: backend to use

> connection: connection to use

> physical_ticket_sig: signature of physical sender

> logical_ticket_sig: signature of logical sender

> logical_from_id: id of logical sender

> logical_to_id: id of logicial target

> message: text of message to send

> Sends a message to a peer over a given connection.

> Return value: 1 on success, 0 on failure.

— Function: void lw6cli_poll (lw6cli_backend_t * backend, lw6cnx_connection_t * connection)

> backend: backend to use

> connection: connection to use

> Performs required duty on connection, depending on the backend, this can include sending messages and/or receiving them. Must be called on a regular basis.

> Return value: none.

— Function: char * lw6cli_repr (lw6cli_backend_t * backend, lw6cnx_connection_t * connection)

> backend: backend to use

> connection: connection to represent

> Gives a human readable representation of the connection.

> Return value: dynamically allocated string.

— Function: lw6cli_oob_t * lw6cli_oob_new (char * public_url, lw6cli_verify_callback_func_t verify_callback_func, void * verify_callback_data)

> public_url: the address of the distant server to test

> verify_callback_func: a function which will be called when a node has been verified

> verify_callback_data: additionnal data passed to the callback func

> Create a new OOB structure, copying required objects. We need to make copies for this is for usage in a separate thread. The thread member is not set here since the right way to do things is first to set up data then to fire the thread.

> Return value: new object

— Function: void lw6cli_oob_free (lw6cli_oob_t * oob)

> oob: the object to free

> Frees an OOB structure.

> Return value: none

— Function: char * lw6cli_default_backends ()

> Returns the list of the default cli backends.

> Return value: comma separated string, must not be freed.

— Function: lw6sys_assoc_t * lw6cli_get_backends (int argc, char * [] argv)

> argc: argc, as passed to `main`

> argv: argv, as passed to `main`

> List available cli backends. The hash contains pairs with id and name for each backend. The id is the technical key you can use to load the backend, the name is something more readable you can display in an interface. The backend objects themselves are not instanciated by this (in fact, they are, but released on the fly) you need to load and initialize them afterwards.

> Return value: hash containing id/name pairs.

— Function: lw6cli_backend_t * lw6cli_create_backend (int argc, char * [] argv, char * name)

> argc: argc, as passed to `main`

> argv: argv, as passed to `main`

> name: string containing cli key, typically got from `lw6cli_get_backends`

> Creates a cli backend, this is just about loading the dynamic library if needed, and/or check cli engine is available, and connect to it. It does not perform initialization.

> Return value: cli backend.

— Function: void lw6cli_destroy_backend (lw6cli_backend_t * backend)

> backend: backend to destroy

> Destroys a cli backend.

> Return value: none.

— Function: int lw6cli_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `cli` module test suite.

> Return value: 1 if test is successfull, 0 on error.