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

### 5.25 libmsg

#### 5.25.1 Overview

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

#### 5.25.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)

> info: the node info to use

> key: the key to identify the message

> Generate a FOO command.

> Return value: newly allocated string.

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

> info: the node info to use

> key: the key to identify the message

> Generate a BAR command.

> 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, int round, char * ker_msg)

> serial: the message serial number

> i: the message index in the group

> n: the number of messages in the group

> round: the message round (can have an offset with real round)

> 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: int lw6msg_cmd_analyse_hello (lw6nod_info_t ** info, 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, 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, char * msg)

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

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

> 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, char * msg)

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

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

> msg: the message to analyse

> Analyzes a BAR message.

> Return value: 1 on success, 0 on failure

— Function: int lw6msg_cmd_analyse_goodbye (lw6nod_info_t ** info, 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, int * round, char ** ker_msg, char * msg)

> serial: will contain serial number on success

> i: will contain group index on success

> n: will contain group size on success

> round: will contain round on success (can have an offset with real round)

> ker_msg: will contain actual message on success

> Analyzes a DATA message.

> Return value: 1 on success, 0 on failure

— Function: char * lw6msg_cmd_guess_from_url (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, char * version, 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, 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 (char * envelope, lw6msg_envelope_mode_t mode, char * local_url, 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: 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 (char * command, char * remote_url, char * password, 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, char * request, char * local_url, 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 (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_test (int mode)

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

> Runs the `nod` module test suite.

> 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, 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, 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, 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, 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, char * key, 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, 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, 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, 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, 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 (int * parsed_value, char ** next, 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_gt0 (int * parsed_value, char ** next, 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, 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, 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, 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 (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 (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.