libmsg - Liquid War 6
Description: Liquid War 6

Next: libnet, Previous: libmat, Up: C API

### 5.33 libmsg

#### 5.33.1 Overview

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

#### 5.33.2 API

— Function: char * lw6msg_cmd_generate_hello (lw6nod_info_t * info)

> info: the node info to use

> Generate a HELLO command.

> Return value: newly allocated string.

— Function: char * lw6msg_cmd_generate_ticket (lw6nod_info_t * info, u_int64_t ticket)

> info: the node info to use

> ticket: the ticket to send

> Generate a TICKET command.

> Return value: newly allocated string.

— Function: char * lw6msg_cmd_generate_foo (lw6nod_info_t * info, u_int32_t key, int serial)

> info: the node info to use

> key: the key to identify the message

> serial: serial number of latest data message

> Generate a FOO command.

> Return value: newly allocated string.

— Function: char * lw6msg_cmd_generate_bar (lw6nod_info_t * info, u_int32_t key, int serial)

> info: the node info to use

> key: the key to identify the message

> serial: serial number of latest data message

> Generate a BAR command.

> Return value: newly allocated string.

— Function: char * lw6msg_cmd_generate_join (lw6nod_info_t * info, int64_t seq, int serial)

> info: the node info to use

> seq: the current seq

> serial: the serial message number to start with

> Generate a JOIN command. The seq parameter, if 0, means we want to request to join to a server. Wether this is a real server or a physical client acting as a server is out of consideration, 0 means request to join, period. If greater than 0, means we are accepting a client, and then the value is our current seq, which the client must use to calibrate its own data. The serial number is here to avoid querying messages before the join and keep the serie complete.

> Return value: newly allocated string.

— Function: char * lw6msg_cmd_generate_goodbye (lw6nod_info_t * info)

> info: the node info to use

> Generate a GOODBYE command.

> Return value: newly allocated string.

— Function: char * lw6msg_cmd_generate_data (int serial, int i, int n, int64_t seq, const char * ker_msg)

> serial: the message serial number

> i: the message index in the group

> n: the number of messages in the group

> seq: the message seq (round + an offset)

> ker_msg: the actual content of the message (passed to core algo)

> Generate a DATA command. Serial is an ever increasing number, i and n are most of the time 1 and 1, they are usefull only in long multipart messages.

> Return value: newly allocated string.

— Function: char * lw6msg_cmd_generate_meta (int serial, int i, int n, int64_t seq, const lw6msg_meta_array_t * meta_array)

> serial: the message serial number

> i: the message index in the group

> n: the number of messages in the group

> seq: the message seq (round + an offset)

> meta_array: the content to send

> Generate a META command. Serial is an ever increasing number, i and n are most of the time 1 and 1, they are usefull only in long multipart messages.

> Return value: newly allocated string.

— Function: char * lw6msg_cmd_generate_miss (u_int64_t id_from, u_int64_t id_to, int serial_min, int serial_max)

> id_from: id of the node which didn't send data correctly

> id_to: id of the node which didn't receive data correctly

> serial_min: minimum serial number of unsent/unreceived messages

> serial_max: maximum serial number of unsent/unreceived messages

> Generate a MISS command. This will request anyone who has the messages mentionned in stock to resent them to the one who's asking for them.

> Return value: newly allocated string.

— Function: int lw6msg_cmd_analyse_hello (lw6nod_info_t ** info, const char * msg)

> info: will contain (remote) node info on success

> msg: the message to analyse

> Analyzes a HELLO message.

> Return value: 1 on success, 0 on failure

— Function: int lw6msg_cmd_analyse_ticket (lw6nod_info_t ** info, u_int64_t * ticket, const char * msg)

> info: will contain (remote) node info on success

> ticket: if not NULL, will contain the ticket value on success

> msg: the message to analyse

> Analyzes a TICKET message.

> Return value: 1 on success, 0 on failure

— Function: int lw6msg_cmd_analyse_foo (lw6nod_info_t ** info, u_int32_t * key, int * serial, const char * msg)

> info: will contain (remote) node info on success

> key: if not NULL, will contain the foo/bar key on success

> serial: if not NULL, will contain the latest serial number of peer

> msg: the message to analyse

> Analyzes a FOO message.

> Return value: 1 on success, 0 on failure

— Function: int lw6msg_cmd_analyse_bar (lw6nod_info_t ** info, u_int32_t * key, int * serial, const char * msg)

> info: will contain (remote) node info on success

> key: if not NULL, will contain the foo/bar key on success

> serial: if not NULL, will contain the latest serial number of peer

> msg: the message to analyse

> Analyzes a BAR message.

> Return value: 1 on success, 0 on failure

— Function: int lw6msg_cmd_analyse_join (lw6nod_info_t ** info, lw6nod_info_t * local_info, int64_t * seq, int * serial, const char * msg)

> info: will contain (remote) node info on success

> local_info: local node info to be updated (peer_id list), can be NULL

> seq: sequence used to initialize communication

> serial: serial used to initialize communication

> msg: the message to analyse

> Analyzes a JOIN message.

> Return value: 1 on success, 0 on failure

— Function: int lw6msg_cmd_analyse_goodbye (lw6nod_info_t ** info, const char * msg)

> info: will contain (remote) node info on success

> msg: the message to analyse

> Analyzes a GOODBYE message.

> Return value: 1 on success, 0 on failure

— Function: int lw6msg_cmd_analyse_data (int * serial, int * i, int * n, int64_t * seq, char ** ker_msg, const char * msg)

> serial: will contain serial number on success

> i: will contain group index on success

> n: will contain group size on success

> seq: will contain seq on success (round + an offset)

> ker_msg: will contain actual message on success

> msg: the message to analyze

> Analyzes a DATA message.

> Return value: 1 on success, 0 on failure

— Function: int lw6msg_cmd_analyse_meta (int * serial, int * i, int * n, int64_t * seq, lw6msg_meta_array_t * meta_array, const char * msg)

> serial: will contain serial number on success

> i: will contain group index on success

> n: will contain group size on success

> seq: will contain seq on success (round + an offset)

> meta_array: will contain the content on success

> msg: the message to analyze

> Analyzes a META message.

> Return value: 1 on success, 0 on failure

— Function: int lw6msg_cmd_analyse_miss (u_int64_t * id_from, u_int64_t * id_to, int * serial_min, int * serial_max, const char * msg)

> id_from: will contain the id of the node which didn't send data correctly

> id_to: will contain the id of the node which didn't receive data correctly

> serial_min: will contain the minimum serial number of unsent/unreceived messages

> serial_max: will contain the maximum serial number of unsent/unreceived messages

> msg: the message to analyze

> Analyzes a MISS message.

> Return value: 1 on success, 0 on failure

— Function: char * lw6msg_cmd_guess_from_url (const char * msg)

> msg: the message to analyse

> Analyzes a GOODBYE message.

> Return value: the from url, if found (dynamically allocated)

— Function: char * lw6msg_envelope_generate (lw6msg_envelope_mode_t mode, const char * version, const char * password_checksum, u_int32_t physical_ticket_sig, u_int32_t logical_ticket_sig, u_int64_t physical_from_id, u_int64_t physical_to_id, u_int64_t logical_from_id, u_int64_t logical_to_id, const char * msg)

> mode: mode to use (a la TELNET or URL compatible)

> version: the program version to use (note: can be changed when testing)

> password_checksum: the password string to send

> physical_ticket_sig: the signature of the message, calculated with ticket + physical from/to

> logical_ticket_sig: the signature of the message, calculated with ticket + logical from/to

> physical_from_id: the sender id

> physical_to_id: the receiver id

> logical_from_id: the message creator id

> logical_to_id: the message final destination id

> msg: the body of the message

> Generate an envelope, that is, the complete message sendable on the network.

> Return value: newly allocated string.

— Function: int lw6msg_envelope_analyse (const char * envelope, lw6msg_envelope_mode_t mode, const char * local_url, const char * password, u_int64_t expected_physical_from_id, u_int64_t expected_physical_to_id, char ** msg, u_int32_t * physical_ticket_sig, u_int32_t * logical_ticket_sig, u_int64_t * physical_from_id, u_int64_t * physical_to_id, u_int64_t * logical_from_id, u_int64_t * logical_to_id, char ** physical_from_url)

> envelope: the envelope to analyse

> mode: mode to use (a la TELNET or URL compatible)

> local_url: the url of local server (usefull for password)

> password: the password to check against

> expected_physical_from_id: the sender id, if NULL, no check performed

> expected_physical_to_id: the receiver id, if NULL, no check performed

> msg: if not NULL, will contain body of the message

> physical_ticket_sig: if not NULL, will contain signature of message, calculated with ticket

> logical_ticket_sig: if not NULL, will contain signature of message, calculated with ticket

> physical_from_id: if not NULL, will contain sender id

> physical_to_id: if not NULL, will contain receiver id

> logical_from_id: if not NULL, will contain message creator id

> logical_to_id: if not NULL, will contain message final destination id

> physical_from_url: if not NULL and if message allows, will contain sender public URL

> Generate an envelope, that is, the complete message sendable on the network.

> Return value: newly allocated string.

— Function: void lw6msg_meta_array_zero (lw6msg_meta_array_t * meta_array)

> meta_array: meta meta_array (list of nodes) to modify

> Fills the meta meta_array with zeroes, emptying all nodes.

> Return value: none

— Function: int lw6msg_meta_array_find (const lw6msg_meta_array_t * meta_array, u_int64_t node_id)

> meta_array: meta meta_array (list of nodes) to modify

> node_id: the ID (64-bit) of the node to seartch

> Registers a node in the meta_array.

> Return value: 1 if registered, 0 if not (possible error: no place left)

— Function: int lw6msg_meta_array_exists (const lw6msg_meta_array_t * meta_array, u_int64_t node_id)

> meta_array: meta meta_array (list of nodes) to modify

> node_id: the ID (64-bit) of the node to test

> Registers a node in the meta_array.

> Return value: 1 if registered, 0 if not (possible error: no place left)

— Function: int lw6msg_meta_array_set (lw6msg_meta_array_t * meta_array, u_int64_t node_id, int serial_0, int64_t seq_0)

> meta_array: meta meta_array (list of nodes) to modify

> node_id: the ID (64-bit) of the node to add

> serial_0: base serialfor the node to add

> seq_0: base seq for for node to add

> Registers a node in the meta_array.

> Return value: 1 if registered, 0 if not (possible error: no place left)

— Function: int lw6msg_meta_array_unset (lw6msg_meta_array_t * meta_array, u_int64_t node_id)

> meta_array: meta meta_array (list of nodes) to modify

> node_id: the ID (64-bit) of the node to remove

> Unregisters a node in the meta_array.

> Return value: 1 if node existed, 0 if it was not here

— Function: int lw6msg_meta_str2array (lw6msg_meta_array_t * meta_array, const char * str)

> meta_array: meta meta_array (list of nodes) to get (out param)

> str: meta string (list of nodes) to be put in the meta_array

> Transforms a string describing the nodes and their id/serial/seq into a more usable C structure.

> Return value: 1 if parseable and success, 0 if not.

— Function: char * lw6msg_meta_array2str (const lw6msg_meta_array_t * meta_array)

> meta_array: meta meta_array (list of nodes) to transform as a string

> Transforms a C struct describing the nodes and their id/serial/seq into a string transmittable on the network.

> Return value: dynamically allocated string

— Function: char * lw6msg_oob_generate_info (lw6nod_info_t * info)

> info: the node to generate info about

> Generates a standard response to the INFO question for OOB (out of band) messages. The same message is sent, be it on http or tcp or udp, so it's factorized here. Function will lock the info object when needed.

> Return value: newly allocated string.

— Function: char * lw6msg_oob_generate_list (lw6nod_info_t * info)

> info: the node to generate info about

> Generates a standard response to the LIST question for OOB (out of band) messages. The same message is sent, be it on http or tcp or udp, so it's factorized here. Function will lock the info object when needed. There's a max length because we don't want the udp buffer to be saturated + too long lists do not really mean anything anyway.

> Return value: newly allocated string.

— Function: char * lw6msg_oob_generate_pong (lw6nod_info_t * info)

> info: the node to generate info about

> Generates a standard response to the PING question for OOB (out of band) messages. The same message is sent, be it on http or tcp or udp, so it's factorized here. Function will lock the info object when needed.

> Return value: newly allocated string.

— Function: char * lw6msg_oob_generate_request (const char * command, const char * remote_url, const char * password, const char * local_url)

> command: the command to send (PING, INFO, LIST)

> remote_url: the remote URL (used to seed password)

> password: the password, can be NULL or ""

> local_url: the public URL to send along with the message, can be NULL or ""

> Generates a simple clear text OOB request, with a password if needed.

> Return value: a newly allocated string

— Function: int lw6msg_oob_analyse_request (int * syntax_ok, char ** command, int * password_ok, char ** remote_url, const char * request, const char * local_url, const char * password)

> syntax_ok: will contain 1 if syntax is OK, 0 if not

> command: the command (out param, needs *not* to be freed)

> password_ok: will contain 1 if password is OK, 0 if not

> remote_url: the URL detected, if provided (out param, does needs to be freed)

> request: the request to analyse

> local_url: the local url (used to seed password)

> password: the password to check against

> Analyses a simple OOB message of the form COMMAND <passwd> <url>.

> Return value: 1 if OK, 0 if not. If 0, check the value of password_ok.

— Function: char * lw6msg_oob_analyse_pong (const char * text)

> text: the text of the message to parse

> Analyses a PONG message and gets the public_url from it, if it exists.

> Return value: newly allocated string containing public_url if OK, NULL on error.

— Function: int lw6msg_sort_str_by_seq_callback (const lw6sys_list_t ** list_a, const lw6sys_list_t ** list_b)

> list_a: pointer to a list of int item

> list_b: pointer to a list of int item

> Sort callback for a list containing strings which begin by a seq number, will sort with lower seq number first.

> Return value: -1 if `list_a` < `list_b` , 0 if `list_a` == `list_b`, 1 if `list_a` > `list_b`

— Function: int lw6msg_test_register (int mode)

> mode: test mode (bitmask)

> Registers all tests for the libmsg module.

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

— Function: int lw6msg_test_run (int mode)

> mode: test mode (bitmask)

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

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

— Function: u_int32_t lw6msg_ticket_calc_sig (u_int64_t ticket, u_int64_t from_id, u_int64_t to_id, const char * msg)

> ticket: the (private) ticket to use

> from_id: the sender/creator

> to_id: the receiver/target

> msg: the message to sign

> Produces a little signature, which is clearly vulnerable to brute-force attacks but makes it possible to be 100% sure if it's wrong, someone is trying to do something nasty (or there's a serious bug!).

> Return value: the sig, always non-zero

— Function: int lw6msg_ticket_check_sig (u_int64_t ticket, u_int64_t from_id, u_int64_t to_id, const char * msg, u_int32_t ticket_sig)

> ticket: the (private) ticket to use

> from_id: the sender/creator

> to_id: the receiver/target

> msg: the message to sign

> ticket_sig: the signature to check against

> Checks a sig is OK.

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

— Function: int lw6msg_utils_parse_key_value_to_ptr (char ** key, char ** value, const char * line)

> key: will contain the key detected

> value: will contain the value detected

> line: the line to analyse

> Analyses a trivial "KEY value" line and returns the key and the value in the passed pointers.

> Return value: 1 if line OK (and in this case `key` and `value` are set), 0 if not.

— Function: int lw6msg_utils_parse_key_value_to_assoc (lw6sys_assoc_t ** assoc, const char * line)

> assoc: an assoc object which will contain the result

> line: the line to analyse

> Analyses a trivial "KEY value" line and sets the `assoc` parameter according to detected values. Note that `assoc` must be set to contain string, and free them automatically with `lw6sys_free_callback` for instance.

> Return value: 1 if line OK (and in this case `assoc` is updated), 0 if not.

— Function: char * lw6msg_utils_get_assoc_str_with_default (lw6sys_assoc_t * assoc, const char * key, const char * default_value)

> assoc: the string assoc to query

> key: the key to find in the assoc

> default_value: the default value to return

> Queries a string assoc for a given value, and if not available, returns default value. Not that default value (nor the assoc value) is copied, so you must take care all remain valid until usage of returned value is over.

> Return value: a string, must not be freed.

— Function: int lw6msg_utils_get_assoc_int_with_default (lw6sys_assoc_t * assoc, const char * key, int default_value)

> assoc: the string assoc to query

> key: the key to find in the assoc

> default_value: the default value to return

> Queries a string assoc for a given value, and if not available, returns default value. Not that default value (nor the assoc value) is copied, so you must take care all remain valid until usage of returned value is over. This one will returned an int converted with `lw6sys_atoi`.

> Return value: a string, must not be freed.

— Function: int lw6msg_word_first (lw6msg_word_t * word, char ** next, const char * msg)

> word: will contain the parsed word

> next: if NOT NULL, will contain a (non freeable) pointer on remaining message

> msg: the message to parse

> Analyses a message and gets the first word. This word is put in `buf` member with its length. `next` is usefull if you want to parse the rest of the message, it points at the beginning of it.

> Return value: 1 on success, 0 on failure.

— Function: int lw6msg_word_first_x (lw6msg_word_t * word, char ** next, const char * msg)

> word: will contain the parsed word

> next: if NOT NULL, will contain a (non freeable) pointer on remaining message

> msg: the message to parse

> Analyses a message and gets the first word. This word is put in `buf` member with its length. `next` is usefull if you want to parse the rest of the message, it points at the beginning of it. This special `x` function will consider slash ("/") as valid separator. It can't be used all the time but for almost every field but URLs, it's fine. Internally, this one is used to parse integers, IDs, etc.

> Return value: 1 on success, 0 on failure.

— Function: int lw6msg_word_first_base64 (lw6msg_word_t * word, char ** next, const char * msg)

> word: will contain the parsed word

> next: if NOT NULL, will contain a (non freeable) pointer on remaining message

> msg: the message to parse

> Analyses a message and gets the first word. This word is put in `buf` member with its length. `next` is usefull if you want to parse the rest of the message, it points at the beginning of it. The word is expected to be base64 encoded and is decoded on-the-fly.

> Return value: 1 on success, 0 on failure.

— Function: int lw6msg_word_first_int_32 (int32_t * parsed_value, char ** next, const char * msg)

> parsed_value: will contain the parsed value

> next: if NOT NULL, will contain a (non freeable) pointer on remaining message

> msg: the message to parse

> Analyses a message, gets the first word and interpret it as an int.

> Return value: 1 on success, 0 on failure.

— Function: int lw6msg_word_first_int_32_ge0 (int32_t * parsed_value, char ** next, const char * msg)

> parsed_value: will contain the parsed value

> next: if NOT NULL, will contain a (non freeable) pointer on remaining message

> msg: the message to parse

> Analyses a message, gets the first word and interpret it as an int. The value must be strictly greater than 0.

> Return value: 1 on success, 0 on failure.

— Function: int lw6msg_word_first_int_32_gt0 (int32_t * parsed_value, char ** next, const char * msg)

> parsed_value: will contain the parsed value

> next: if NOT NULL, will contain a (non freeable) pointer on remaining message

> msg: the message to parse

> Analyses a message, gets the first word and interpret it as an int. The value must be strictly greater than 0.

> Return value: 1 on success, 0 on failure.

— Function: int lw6msg_word_first_int_64 (int64_t * parsed_value, char ** next, const char * msg)

> parsed_value: will contain the parsed value

> next: if NOT NULL, will contain a (non freeable) pointer on remaining message

> msg: the message to parse

> Analyses a message, gets the first word and interpret it as an int.

> Return value: 1 on success, 0 on failure.

— Function: int lw6msg_word_first_int_64_ge0 (int64_t * parsed_value, char ** next, const char * msg)

> parsed_value: will contain the parsed value

> next: if NOT NULL, will contain a (non freeable) pointer on remaining message

> msg: the message to parse

> Analyses a message, gets the first word and interpret it as an int. The value must be strictly greater than 0.

> Return value: 1 on success, 0 on failure.

— Function: int lw6msg_word_first_int_64_gt0 (int64_t * parsed_value, char ** next, const char * msg)

> parsed_value: will contain the parsed value

> next: if NOT NULL, will contain a (non freeable) pointer on remaining message

> msg: the message to parse

> Analyses a message, gets the first word and interpret it as an int. The value must be strictly greater than 0.

> Return value: 1 on success, 0 on failure.

— Function: int lw6msg_word_first_id_16 (u_int16_t * parsed_value, char ** next, const char * msg)

> parsed_value: will contain the parsed value

> next: if NOT NULL, will contain a (non freeable) pointer on remaining message

> msg: the message to parse

> Analyses a message, gets the first word and interpret it as an 16-bit id.

> Return value: 1 on success, 0 on failure.

— Function: int lw6msg_word_first_id_32 (u_int32_t * parsed_value, char ** next, const char * msg)

> parsed_value: will contain the parsed value

> next: if NOT NULL, will contain a (non freeable) pointer on remaining message

> msg: the message to parse

> Analyses a message, gets the first word and interpret it as an 32-bit id.

> Return value: 1 on success, 0 on failure.

— Function: int lw6msg_word_first_id_64 (u_int64_t * parsed_value, char ** next, const char * msg)

> parsed_value: will contain the parsed value

> next: if NOT NULL, will contain a (non freeable) pointer on remaining message

> msg: the message to parse

> Analyses a message, gets the first word and interpret it as an 64-bit id.

> Return value: 1 on success, 0 on failure.

— Function: char * lw6msg_z_encode (const char * msg, int limit)

> msg: message to encode

> limit: if under this limit (length in bytes), do not encode, return as is

> Z-encode a message, by "Z-encoding" we mean pass the string through 1) zlib then 2) base64 encoding, this way we get a string without any blank and/or special character, and of reasonnable length. There's an optional limit *not* to encode anything, just when we know there are no special characters to escape and string is small, it's useless to fire this big artillery.

> Return value: newly allocated string, 0 terminated, NULL on error.

— Function: char * lw6msg_z_decode (const char * msg)

> msg: message to decode

> Z-decode a message, by "Z-encoding" we mean pass the string through 1) zlib then 2) base64 encoding, this way we get a string without any blank and/or special character, and of reasonnable length. This decode string does it the reverse way, un64-encode the string then uncompress it back to a readable string.

> Return value: newly allocated string, 0 terminated, NULL on error.

— Struct: lw6msg_meta_array_item_s
— Member of lw6msg_meta_array_item_s: node_id

> Type: `u_int64_t`

> Definition: `u_int64_t lw6msg_meta_array_item_s::node_id`

— Member of lw6msg_meta_array_item_s: serial_0

> Type: `int`

> Definition: `int lw6msg_meta_array_item_s::serial_0`

— Member of lw6msg_meta_array_item_s: seq_0

> Type: `int64_t`

> Definition: `int64_t lw6msg_meta_array_item_s::seq_0`

— Struct: lw6msg_meta_array_s
— Member of lw6msg_meta_array_s: logical_from

> Type: `u_int64_t`

> Definition: `u_int64_t lw6msg_meta_array_s::logical_from`

— Member of lw6msg_meta_array_s: items

> Type: `lw6msg_meta_array_item_t`

> Definition: `lw6msg_meta_array_item_t lw6msg_meta_array_s::items[LW6MSG_NB_META_ARRAY_ITEMS]`

— Struct: lw6msg_word_s

> This structure is used to retrieve words from messages. We use a structure here with a fixed sized buffer and a len member, this is to avoid mallocating too often when parsing.

— Member of lw6msg_word_s: len

> Type: `int`

> Definition: `int lw6msg_word_s::len`

> Length of word, in bytes.

— Member of lw6msg_word_s: buf

> Type: `char`

> Definition: `char lw6msg_word_s::buf[LW6MSG_MAX_WORD_SIZE+1]`

> Word data, containing a 0 char at the end, so it is safe to call standard C string functions on it.