Next: libdef, Previous: libcnx, Up: C API

### 5.14 libdat

#### 5.14.1 Overview

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

#### 5.14.2 API

— Function: int lw6dat_test (int mode)

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

> Runs the `dat` module test suite.

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

— Function: lw6dat_warehouse_t * lw6dat_warehouse_new (u_int64_t local_node_id)

> Creates a new warehouse object.

> Return value: new object, allocated dynamically

— Function: void lw6dat_warehouse_free (lw6dat_warehouse_t * warehouse)

> warehouse: the object to free

> Frees a warehouse object.

> Return value: new object, allocated dynamically

— Function: void lw6dat_warehouse_purge (lw6dat_warehouse_t * warehouse)

> warehouse: the object to purge

> Purges a warehouse object.

> Return value: new object, allocated dynamically

— Function: int lw6dat_warehouse_get_nb_nodes (lw6dat_warehouse_t * warehouse)

> warehouse: the warehouse object to query.

> Tells how many nodes are registered in the object.

> Return value: integer, number of nodes

— Function: u_int64_t lw6dat_warehouse_get_local_id (lw6dat_warehouse_t * warehouse)

> warehouse: the warehouse object to query.

> Returns the local id.

> Return value: 64-bit id.

— Function: int lw6dat_warehouse_get_local_serial (lw6dat_warehouse_t * warehouse)

> warehouse: the warehouse object to query.

> Returns the latest (highest) serial number given for local node.

> Return value: integer, latest serial number

— Function: int lw6dat_warehouse_put_atom_str (lw6dat_warehouse_t * warehouse, u_int64_t logical_from, char * full_str)

> warehouse: warehouse object to use

> logical_from: from who the message came from originally

> full_str: message of the form serial i n seq from cmd

> Puts an atomic string in the object, this kind of string is typically received on the network.

> Return value: 1 on success, 0 on error

— Function: int lw6dat_warehouse_calc_serial_draft_and_reference (lw6dat_warehouse_t * warehouse)

> warehouse: object to work on

> The various `get_seq` functions can perform slowly if we don't pre-calculate the serial number of draft and reference atoms. So this calculation is not within the functions themselves but can be cached by using this function. Just call it and after you might query the object for reference and draft info.

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

— Function: int lw6dat_warehouse_put_local_msg (lw6dat_warehouse_t * warehouse, char * msg)

> warehouse: warehouse object to use

> msg: message

> Puts a message in the object. The message will be splitted into several atoms if needed, it can be arbitrary long.

> Return value: 1 on success, 0 on error

— Function: int lw6dat_warehouse_get_seq_min (lw6dat_warehouse_t * warehouse)

> warehouse: object to query

> Tells the lowest seq referenced in the warehouse. Does not mean this is the lowest ever received, only we really have no chances of going below that point, nothing is stored, either complete or partial, below that.

> Return value: integer.

— Function: int lw6dat_warehouse_get_seq_max (lw6dat_warehouse_t * warehouse)

> warehouse: object to query

> Tells the highest seq referenced in the warehouse. Does not mean an actual message can be built from it, only we've got some traces of such a high seq.

> Return value: integer.

— Function: int lw6dat_warehouse_get_seq_draft (lw6dat_warehouse_t * warehouse)

> warehouse: object to query

> Tells the highest seq that can be considered as a valid draft. This is not exactly the maximimum seq encountered, for here we want at least one complete message and not just one chunk of data (an atom) referring to a high seq, we want the complete stuff. However there can be missing messages in between.

> Return value: integer.

— Function: int lw6dat_warehouse_get_seq_reference (lw6dat_warehouse_t * warehouse)

> warehouse: object to query

> Tells the highest seq that can be considered as a reference. Being considered as a reference means we received all messages for this seq *and* at least one message from the following seq, and this for every node involved. This being said, we're sure to have the right information, nothing is missing.

> Return value: integer.

— Function: lw6sys_list_t * lw6dat_warehouse_get_msg_list_by_seq (lw6dat_warehouse_t * warehouse, int seq_min, int seq_max)

> warehouse: object to query

> seq_min: lowest sequence number (round or chat index)

> seq_max: highest sequence number (round or chat index)

> Gets the list of messages for a given sequence (round or chat index), polling all the nodes. The from and to boundaries are included.

> Return value: a list of strings.

— Function: lw6sys_list_t * lw6dat_warehouse_get_atom_str_list_not_sent (lw6dat_warehouse_t * warehouse, u_int64_t logical_to)

> warehouse: object to query

> logical_to: the id of the node that we want to send data to

> Returns all the messages that were not sent for the given warehouse.

> Return value: a list of strings, containing atoms.