Next: libdat, Previous: libcns, Up: C API

### 5.11 libcnx

#### 5.11.1 Overview

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

#### 5.11.2 API

— Function: lw6cnx_connection_t * lw6cnx_connection_new (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)

> local_url: the local public URL

> remote_url: the remote public URL

> remote_ip: the remote IP address

> remote_port: the remote port

> password: the password to use

> local_id: the local ID

> remote_id: the remote ID

> dns_ok: 1 if no DNS mismatch, 0 if IP does not match public URL

> network_reliability: drop 1 out of X packets

> recv_callback_func: a callback to call when data is received

> recv_callback_data: additionnal data to pass to the callback

> Create a connection object. This object in itself does nothing, it's just to share common structures among modules, more precisely, between cli and srv code. It's the responsability off the caller/backend to handle the `backend_specific_data` field which is NULL after this call.

> Return value: newly allocated object.

— Function: void lw6cnx_connection_free (lw6cnx_connection_t * connection)

> connection: object to free

> Frees a connection object. It's the responsibility of the caller/backend to handle the `backend_specific_data` field.

> Return value: none.

— Function: int lw6cnx_connection_should_send_foo (lw6cnx_connection_t * connection, int64_t now)

> connection: the connection concerned

> now: the current timestamp

> Tells wether a new foo message must be issued.

> Return value: 1 if true, 0 if false.

— Function: void lw6cnx_connection_init_foo_bar_key (lw6cnx_connection_t * connection, int64_t now, int next_foo_delay)

> connection: the connection concerned

> now: the current timestamp

> next_foo_delay: the delay (msec) before next foo message is sent

> Generates a new foo_bar_key, and schedules the next foo message send timestamp.

> Return value: none.

— Function: int lw6cnx_connection_lock_send (lw6cnx_connection_t * connection)

> connection: the connexion to lock

> Acquires a "send" lock on the connexion, the idea is to avoid too threads sending data using the same socket at the same time. Note that each backend must call this when accessing the socket, there's no top-level lock for the sake of performance.

> Return value: 1 on success, 0 if not.

— Function: void lw6cnx_connection_unlock_send (lw6cnx_connection_t * connection)

> connection: the connexion to lock

> Releases a "send" lock on the connexion, the idea is to avoid too threads sending data using the same socket at the same time. Note that each backend must call this when accessing the socket, there's no top-level lock for the sake of performance.

> Return value: none.

— Function: int lw6cnx_connection_reliability_filter (lw6cnx_connection_t * connection)

> connection: the connexion concerned

> Will filter and return true only in "rare" cases when packets must be artificially dropped for testing purpose.

> Return value: 1 if message must be sent/received, 0 if not

— Function: char * lw6cnx_password_checksum (char * seed, char * password)

> seed: a seed to blur the password, can be NULL

> password: the password, can be NULL

> Calculates the checksum of a password, and returns it as a string, ready to be sent on the network. If password is empty or NULL, then an empty (but not NULL unless internal error) string will be returned. All LW6 protocols should send these checksums instead of real passwords, then on server side value can be checked against both real password and its checksum. The seed is here so that eavesdropper can't reuse the checksum to connect on random sessions. Seed can typically be the node 'public_url' value.

> Return value: a dynamically allocated string

— Function: int lw6cnx_password_verify (char * seed, char * password_here, char * password_received)

> seed: a seed to blur the password, can be NULL

> password_here: the local password, can be NULL

> password_received: the password received from network, can be NULL

> Tells wether a password received over the network is valid. The `password_here` argument (the local password) will be checksumed so that `password_received` is checked against both clear and checksumed values, so it can be in any form.

> Return value: 1 if OK, passwords are the same, 0 if not.

— Function: int lw6cnx_test (int mode)

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

> Runs the `cnx` module test suite.

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

— Function: void lw6cnx_ticket_table_zero (lw6cnx_ticket_table_t * ticket_table)

> ticket_table: the ticket table to fill with zero

> Fills the ticket table struct with 0s.

> Return value: none.

— Function: int lw6cnx_ticket_table_init (lw6cnx_ticket_table_t * ticket_table, int hash_size)

> ticket_table: the ticket table to init

> hash_size: the hash size for both recv/send hashs

> Initialize a ticket table, that is, set it up with two empty hashs. Recv hash is filled automatically as it's queried for tickets, send hash must be filled explicitely with info from the network.

> Return value: none.

— Function: void lw6cnx_ticket_table_clear (lw6cnx_ticket_table_t * ticket_table)

> ticket_table: the ticket table to clear

> Clears the object (frees memory).

> Return value: none.

— Function: u_int64_t lw6cnx_ticket_table_get_recv (lw6cnx_ticket_table_t * ticket_table, char * peer_id)

> ticket_table: the ticket table to query

> peer_id: the id of remote node

> Gets the ticket used to communicate with peer, to check its incoming (recv) messages. If ticket does not exist yet, it's automatically generated so tunction will always return a non-zero value.

> Return value: the ticket used to check incoming messages.

— Function: void lw6cnx_ticket_table_ack_recv (lw6cnx_ticket_table_t * ticket_table, char * peer_id)

> ticket_table: the ticket table to query

> peer_id: the id of remote node

> Acknowledges the ticket used to communicate with peer, to check its incoming (recv) messages has been received. This is to avoid sending it again when it has been received, as it's kept "forever" by peer, we never need to send it again.

> Return value: none.

— Function: int lw6cnx_ticket_table_was_recv_exchanged (lw6cnx_ticket_table_t * ticket_table, char * peer_id)

> ticket_table: the ticket table to query

> peer_id: the id of remote node

> Acknowledges the ticket used to communicate with peer, to check its incoming (recv) messages has been received. This is to avoid sending it again when it has been received, as it's kept "forever" by peer, we never need to send it again.

> Return value: the ticket used to check incoming messages.

— Function: u_int64_t lw6cnx_ticket_table_get_send (lw6cnx_ticket_table_t * ticket_table, char * peer_id)

> ticket_table: the ticket table to query

> peer_id: the id of remote node

> Gets the ticket used to communicate with peer, to stamp the outgoing messages. If ticket does not exist yet, 0 is returned, indeed this value must be initialized with the value the peer gives us.

> Return value: the ticket used to stamp outgoing messages.

— Function: void lw6cnx_ticket_table_set_send (lw6cnx_ticket_table_t * ticket_table, char * peer_id, u_int64_t send_ticket)

> ticket_table: the ticket table to query

> peer_id: the id of remote node

> send_ticket: the ticket to use to stamp outgoing messages

> Sets the ticket used to communicate with peer, to stamp the outgoing (send) messages. This value should be received from the network. Note that once it's set, it's impossible to change it, it will remain the same for the whole duration of the node existence.

> Return value: NULL