View lcov test coverage results on http://www.ufoot.org/liquidwar/v6/doc/coverage/src/lib/cnx/index.html.
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.
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.
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.
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.
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.
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.
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
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.
sys_context: global system context
packet: object to free
Frees a packet object.
Return value: none.
sys_context: global system context
packet: packet to analyse
Calculates a checksum for a packet.
Return value: 32-bit checksum.
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.
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.
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
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.
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.
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.
sys_context: global system context
ticket_table: the ticket table to fill with zero
Fills the ticket table struct with 0s.
Return value: none.
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.
sys_context: global system context
ticket_table: the ticket table to clear
Clears the object (frees memory).
Return value: none.
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.
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.
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.
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.
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
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.
Type: char *
Definition: char* lw6cnx_connection_s::local_url
URL of our local node.
Type: char *
Definition: char* lw6cnx_connection_s::remote_url
URL of the remote node.
Type: char *
Definition: char* lw6cnx_connection_s::remote_ip
IP address of the remote node.
Type: int
Definition: int lw6cnx_connection_s::remote_port
IP port of the remote node.
Type: char *
Definition: char* lw6cnx_connection_s::password
Password as clear text.
Type: char *
Definition: char* lw6cnx_connection_s::password_send_checksum
Password as a checksum, what will be sent on the network.
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.
Type: char *
Definition: char* lw6cnx_connection_s::local_id_str
ID of the local node, as an hexa string.
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.
Type: char *
Definition: char* lw6cnx_connection_s::remote_id_str
ID of the local node, as an hexa string.
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.
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.
Type: lw6cnx_properties_t
Definition: lw6cnx_properties_t lw6cnx_connection_s::properties
Properties got from the backend.
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.
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.
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.
Type: int64_t
Definition: int64_t lw6cnx_connection_s::last_send_foo_timestamp
The last time FOO was sent.
Type: int64_t
Definition: int64_t lw6cnx_connection_s::next_send_foo_timestamp
The next time FOO needs to be sent.
Type: int
Definition: int lw6cnx_connection_s::ping_msec
The current ping, updated when receiving BAR message.
Type: int
Definition: int lw6cnx_connection_s::sent_nb_total
Number of sent messages on this cnx.
Type: int
Definition: int lw6cnx_connection_s::sent_nb_success
Number of successfully sent messages on this cnx.
Type: int
Definition: int lw6cnx_connection_s::sent_nb_fail
Number of failed sent messages on this cnx.
Type: int64_t
Definition: int64_t lw6cnx_connection_s::last_recv_timestamp
Last time something was received on this connection.
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.
Used to hold a network message plus some metadata, such as who it is for, and who emitted the message.
Type: u_int32_t
Definition: u_int32_t lw6cnx_packet_s::logical_ticket_sig
Logical signature for the packet.
Type: u_int32_t
Definition: u_int32_t lw6cnx_packet_s::physical_ticket_sig
Physical signature for the packet.
Type: u_int64_t
Definition: u_int64_t lw6cnx_packet_s::logical_from_id
Logical sender.
Type: u_int64_t
Definition: u_int64_t lw6cnx_packet_s::logical_to_id
Logical receiver.
Type: char *
Definition: char* lw6cnx_packet_s::msg
Used to hold generic client/server properties, set up by the backend, can then be queried by the caller.
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.
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.
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!
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.
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.
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.
Type: lw6sys_spinlock_t *
Definition: lw6sys_spinlock_t* lw6cnx_ticket_table_s::recv_spinlock
Lock for the recv_table hash.
Type: lw6sys_spinlock_t *
Definition: lw6sys_spinlock_t* lw6cnx_ticket_table_s::recv_ack_spinlock
Lock for the recv_ack_table hash.
Type: lw6sys_spinlock_t *
Definition: lw6sys_spinlock_t* lw6cnx_ticket_table_s::send_spinlock
Lock for the send_table hash.
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.
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.
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.