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

### 5.33 libmsg

#### 5.33.1 Overview

View lcov test coverage results on http://www.gnu.org/software/liquidwar6/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 (lw6sys_list_t ** list_a, 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: libnet, Previous: libmat, Up: C API [Contents][Index]