Next: mod-http, Previous: libcfg, Up: C API [Contents][Index]

### 5.8 libcli

#### 5.8.1 Overview

View lcov test coverage results on http://www.ufoot.org/liquidwar/v6/doc/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, const char * local_url, const char * remote_url, const char * remote_ip, int remote_port, const 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, int64_t now, u_int32_t physical_ticket_sig, u_int32_t logical_ticket_sig, u_int64_t logical_from_id, u_int64_t logical_to_id, const char * message)

  backend: backend to use

  connection: connection to use

  now: current timestamp

  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: int lw6cli_can_send (lw6cli_backend_t * backend, lw6cnx_connection_t * connection)

  backend: backend to use

  connection: connection to use

  Tells wether a client connection can technically send messages. This does not garantee send will succeed, but if it’s not OK at this stage, it’s not even worth trying.

  Return value: 1 if it can be used to send messages, 0 if not ready.

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 (const 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 (const 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, const 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, const char * [] argv, const 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_register (int mode)

  mode: test mode (bitmask)

  Registers all tests for the libcli module.

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

Function: int lw6cli_test_run (int mode)

  mode: test mode (bitmask)

  Runs the `cli` module test suite, testing most (if not all...) functions.

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

Struct: lw6cli_backend_s

  The cli backend is the first argument passed to any cli function, it contains reference to all the functions which can be used as well as a pointer on associated data. In OO, this would just be an object, with members and methods, using polymorphism through opaque pointers.

Member of lw6cli_backend_s: dl_handle

  Type: `lw6dyn_dl_handle_t *`

  Definition: `lw6dyn_dl_handle_t* lw6cli_backend_s::dl_handle`

  Handle on dynamic library (if it makes sense).

Member of lw6cli_backend_s: cli_context

  Type: `void *`

  Definition: `void* lw6cli_backend_s::cli_context`

  Cli specific data, what is behind this pointer really depends on the cli engine.

Member of lw6cli_backend_s: argc

  Type: `int`

  Definition: `int lw6cli_backend_s::argc`

  The argc value passed to main.

Member of lw6cli_backend_s: argv

  Type: `const char **`

  Definition: `const char** lw6cli_backend_s::argv`

  The argv value passed to main.

Member of lw6cli_backend_s: id

  Type: `u_int32_t`

  Definition: `u_int32_t lw6cli_backend_s::id`

  The id of the object, this is non-zero and unique within one run session, incremented at each object creation.

Member of lw6cli_backend_s: name

  Type: `char *`

  Definition: `char* lw6cli_backend_s::name`

  Module name.

Member of lw6cli_backend_s: properties

  Type: `lw6cnx_properties_t`

  Definition: `lw6cnx_properties_t lw6cli_backend_s::properties`

  General backend properties.

Member of lw6cli_backend_s: init

  Type: `void *(*`

  Definition: `void*(* lw6cli_backend_s::init)(int argc, const char *argv[], lw6cnx_properties_t *properties)`

  Pointer on lw6cli_init callback code.

Member of lw6cli_backend_s: quit

  Type: `void(*`

  Definition: `void(* lw6cli_backend_s::quit)(void *cli_context)`

  Pointer on lw6cli_quit callback code.

Member of lw6cli_backend_s: process_oob

  Type: `int(*`

  Definition: `int(* lw6cli_backend_s::process_oob)(void *cli_context, lw6nod_info_t *node_info, lw6cli_oob_data_t *oob_data)`

  Pointer on lw6cli_process_oob callback code.

Member of lw6cli_backend_s: open

  Type: `lw6cnx_connection_t *(*`

  Definition: `lw6cnx_connection_t*(* lw6cli_backend_s::open)(void *cli_context, const char *local_url, const char *remote_url, const char *remote_ip, int remote_port, const 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)`

  Pointer on lw6cli_open callback code.

Member of lw6cli_backend_s: close

  Type: `void(*`

  Definition: `void(* lw6cli_backend_s::close)(void *cli_context, lw6cnx_connection_t *connection)`

  Pointer on lw6cli_close callback code.

Member of lw6cli_backend_s: send

  Type: `int(*`

  Definition: `int(* lw6cli_backend_s::send)(void *cli_context, lw6cnx_connection_t *connection, int64_t now, u_int32_t physical_ticket_sig, u_int32_t logical_ticket_sig, u_int64_t logical_from_id, u_int64_t logical_to_id, const char *message)`

  Pointer on lw6cli_send callback code.

Member of lw6cli_backend_s: can_send

  Type: `int(*`

  Definition: `int(* lw6cli_backend_s::can_send)(void *cli_context, lw6cnx_connection_t *connection)`

  Pointer on lw6cli_can_send callback code.

Member of lw6cli_backend_s: poll

  Type: `void(*`

  Definition: `void(* lw6cli_backend_s::poll)(void *cli_context, lw6cnx_connection_t *connection)`

  Pointer on lw6cli_poll callback code.

Member of lw6cli_backend_s: repr

  Type: `char *(*`

  Definition: `char*(* lw6cli_backend_s::repr)(void *cli_context, lw6cnx_connection_t *connection)`

  Pointer on lw6cli_repr callback code.

Struct: lw6cli_oob_data_s

  Holds the data for the process_oob function, this is merely a utility struct to simplify headers/

Member of lw6cli_oob_data_s: creation_timestamp

  Type: `int64_t`

  Definition: `int64_t lw6cli_oob_data_s::creation_timestamp`

  Creation timestamp of the OOB request, this is used to know wether we have already timed out or not. This is not the node creation timestamp.

Member of lw6cli_oob_data_s: do_not_finish

  Type: `int`

  Definition: `volatile int lw6cli_oob_data_s::do_not_finish`

  Flag used to force finish, for instance when we want to delete the object quickly and do not want to wait until a long polling-based network operation finishes completely.

Member of lw6cli_oob_data_s: public_url

  Type: `char *`

  Definition: `char* lw6cli_oob_data_s::public_url`

  Public URL of the node, we need this at hand to serve it quickly to peers, and be able to perform basic checks.

Member of lw6cli_oob_data_s: verify_callback_func

  Type: `lw6cli_verify_callback_func_t`

  Definition: `lw6cli_verify_callback_func_t lw6cli_oob_data_s::verify_callback_func`

  Pointer on a function which will verify if peer is OK, and act accordinlgy if it’s OK or not. Note that the callback function might be called pretty much anytime in the heavily multithreaded context of LW6 so it must be reentrant and have mutexes if needed. Indeed, it’s very likely to update some shared list of available nodes.

Member of lw6cli_oob_data_s: verify_callback_data

  Type: `void *`

  Definition: `void* lw6cli_oob_data_s::verify_callback_data`

  Data passed to the verify_callback function.

Struct: lw6cli_oob_s

  Structure containing both the thread running an OOB request and its data. It was advantagious to separate thoses two and not make the thread a permanent member of the OOB data struct, since it allows the actual OOB code to be totally unaware of the thread running it, which is, to some extent, safer.

Member of lw6cli_oob_s: thread

  Type: `lw6sys_thread_handler_t *`

  Definition: `lw6sys_thread_handler_t* lw6cli_oob_s::thread`

  Pointer on thread running the OOB request.

Member of lw6cli_oob_s: data

  Type: `lw6cli_oob_data_t`

  Definition: `lw6cli_oob_data_t lw6cli_oob_s::data`

  Data used by the OOB request.

Next: mod-http, Previous: libcfg, Up: C API [Contents][Index]