Next: libpil, Previous: libnod, Up: C API

### 5.30 libp2p

#### 5.30.1 Overview

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

#### 5.30.2 API

— Function: lw6p2p_db_t * lw6p2p_db_open (int argc, char * [] argv, char * name)

> argc: number of args, as passed to `main`

> argv: args array, as passed to `main`

> name: the database name

> Creates a new database object. Normally there's only one object like this at a given time, it can be shared among various nodes. The database name is appended to user directory path, this allows different databases to be created, in theory.

> Return value: a pointer on the newly created object.

— Function: void lw6p2p_db_close (lw6p2p_db_t * db)

> db: the db to close

> Closes a db object, memory ressources will be freed.

> Return value: none.

— Function: char * lw6p2p_db_repr (lw6p2p_db_t * db)

> db: the db to work on

> Gives a readable representation of the db

> Return value: a dynamically allocated string

— Function: int lw6p2p_db_reset (int argc, char * [] argv, char * name)

> argc: number of args, as passed to `main`

> argv: args array, as passed to `main`

> name: the database name

> Clears the database. Simply removes the db file, in fact. Do not call while database is used...

> Return value: 1 on success, 0 if failed.

— Function: char * lw6p2p_db_default_name ()

> Returns the default database name, should be p2p.db (this is a relative path, not an absolute path, will be appended to user dir).

> Return value: the default database name, need not (must not) be freed.

— Function: int _lw6p2p_db_now (_lw6p2p_db_t * db)

> db: the db object concerned (used to calculate time origin)

> Returns a timestamp suitable for db usage. The reason we don't use regular timestamps is that they are 1) too accurate (msec is useless for what's involved here) and 2) too big and likely to be negative in signed mode even if converted to seconds.

> Return value: a timestamp, 0 means "beginning of program" (think of it as uptime)

— Function: lw6p2p_entry_t * lw6p2p_entry_new (int creation_timestamp, char * version, char * codename, int stamp, char * id, char * url, char * title, char * description, int has_password, int bench, int open_relay, char * community_id, int round, char * level, int required_bench, int nb_colors, int max_nb_colors, int nb_cursors, int max_nb_cursors, int nb_nodes, int max_nb_nodes, char * ip, int port, int last_ping_timestamp, int ping_delay_msec, int available)

> creation_timestamp: when it has been created, UNIX timestamp

> version: version of the node

> codename: codename of the node

> stamp: stamp of the node

> id: id of the node (string representation)

> url: public url of the node

> title: title of the node

> description: description of the node

> has_password: wether node is password protected or not

> bench: node bench

> open_relay: wether the node is in open relay mode or not

> round: current round

> level: current level played

> required_bench: current bench

> nb_colors: number of colors playing

> max_nb_colors: maximum number of colors

> nb_cursors: number of cursors playing

> max_nb_cursors: maximum number of cursors

> nb_nodes: number of nodes playing

> max_nb_nodes: maximum number of nodes

> ip: node ip (string representation)

> port: node port

> last_ping_timestamp: UNIX timestamp of last contact with node

> ping_delay_msec: ping delay, in milliseconds

> available: wether node is available, wether we can connect to it

> Creates a new p2p entry. Will accept NULL parameters for strings as well as arbitrary long strings, will simply cut them short if there aren't already limited to max size.

> Return value: newly allocated object

— Function: void lw6p2p_entry_free (lw6p2p_entry_t * entry)

> entry: entry to free

> Frees a p2p entry.

> Return value: none.

— Function: char * lw6p2p_entry_repr (lw6p2p_entry_t * entry)

> entry: entry to represent

> Gives a human-readable representation of the entry

> Return value: dynamically allocated string

— Function: lw6p2p_node_t * lw6p2p_node_new (int argc, char * [] argv, lw6p2p_db_t * db, char * client_backends, char * server_backends, char * bind_ip, int bind_port, int broadcast, char * public_url, char * title, char * description, char * password, int bench, int open_relay, char * known_nodes, int network_reliability, int trojan)

> argc: number of args, as passed to `main`

> argv: args array, as passed to `main`

> db: the database to use

> client_backends: the list of client backends to use

> server_backends: the list of server backends to use

> bind_ip: the IP address to bind on

> bind_port: the IP port to listen on

> broadcast: wether broadcast is allowed on this node

> public_url: the public URL we want to show

> title: the title of the node

> description: the description of the node

> password: the password to use

> bench: the bench of the node (its power)

> open_relay: act as an open relay or not

> known_nodes: list of already known nodes

> network_reliability: drop 1 packet out of X

> trojan: act as a stupid trojan to test out automatic kick-off

> Creates a new "pear to pear" node. This will fire the server and allow client access, on demand. A lot of stuff can be done in the background once this is called.

> Return value: a pointer on the newly created objects.

— Function: void lw6p2p_node_free (lw6p2p_node_t * node)

> node: the node to free

> Frees a node object, all network communications will be shut.

> Return value: none.

— Function: char * lw6p2p_node_repr (lw6p2p_node_t * node)

> node: the node to work on

> Gives a readable representation of the node

> Return value: a dynamically allocated string

— Function: int lw6p2p_node_poll (lw6p2p_node_t * node)

> node: the node to poll

> Polls a p2p node. This must be called on a regular basis, else network communication is stalled.

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

— Function: void lw6p2p_node_close (lw6p2p_node_t * node)

> node: the node to close

> Closes a p2p node. Closing is necessary in some contexts, for instance scheme/smob instanciation when you want to release the object ressources (sockets, ports, threads...) *before* it is deleted by, for instance, a garbage collector.

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

— Function: u_int64_t lw6p2p_node_get_id (lw6p2p_node_t * node)

> node: the node to query

> Returns the node id, an id which is supposed to uniquely identify the node at run-time.

> Return value: numerical id.

— Function: lw6sys_list_t * lw6p2p_node_get_entries (lw6p2p_node_t * node)

> node: node to query

> Returns a list of all known nodes, this is a plain table dump, sorted so that the most likely to be interesting to connect oneself to are listed *last*, this is just a (little) optimization, since we know we'll need to parse this list to construct a Guile object, we reverse the order.

> Return value: list object containing `lw6p2p_entry_t` objects

— Function: int lw6p2p_test (int mode)

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

> Runs the `p2p` module test suite. This test can fail if one cannot bind on some network port, in a general manner it is dependent on the network environment, so it's better if there's some sort of human control on it.

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