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


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.


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