Next: , Previous: , Up: C API   [Contents][Index]


5.13 libcnx

5.13.1 Overview

View lcov test coverage results on http://www.ufoot.org/liquidwar/v6/doc/coverage/src/lib/cnx/index.html.

5.13.2 API

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

sys_context: global system context

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

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 (lw6sys_context_t * sys_context, lw6cnx_connection_t * connection)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6cnx_connection_t * connection, int64_t now)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6cnx_connection_t * connection, int64_t now, int next_foo_delay)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6cnx_connection_t * connection)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6cnx_connection_t * connection)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6cnx_connection_t * connection)

sys_context: global system context

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: lw6cnx_packet_t * lw6cnx_packet_new (lw6sys_context_t * sys_context, u_int32_t logical_ticket_sig, u_int32_t physical_ticket_sig, u_int64_t logical_from_id, u_int64_t logical_to_id, const char * msg)

sys_context: global system context

logical_ticket_sig: logical signature

physical_ticket_sig: physical signature

logical_from_id: logical sender

logical_to_id: logical receiver

msg: the message text

Creates a new packet object, this simply allocates memory and copy the string. The string is duplicated, param msg can be freed.

Return value: new object.

Function: void lw6cnx_packet_free (lw6sys_context_t * sys_context, lw6cnx_packet_t * packet)

sys_context: global system context

packet: object to free

Frees a packet object.

Return value: none.

Function: u_int32_t lw6cnx_packet_checksum (lw6sys_context_t * sys_context, const lw6cnx_packet_t * packet)

sys_context: global system context

packet: packet to analyse

Calculates a checksum for a packet.

Return value: 32-bit checksum.

Function: int lw6cnx_packet_compare (lw6sys_context_t * sys_context, const lw6cnx_packet_t * a, const lw6cnx_packet_t * b)

sys_context: global system context

a: first packet to analyse

b: second packet to analyse

Compares two packets. The comparison is made using checksums, the result is a strcmp-like integer, which is adapted to sorting. The order has no real signification, it’s mostly used to re-order packets in a pseudo-random order, to ensure no algorithm relies on packets arriving in the right order.

Return value: -1 if a lower than b, 0 if a equals b, 1 if a is greater than b.

Function: int lw6cnx_packet_sort_callback (lw6sys_context_t * sys_context, void * func_data, const void * ptr_a, const void * ptr_b)

sys_context: global system context

func_data: additionnal data, function specific

ptr_a: first packet to analyse

ptr_b: second packet to analyse

Callback usable to sort packets, relies on lw6cnx_packet_compare internally.

Return value: -1 if ptr_a lower than ptr_b, 0 if ptr_a equals ptr_b, 1 if ptr_a is greater than ptr_b.

Function: char * lw6cnx_password_checksum (lw6sys_context_t * sys_context, const char * seed, const char * password)

sys_context: global system context

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 (lw6sys_context_t * sys_context, const char * seed, const char * password_here, const char * password_received)

sys_context: global system context

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_register (lw6sys_context_t * sys_context, int mode)

sys_context: global system context

mode: test mode (bitmask)

Registers all tests for the libcnx module.

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

Function: int lw6cnx_test_run (lw6sys_context_t * sys_context, int mode)

sys_context: global system context

mode: test mode (bitmask)

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

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

Function: void lw6cnx_ticket_table_zero (lw6sys_context_t * sys_context, lw6cnx_ticket_table_t * ticket_table)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6cnx_ticket_table_t * ticket_table, int hash_size)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6cnx_ticket_table_t * ticket_table)

sys_context: global system context

ticket_table: the ticket table to clear

Clears the object (frees memory).

Return value: none.

Function: u_int64_t lw6cnx_ticket_table_get_recv (lw6sys_context_t * sys_context, lw6cnx_ticket_table_t * ticket_table, const char * peer_id)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6cnx_ticket_table_t * ticket_table, const char * peer_id, int ack_delay_msec)

sys_context: global system context

ticket_table: the ticket table to query

peer_id: the id of remote node

ack_delay_msec: delay before which we’ll consider the ticket as really received

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. The delay is here to avoid checking tickets too quickly, for instance one could have sent the ticket yet, but for some reason some unsigned messages are still in the pipe, typically they transit through another slow channel such as httpd while the ticket was sent on udp.

Return value: none.

Function: int lw6cnx_ticket_table_was_recv_exchanged (lw6sys_context_t * sys_context, lw6cnx_ticket_table_t * ticket_table, const char * peer_id)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6cnx_ticket_table_t * ticket_table, const char * peer_id)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6cnx_ticket_table_t * ticket_table, const char * peer_id, u_int64_t send_ticket)

sys_context: global system context

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

Struct: lw6cnx_connection_s

This structure holds all data associated to a physical connexion with a remote peer. This includes informations about the local node, informations about the peer, and protocol specific details. Depending on which backend is used to handle the connection, it will behave differently. If you search for attributes such as socket id, search for them in backend_specific_data which is, in fact, handle by the backend code.

Member of lw6cnx_connection_s: local_url

Type: char *

Definition: char* lw6cnx_connection_s::local_url

URL of our local node.

Member of lw6cnx_connection_s: remote_url

Type: char *

Definition: char* lw6cnx_connection_s::remote_url

URL of the remote node.

Member of lw6cnx_connection_s: remote_ip

Type: char *

Definition: char* lw6cnx_connection_s::remote_ip

IP address of the remote node.

Member of lw6cnx_connection_s: remote_port

Type: int

Definition: int lw6cnx_connection_s::remote_port

IP port of the remote node.

Member of lw6cnx_connection_s: password

Type: char *

Definition: char* lw6cnx_connection_s::password

Password as clear text.

Member of lw6cnx_connection_s: password_send_checksum

Type: char *

Definition: char* lw6cnx_connection_s::password_send_checksum

Password as a checksum, what will be sent on the network.

Member of lw6cnx_connection_s: local_id_int

Type: u_int64_t

Definition: u_int64_t lw6cnx_connection_s::local_id_int

ID of the local node, as an unsigned 64-bit integer.

Member of lw6cnx_connection_s: local_id_str

Type: char *

Definition: char* lw6cnx_connection_s::local_id_str

ID of the local node, as an hexa string.

Member of lw6cnx_connection_s: remote_id_int

Type: u_int64_t

Definition: u_int64_t lw6cnx_connection_s::remote_id_int

ID of the remote node, as an unsigned 64-bit integer.

Member of lw6cnx_connection_s: remote_id_str

Type: char *

Definition: char* lw6cnx_connection_s::remote_id_str

ID of the local node, as an hexa string.

Member of lw6cnx_connection_s: dns_ok

Type: int

Definition: int lw6cnx_connection_s::dns_ok

Will be set to 1 if the peer domain name is the same as the one reported in the URL. For instance, if we get a connection from 23.45.23.45, but this host claims to be on www.foo.bar and DNS reports www.foo.bar as being 111.222.111.222 then there’s something strange. It could just be someone doing NAT, but in all cases it’s worth mentionning, so we keep the information here. Having 0 here is a bad point for the connection.

Member of lw6cnx_connection_s: network_reliability

Type: int

Definition: int lw6cnx_connection_s::network_reliability

The higher, the most reliable message sending will be. It can never be perfect, LW6 will always drop some packets from time to time, just to simulate real packet loss and be sure if it happens, it’s handled nicely.

Member of lw6cnx_connection_s: properties

Type: lw6cnx_properties_t

Definition: lw6cnx_properties_t lw6cnx_connection_s::properties

Properties got from the backend.

Member of lw6cnx_connection_s: recv_list

Type: lw6sys_list_r_t *

Definition: lw6sys_list_r_t* lw6cnx_connection_s::recv_list

List of messages received. This is a list_r and not a plain list because it can typically be filled and consumed in different threads.

Member of lw6cnx_connection_s: send_mutex

Type: lw6sys_mutex_t *

Definition: lw6sys_mutex_t* lw6cnx_connection_s::send_mutex

Send mutex, this will be used so that sending operations are properly serialized. Indeed, threads that respond on the fly could be likely to call this concurrently.

Member of lw6cnx_connection_s: foo_bar_key

Type: u_int32_t

Definition: u_int32_t lw6cnx_connection_s::foo_bar_key

This is used to handle keepalive. Actually, the protocol is that from time to time FOO key is sent and then each connection (in a tentacle object, typically) is supposed to respond BAR key to show it has received the latest message. This field just stores the value so that when we receive a BAR message we know which key to check against.

Member of lw6cnx_connection_s: last_send_foo_timestamp

Type: int64_t

Definition: int64_t lw6cnx_connection_s::last_send_foo_timestamp

The last time FOO was sent.

Member of lw6cnx_connection_s: next_send_foo_timestamp

Type: int64_t

Definition: int64_t lw6cnx_connection_s::next_send_foo_timestamp

The next time FOO needs to be sent.

Member of lw6cnx_connection_s: ping_msec

Type: int

Definition: int lw6cnx_connection_s::ping_msec

The current ping, updated when receiving BAR message.

Member of lw6cnx_connection_s: sent_nb_total

Type: int

Definition: int lw6cnx_connection_s::sent_nb_total

Number of sent messages on this cnx.

Member of lw6cnx_connection_s: sent_nb_success

Type: int

Definition: int lw6cnx_connection_s::sent_nb_success

Number of successfully sent messages on this cnx.

Member of lw6cnx_connection_s: sent_nb_fail

Type: int

Definition: int lw6cnx_connection_s::sent_nb_fail

Number of failed sent messages on this cnx.

Member of lw6cnx_connection_s: last_recv_timestamp

Type: int64_t

Definition: int64_t lw6cnx_connection_s::last_recv_timestamp

Last time something was received on this connection.

Member of lw6cnx_connection_s: backend_specific_data

Type: void *

Definition: void* lw6cnx_connection_s::backend_specific_data

Store backend data, this is when, for instance, a socket handle will be kept, or a library handle (CURL, to name it). Common code does not know what’s in there.

Struct: lw6cnx_packet_s

Used to hold a network message plus some metadata, such as who it is for, and who emitted the message.

Member of lw6cnx_packet_s: logical_ticket_sig

Type: u_int32_t

Definition: u_int32_t lw6cnx_packet_s::logical_ticket_sig

Logical signature for the packet.

Member of lw6cnx_packet_s: physical_ticket_sig

Type: u_int32_t

Definition: u_int32_t lw6cnx_packet_s::physical_ticket_sig

Physical signature for the packet.

Member of lw6cnx_packet_s: logical_from_id

Type: u_int64_t

Definition: u_int64_t lw6cnx_packet_s::logical_from_id

Logical sender.

Member of lw6cnx_packet_s: logical_to_id

Type: u_int64_t

Definition: u_int64_t lw6cnx_packet_s::logical_to_id

Logical receiver.

Member of lw6cnx_packet_s: msg

Type: char *

Definition: char* lw6cnx_packet_s::msg

Struct: lw6cnx_properties_s

Used to hold generic client/server properties, set up by the backend, can then be queried by the caller.

Member of lw6cnx_properties_s: hint_timeout

Type: int

Definition: int lw6cnx_properties_s::hint_timeout

Gives an idea of what timeout one can expect with this backend, this is not necessarly the exact timeout but it gives an order of magnitude. Unit is seconds.

Member of lw6cnx_properties_s: ping_alter_base

Type: int

Definition: int lw6cnx_properties_s::ping_alter_base

Modifies the ping returned by terrain experience, this is a way to help some kind of connections to be preferred over others. Set it to N to add N milliseconds to the real ping. Adding a few msecs, such as 1 or 5 will just give an advantage to a given connection while not giving really wrong results. High values like 50 or 100 seriously penalizes some kind of connections, which is whishable, think of the httpd way to send things for instance.

Member of lw6cnx_properties_s: ping_alter_percent

Type: int

Definition: int lw6cnx_properties_s::ping_alter_percent

Modifies the ping returned by terrain experience, this is a way to help some kind of connections to be preferred over others. Set it to 100 for default value, means 100% of real ping delay, set it to 50 to make the algorithm believe lag is twice lower (this means, connection twice faster) and set it to 1000 to make believe that everything is slow. In practice only a slight alteration should be required, one should still favor really fast connections when it’s proved in real life that they are faster!

Member of lw6cnx_properties_s: reliable

Type: int

Definition: int lw6cnx_properties_s::reliable

Wether this connexion is to be considered reliable or not. Well, in LW6, all connexions are unrealiable since LW6 will drop packets on purpose to simulate problems, but however, some are well-known to be unreliable (UDP...) while others are OK.

Member of lw6cnx_properties_s: backend_id

Type: const char *

Definition: const char* lw6cnx_properties_s::backend_id

The backend id, beware, this is a static string, must not be freed, and depends on backend library to be here, if this one is unloaded, will point to nowhere.

Struct: lw6cnx_ticket_table_s

A common, shared table, to store all the tickets associated with various connections. This needs to be in-memory and quite fast for it’s called very often (at each message, in fact) to perform sanity checks and avoid fakes/cheaters.

Member of lw6cnx_ticket_table_s: recv_spinlock

Type: lw6sys_spinlock_t *

Definition: lw6sys_spinlock_t* lw6cnx_ticket_table_s::recv_spinlock

Lock for the recv_table hash.

Member of lw6cnx_ticket_table_s: recv_ack_spinlock

Type: lw6sys_spinlock_t *

Definition: lw6sys_spinlock_t* lw6cnx_ticket_table_s::recv_ack_spinlock

Lock for the recv_ack_table hash.

Member of lw6cnx_ticket_table_s: send_spinlock

Type: lw6sys_spinlock_t *

Definition: lw6sys_spinlock_t* lw6cnx_ticket_table_s::send_spinlock

Lock for the send_table hash.

Member of lw6cnx_ticket_table_s: recv_table

Type: lw6sys_hash_t *

Definition: lw6sys_hash_t* lw6cnx_ticket_table_s::recv_table

Hash table containing the tickets for recv operations. This table is auto-generated, if one asks for a ticket for an unknown host, one is generated. The key is the ID (64-bit integer) of the host, as an hexa string.

Member of lw6cnx_ticket_table_s: recv_ack_table

Type: lw6sys_hash_t *

Definition: lw6sys_hash_t* lw6cnx_ticket_table_s::recv_ack_table

Hash table containing wether the send ticket was received by a given host. The data is just a NULL pointer, only if the key is present, we know we don’t need to resend our key to the peer. An easy way to know that the key was sent is if the peer was abled to produce a valid message/checksum. The key is the ID (64-bit integer) of the host, as an hexa string.

Member of lw6cnx_ticket_table_s: send_table

Type: lw6sys_hash_t *

Definition: lw6sys_hash_t* lw6cnx_ticket_table_s::send_table

Hash table containing the tickets for send operations. Those tickets are typically received from the peers themselves who generate them on the fly. The key is the ID (64-bit integer) of the host, as an hexa string.


Next: , Previous: , Up: C API   [Contents][Index]