Next: , Previous: libmap, Up: C API


5.27 libmsg

5.27.1 Overview

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

5.27.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_ge0 (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_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.