Next: , Previous: libcns, Up: C API


5.13 libcnx

5.13.1 Overview

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

5.13.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