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


5.36 libp2p

5.36.1 Overview

View lcov test coverage results on http://www.ufoot.org/liquidwar/v6/doc/coverage/src/lib/p2p/index.html.

5.36.2 API

Function: lw6p2p_db_t * lw6p2p_db_open (lw6sys_context_t * sys_context, int argc, const char * [] argv, const char * name)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6p2p_db_t * db)

sys_context: global system context

db: the db to close

Closes a db object, memory ressources will be freed.

Return value: none.

Function: char * lw6p2p_db_repr (lw6sys_context_t * sys_context, const lw6p2p_db_t * db)

sys_context: global system context

db: the db to work on

Gives a readable representation of the db

Return value: a dynamically allocated string

Function: int lw6p2p_db_reset (lw6sys_context_t * sys_context, int argc, const char * [] argv, const char * name)

sys_context: global system context

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 (lw6sys_context_t * sys_context)

sys_context: global system context

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_timestamp (lw6sys_context_t * sys_context, _lw6p2p_db_t * db, int64_t timestamp)

sys_context: global system context

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

timestamp: the timestamp as returned by lw6sys_get_timestamp

Returns a timestamp suitable for db usage (seconds since object creation), set to the timestamp passed as an argument (milliseconds). 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: int _lw6p2p_db_now (lw6sys_context_t * sys_context, _lw6p2p_db_t * db)

sys_context: global system context

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

Returns a timestamp suitable for db usage, (seconds since object creation) set to the current moment. 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 (lw6sys_context_t * sys_context, 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)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6p2p_entry_t * entry)

sys_context: global system context

entry: entry to free

Frees a p2p entry.

Return value: none.

Function: char * lw6p2p_entry_repr (lw6sys_context_t * sys_context, const lw6p2p_entry_t * entry)

sys_context: global system context

entry: entry to represent

Gives a human-readable representation of the entry

Return value: dynamically allocated string

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

sys_context: global system context

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

node_id: the node id

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 (lw6sys_context_t * sys_context, lw6p2p_node_t * node)

sys_context: global system context

node: the node to free

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

Return value: none.

Function: char * lw6p2p_node_repr (lw6sys_context_t * sys_context, const lw6p2p_node_t * node)

sys_context: global system context

node: the node to work on

Gives a readable representation of the node

Return value: a dynamically allocated string

Function: int lw6p2p_node_poll (lw6sys_context_t * sys_context, lw6p2p_node_t * node, lw6sys_progress_t * progress)

sys_context: global system context

node: the node to poll

progress: progress indicator to show the advancement

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 (lw6sys_context_t * sys_context, lw6p2p_node_t * node)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6p2p_node_t * node)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6p2p_node_t * node, int skip_local)

sys_context: global system context

node: node to query

skip_local: wether to skip local node, 1 to skip, 0 to keep

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_node_server_start (lw6sys_context_t * sys_context, lw6p2p_node_t * node, int64_t seq_0)

sys_context: global system context

node: node to start

seq_0: seq when starting the server

Starts a node in server mode, if node was previously connected to other nodes, disconnect it from any peer.

Return value: 1 on success, 0 on failure.

Function: int lw6p2p_node_client_join (lw6sys_context_t * sys_context, lw6p2p_node_t * node, u_int64_t remote_id, const char * remote_url, lw6sys_progress_t * progress)

sys_context: global system context

node: node to use

remote_id: id of remote node to join

remote_url: url of remote node to join

progress: progress indicator to show end-user the advancement of process

Starts a node in client mode, joins the given node, if node was previously connected to other nodes, disconnect it from any peer.

Return value: 1 on success, 0 on failure.

Function: int lw6p2p_node_refresh_peer (lw6sys_context_t * sys_context, lw6p2p_node_t * node, u_int64_t remote_id, const char * remote_url)

sys_context: global system context

node: node to use

remote_id: id of remote node to refresh

remote_url: url of remote node to refresh

Forces a refresh of a remote node, that is, try and get more up-to-date informations from it, not waiting for the standard update schedule.

Return value: 1 on success, 0 on failure.

Function: void lw6p2p_node_disconnect (lw6sys_context_t * sys_context, lw6p2p_node_t * node)

sys_context: global system context

node: node to disconnect

Disconnects a node, if node was previously connected to other nodes, disconnect it from any peer. Note that this does not affect out-of-band connections, only real game-related links.

Return value: 1 on success, 0 on failure.

Function: int lw6p2p_node_update_info (lw6sys_context_t * sys_context, lw6p2p_node_t * node, int round, const char * level, int nb_colors, int max_nb_colors, int nb_cursors, int max_nb_cursors, int nb_nodes, int max_nb_nodes, int game_screenshot_size, void * game_screenshot_data)

sys_context: global system context

node: node to update

round: the current round (can have an offset with real round number)

level: the name of the current level (map)

nb_colors: number of colors playing

max_nb_colors: max number of colors allowed

nb_cursors: number of cursors playing

max_nb_cursors: max number of cursors allowed

nb_nodes: number of nodes playing

max_nb_nodes: max number of nodes allowed

game_screenshot_size: size of screenshot (bytes)

game_screenshot_data: screenshot data (byte buffer, contains JPEG)

Updates node info, that is, all the data/metadata which can be displayed to other peers and are, by nature, dynamic.

Return value: 1 on success, 0 on failure.

Function: void lw6p2p_node_calibrate (lw6sys_context_t * sys_context, lw6p2p_node_t * node, int64_t timestamp, int64_t seq)

sys_context: global system context

node: the object to calibrate

timestamp: the current ticks setting (1000 ticks per second)

seq: the round expected to be returned with this ticks value

Calibrates the node, so that sequence numbering is consistent accross nodes.

Return value: none.

Function: int64_t lw6p2p_node_get_local_seq_0 (lw6sys_context_t * sys_context, lw6p2p_node_t * node)

sys_context: global system context

node: the object to query

Gets the reference local seq_0 for this node, the information is taken from the warehouse, even if node->calibrate_seq should probably return the same value.

Return value: the seq.

Function: int64_t lw6p2p_node_get_local_seq_last (lw6sys_context_t * sys_context, lw6p2p_node_t * node)

sys_context: global system context

node: the object to query

Gets the local seq_last for this node, the information is taken from the warehouse, which has parsed the messages and this information can in return be used to avoid maintaining outside of the node the information about what was the last seq used for a local message.

Return value: the seq.

Function: int64_t lw6p2p_node_get_seq_min (lw6sys_context_t * sys_context, lw6p2p_node_t * node)

sys_context: global system context

node: the object to query

Gets the minimum seq registered, not of utmost importance but interesting for debugging purpose, to check what’s in the warehouse.

Return value: the seq.

Function: int64_t lw6p2p_node_get_seq_max (lw6sys_context_t * sys_context, lw6p2p_node_t * node)

sys_context: global system context

node: the object to query

Gets the maximum seq registered, this is typically used for guessing which seq might make sense for this node, but in a real example one should rely on algorithm/ker-side kept values.

Return value: the seq.

Function: int64_t lw6p2p_node_get_seq_draft (lw6sys_context_t * sys_context, lw6p2p_node_t * node)

sys_context: global system context

node: the object to query

Gets the seq of the current draft as the warehouse understands it. Note that it’s the responsibility of the caller to update the pilot according to this, this information is just about what is in the warehouse, not necessarly what is in the pilot / game_state.

Return value: the seq.

Function: int64_t lw6p2p_node_get_seq_reference (lw6sys_context_t * sys_context, lw6p2p_node_t * node)

sys_context: global system context

node: the object to query

Gets the seq of the current reference as the warehouse understands it. Note that it’s the responsibility of the caller to update the pilot according to this, this information is just about what is in the warehouse, not necessarly what is in the pilot / game_state.

Return value: the seq.

Function: int lw6p2p_node_is_peer_connected (lw6sys_context_t * sys_context, lw6p2p_node_t * node, u_int64_t peer_id)

sys_context: global system context

node: the object to query

peer_id: id of the peer we want to check

Tests wether the node is connected to us. This is a different question from being registered, being connected means there’s a tentacle connected to the peer, but it does not necessarly means this peer actively takes part in the game.

Return value: 1 if connected, 0 if not.

Function: int lw6p2p_node_is_peer_registered (lw6sys_context_t * sys_context, lw6p2p_node_t * node, u_int64_t peer_id)

sys_context: global system context

node: the object to query

peer_id: id of the peer we want to check

Tests wether the node is registered within the warehouse. This is a different question from being connected, being registered means we received a message (possibly from another peer) that means "this peer is part of the game" regardless of the fact it’s connected or not. Returns true if test is performed with the local id.

Return value: 1 if registered, 0 if not.

Function: int lw6p2p_node_is_seed_needed (lw6sys_context_t * sys_context, lw6p2p_node_t * node)

sys_context: global system context

node: node to query

Returns true (1) if the local node needs to send a SEED message. A SEED message will basically be sent at the beginning of a session when a client connects to a server. Basically this message is of no use but it’s interesting to have a short message (not DUMP) to start with.

Return value: 1 if SEED must be sent.

Function: int lw6p2p_node_is_dump_needed (lw6sys_context_t * sys_context, lw6p2p_node_t * node)

sys_context: global system context

node: node to query

Returns true (1) if the local node needs to send a DUMP message. A DUMP message will basically reset level, game struct, game state, it’s typically sent when a new player is connected. This function will return true once then always 0 so one should really act and do something whenever it’s called and returns 1.

Return value: 1 if DUMP must be sent.

Function: int lw6p2p_node_put_local_msg (lw6sys_context_t * sys_context, lw6p2p_node_t * node, const char * msg)

sys_context: global system context

node: node 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: char * lw6p2p_node_get_next_reference_msg (lw6sys_context_t * sys_context, lw6p2p_node_t * node, lw6sys_progress_t * progress)

sys_context: global system context

node: node to query

progress: progress indicator (read/write)

Get the next waiting reference msg. This is used to maintain the stable reference game state we can rely upon. One is supposed to call this until it returns NULL, then switch draft messages.

Return value: newly allocated string, must be freed.

Function: char * lw6p2p_node_get_next_draft_msg (lw6sys_context_t * sys_context, lw6p2p_node_t * node, lw6sys_progress_t * progress)

sys_context: global system context

node: node to query

progress: progress indicator (read/write)

Get the next waiting draft msg. This is used to maintain the anticipated draft game state we use for drawing. One is supposed to call this after all reference messages have been treated.

Return value: newly allocated string, must be freed.

Function: int lw6p2p_test_register (lw6sys_context_t * sys_context, int mode)

sys_context: global system context

mode: test mode (bitmask)

Registers all tests for the libp2p module.

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

Function: int lw6p2p_test_run (lw6sys_context_t * sys_context, int mode)

sys_context: global system context

mode: test mode (bitmask)

Runs the p2p module test suite, testing most (if not all...) functions.

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

Struct: lw6p2p_db_s

Handler on a database connection, this must be used to pass order to store/retrieve persistent informations about peers.

Member of lw6p2p_db_s: id

Type: u_int32_t

Definition: u_int32_t lw6p2p_db_s::id

The first member, id, is the same as the internal _lw6p2p_db_t structure. The rest of it is hidden. The program will cast from lw6p2p_db_t to _lw6p2p_db_t internally.

Struct: lw6p2p_entry_s

This entry object matches as close as possible the corresponding (node) entry in the database.

Member of lw6p2p_entry_s: creation_timestamp

Type: int

Definition: int lw6p2p_entry_s::creation_timestamp

Node creation timestamp.

Member of lw6p2p_entry_s: version

Type: char

Definition: char lw6p2p_entry_s::version[LW6P2P_VERSION_SIZE+1]

Node version.

Member of lw6p2p_entry_s: codename

Type: char

Definition: char lw6p2p_entry_s::codename[LW6P2P_CODENAME_SIZE+1]

Node codename.

Member of lw6p2p_entry_s: stamp

Type: int

Definition: int lw6p2p_entry_s::stamp

Node stamp.

Member of lw6p2p_entry_s: id

Type: char

Definition: char lw6p2p_entry_s::id[LW6P2P_ID_SIZE+1]

Node id, 64-bit integer as an hexa string.

Member of lw6p2p_entry_s: url

Type: char

Definition: char lw6p2p_entry_s::url[LW6P2P_URL_SIZE+1]

Node URL, the public URL it displays to others.

Member of lw6p2p_entry_s: title

Type: char

Definition: char lw6p2p_entry_s::title[LW6P2P_TITLE_SIZE+1]

Node title, the short readable name for the node.

Member of lw6p2p_entry_s: description

Type: char

Definition: char lw6p2p_entry_s::description[LW6P2P_DESCRIPTION_SIZE+1]

Node description, mode details about this node.

Member of lw6p2p_entry_s: has_password

Type: int

Definition: int lw6p2p_entry_s::has_password

Wether it requires a password or not.

Member of lw6p2p_entry_s: bench

Type: int

Definition: int lw6p2p_entry_s::bench

Node bench, reflects how powerfull it is.

Member of lw6p2p_entry_s: open_relay

Type: int

Definition: int lw6p2p_entry_s::open_relay

Wether this node acts as an open relay or not.

Member of lw6p2p_entry_s: community_id

Type: char

Definition: char lw6p2p_entry_s::community_id[LW6P2P_COMMUNITY_ID_SIZE+1]

Community id, 64-bit integer as an hexa string.

Member of lw6p2p_entry_s: round

Type: int

Definition: int lw6p2p_entry_s::round

Current round.

Member of lw6p2p_entry_s: level

Type: char

Definition: char lw6p2p_entry_s::level[LW6P2P_LEVEL_SIZE+1]

Level used.

Member of lw6p2p_entry_s: required_bench

Type: int

Definition: int lw6p2p_entry_s::required_bench

Required bench to connect to this community.

Member of lw6p2p_entry_s: nb_colors

Type: int

Definition: int lw6p2p_entry_s::nb_colors

Number of colors playing.

Member of lw6p2p_entry_s: max_nb_colors

Type: int

Definition: int lw6p2p_entry_s::max_nb_colors

Maximum number of colors allowed to play.

Member of lw6p2p_entry_s: nb_cursors

Type: int

Definition: int lw6p2p_entry_s::nb_cursors

Number of cursors playing.

Member of lw6p2p_entry_s: max_nb_cursors

Type: int

Definition: int lw6p2p_entry_s::max_nb_cursors

Maximum number of cursors allowed to play.

Member of lw6p2p_entry_s: nb_nodes

Type: int

Definition: int lw6p2p_entry_s::nb_nodes

Number of nodes playing.

Member of lw6p2p_entry_s: max_nb_nodes

Type: int

Definition: int lw6p2p_entry_s::max_nb_nodes

Maximum number of nodes playing.

Member of lw6p2p_entry_s: ip

Type: char

Definition: char lw6p2p_entry_s::ip[LW6P2P_IP_SIZE+1]

IP addess of node.

Member of lw6p2p_entry_s: port

Type: int

Definition: int lw6p2p_entry_s::port

IP port of node.

Member of lw6p2p_entry_s: last_ping_timestamp

Type: int

Definition: int lw6p2p_entry_s::last_ping_timestamp

Last time this node has been pinged.

Member of lw6p2p_entry_s: ping_delay_msec

Type: int

Definition: int lw6p2p_entry_s::ping_delay_msec

Ping delay, in milliseconds.

Member of lw6p2p_entry_s: available

Type: int

Definition: int lw6p2p_entry_s::available

Wether this node is ready to accept connections.

Struct: lw6p2p_node_s

Node object, the main network object, this one will encaspulate everything else, the node can connect to other peers, listen on the network, it’s the high-level interface.

Member of lw6p2p_node_s: id

Type: u_int32_t

Definition: u_int32_t lw6p2p_node_s::id

The first member, id, is the same as the internal _lw6p2p_node_t structure. The rest of it is hidden. The program will cast from lw6p2p_node_t to _lw6p2p_node_t internally.


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