libnod - Liquid War 6
Description: Liquid War 6

Next: libp2p, Previous: libnet, Up: C API

### 5.35 libnod

#### 5.35.1 Overview

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

#### 5.35.2 API

— Function: int lw6nod_info_community_add (lw6nod_info_t * info, u_int64_t id, const char * url)

> info: node info object to modify

> id: ID of the new member

> url: URL of the new member, can be NULL

> Adds a new member to the community.

> Return value: 1 if new member could be added, 0 if not.

— Function: int lw6nod_info_community_is_member (lw6nod_info_t * info, u_int64_t id, const char * url)

> info: node info object to test

> id: ID of the member we want to check

> url: URL of the member we want to check

> Tells wether a member is already in the community. Note that if there's a member with the same URL but with a different ID, or a member with the same ID but a different URL, the function will fail, we need URLs and IDs to both be different for the peer to be added. Not respecting this would lead to confusion, while sharing an ID is conceivable over the whole network, it can't be tolerated within a community. Same for the URL.

> Return value: 1 if new member could be added, 0 if not.

— Function: int lw6nod_info_community_has_id (lw6nod_info_t * info, u_int64_t id)

> info: node info object to test

> id: ID of the member we want to check

> Tells wether a member exists with this ID. Will test both ourselves and remote peers.

> Return value: 1 if ID is already taken, 0 if available.

— Function: int lw6nod_info_community_has_id_without_url (lw6nod_info_t * info, u_int64_t id)

> info: node info object to test

> id: ID of the member we want to check

> Tells wether a member exists with this ID, but for which we don't know the URL, that is, url is NULL.

> Return value: 1 if ID is already taken and has NULL url, 0 else.

— Function: int lw6nod_info_community_has_url (lw6nod_info_t * info, const char * url)

> info: node info object to test

> url: URL of the member we want to check

> Tells wether a member exists with this URL. Will test both ourselves and remote peers.

> Return value: 1 if URL is already taken, 0 if available.

— Function: int64_t lw6nod_info_community_get_id_from_url (lw6nod_info_t * info, const char * url)

> info: node info object to test

> url: URL of the member we want to check

> Returns the id of the node with this URL, if it's known to us.

> Return value: id if it's the community, else 0

— Function: char * lw6nod_info_community_get_url_from_id (lw6nod_info_t * info, int64_t id)

> info: node info object to test

> id: ID of the member we want to check

> Returns the id of the node with this URL, if it's known to us.

> Return value: url if it's the community else NULL, must be freed

— Function: int lw6nod_info_community_remove_by_id (lw6nod_info_t * info, u_int64_t id)

> info: node info object to modify

> id: ID of the member we want to remove

> Removes a community member by ID.

> Return value: 1 if successfully removed, 0 if was not present.

— Function: int lw6nod_info_community_remove_by_url (lw6nod_info_t * info, const char * url)

> info: node info object to modify

> url: URL of the member we want to remove

> Removes a community member by URL.

> Return value: 1 if successfully removed, 0 if was not present.

— Function: int lw6nod_info_community_count (lw6nod_info_t * info)

> info: node info object to modify

> Tells how many members there are in a community. This include ourselves so this can never be 0, should at least be 1. Note that this is pretty much the same as the nb_nodes member of dyn_info, but this one is calculated dynamically from peer list, while the other one is updated from time to time from game_state information.

> Return value: number of community members, including this node (us).

— Function: void lw6nod_info_community_reset (lw6nod_info_t * info)

> info: node info object to modify

> Resets all peers, set community to only one member, ourselves.

> Return value: none.

— Function: char * lw6nod_info_community_get_peer_id_list_str (lw6nod_info_t * info)

> info: node to query

> Builds a string containing all peer ids, separated by a separator.

> Return value: newly allocated string

— Function: void lw6nod_info_community_set_peer_id_list_str (lw6nod_info_t * info, const char * peer_id_list_str)

> info: node to modify

> peer_id_list_str: new value

> Interprets a peer_id_list_str and puts it into the node data structures. Note that this function won't really copy the list, instead it will populate the dyn_info struct with the right values.

> Return value: none

— Function: void lw6nod_info_community_id_without_url_map (lw6nod_info_t * info, lw6nod_id_callback_func_t func, void * func_data)

> info: node to process

> func: function to use as a callback

> func_data: data passed along with the function

> Applies function func to all the members of the community which have an id but not an URL...

> Return value: none.

— Function: void lw6nod_dyn_info_free (lw6nod_dyn_info_t * dyn_info)

> dyn_info: the dyn info struct to free

> Frees a dyn info object, to be used after a call to `lw6nod_info_dup_dyn` for instance.

> Return value: none

— Function: lw6nod_info_t * lw6nod_info_new (const char * program, const char * version, const char * codename, int stamp, u_int64_t id, const char * url, const char * title, const char * description, const char * password, int bench, int open_relay, int uptime, int idle_screenshot_size, void * idle_screenshot_data)

> program: the program (normally it's liquidwar6)

> version: the version

> codename: the codename

> stamp: the stamp

> id: the node id

> url: the node public url

> title: the node title

> description: the node description

> password: the node password

> bench: the node bench

> open_relay: open relay or not

> uptime: uptime in seconds

> idle_screenshot_size: the size (bytes) of the image to display when game is idle

> idle_screenshot_data: the data (jpeg) of the image to display when game is idle

> Creates a node info object. The arguments correspond to the immutable node attributes, other properties such as how many players are connected or set in other functions like `lw6nod_info_update` which can be called later.

> Return value: newly allocated object, NULL on error.

— Function: void lw6nod_info_free (lw6nod_info_t * info)

> info: the node info to free

> Frees a node info object.

> Return value: none

— Function: int lw6nod_info_lock (lw6nod_info_t * info)

> info: the node info to lock

> Locks a node info object, this is usefull for some members, typically list of servers, can be accessed by separated threads, one reading, many writing, and these objects (chained lists) certainly do not want to be modified while being read.

> Return value: 1 if ok, 0 if not.

— Function: int lw6nod_info_unlock (lw6nod_info_t * info)

> info: the node info to unlock

> Unlocks a node info object, this is the compation of the `lw6nod_info_lock` function.

> Return value: 1 if ok, 0 if not.

— Function: void lw6nod_info_idle (lw6nod_info_t * info)

> info: the node info to modify

> Clears a node info object and sets all its variable attributes to NULL/default values. This is what we want when the node is idle, not playing.

> Return value: none.

— Function: int lw6nod_info_update (lw6nod_info_t * info, u_int64_t community_id, int round, const 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, const char * peer_id_list, int game_screenshot_size, void * game_screenshot_data)

> info: the node info to update

> community_id: the id of the community the node belongs to

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

> level: the name of the current level (map)

> required_bench: the bench required to connect

> 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

> peer_id_list: list of peers ids, can be NULL

> game_screenshot_size: size of screenshot (bytes)

> game_screenshot_data: screenshot data (byte buffer, contains JPEG)

> Set a node info object variable attributes. Call this whenever the node has changed some parameter. Not too often for it's not needed and some operations such as modying the screenshot, can be time consuming.

> Return value: 1 if OK, 0 if error.

— Function: lw6nod_dyn_info_t * lw6nod_info_dup_dyn (lw6nod_info_t * info)

> info: the node info containing the dyn info to duplicate

> Extracts the dynamic part of an info struct and duplicates it, this is to avoid protection fault error when concurrent threads access this info.

> Return value: newly allocated object, must be freed.

— Function: lw6sys_hash_t * lw6nod_info_new_discovered_nodes ()

> Creates a new hash, to be used as a discovered nodes list. Using this function has the advantage of setting the hash options to their defaults. We use a hash to avoid having uselessly long lists containing always the same node due to multiple detections.

> Return value: an empty hash

— Function: int lw6nod_info_add_discovered_node (lw6nod_info_t * info, const char * public_url)

> info: the node info to update

> public_url: the address of the discovered node

> Registers a new server, and queues it as something that should be checked later because it's interesting. We can't insert in the database all the servers we suspect to exist so network threads should use this, then main thread will process discovered servers afterwards. This is also a good way to avoid trivial DOS attacks.

> Return value: 1 if OK, O if error.

— Function: lw6sys_list_t * lw6nod_info_pop_discovered_nodes (lw6nod_info_t * info)

> info: the node info to query

> Returns a list of all discovered nodes (their public URL) and empties the current queue as well.

> Return value: a list of dynamically allocated strings.

— Function: lw6sys_list_t * lw6nod_info_new_verified_nodes ()

> Creates a new list, to be filled with nodes and typically passed to `lw6nod_info_set_verified_nodes`. Using this function has the advantage of setting the listh options to their defaults.

> Return value: an empty list

— Function: int lw6nod_info_set_verified_nodes (lw6nod_info_t * info, lw6sys_list_t * list)

> info: the node info to modify

> list: the list of verified nodes, will be freed by this function

> Sets the list of verified nodes, that is, the list of nodes we are sure to exist, this is typically the list we will display later on a web page. We can't directly display any discovered node, one needs to filter them through main thread. Something very important about this function is that `list` will be freed by function, that is, if you call this, then you can (you should) forget your object, it will disappear any time soon.

> Return value: 1 if OK, 0 on error.

— Function: void lw6nod_info_map_verified_nodes (lw6nod_info_t * info, lw6sys_list_callback_func_t func, void * func_data)

> info: the node info concerned

> func: the function to apply

> func_data: arbitrary pointer holding data to pass to function

> Calls `lw6sys_hash_map` with `func` on every member of the list of verified nodes. The reason there's a function for this is that it is very important that list object is locked when doing this. This function does perform a lock/unlock so it is safe.

> Return value: none.

— Function: int lw6nod_test_register (int mode)

> mode: test mode (bitmask)

> Registers all tests for the libnod module.

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

— Function: int lw6nod_test_run (int mode)

> mode: test mode (bitmask)

> Runs the `nod` module test suite, testing most (if not all...) functions.

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

— Struct: lw6nod_const_info_s

> Constant informations about a node, these are informations that do not vary through the node's life, so they are set object creation then left unchanged.

— Member of lw6nod_const_info_s: program

> Type: `char *`

> Definition: `char* lw6nod_const_info_s::program`

> Program, this should be set to liquidwar6.

— Member of lw6nod_const_info_s: version

> Type: `char *`

> Definition: `char* lw6nod_const_info_s::version`

> The version of the program.

— Member of lw6nod_const_info_s: codename

> Type: `char *`

> Definition: `char* lw6nod_const_info_s::codename`

> The codename of the program.

— Member of lw6nod_const_info_s: stamp

> Type: `int`

> Definition: `int lw6nod_const_info_s::stamp`

> The stamp of the program.

— Member of lw6nod_const_info_s: ref_info

> Type: `lw6nod_ref_info_t`

> Definition: `lw6nod_ref_info_t lw6nod_const_info_s::ref_info`

> Reference information, how to uniquely identify node.

— Member of lw6nod_const_info_s: title

> Type: `char *`

> Definition: `char* lw6nod_const_info_s::title`

> The title of the node, its readable short name.

— Member of lw6nod_const_info_s: description

> Type: `char *`

> Definition: `char* lw6nod_const_info_s::description`

> More details about the node.

— Member of lw6nod_const_info_s: has_password

> Type: `int`

> Definition: `int lw6nod_const_info_s::has_password`

> Wether the node is password protected or not.

— Member of lw6nod_const_info_s: password

> Type: `char *`

> Definition: `char* lw6nod_const_info_s::password`

> The password used, cleartext.

— Member of lw6nod_const_info_s: bench

> Type: `int`

> Definition: `int lw6nod_const_info_s::bench`

> The node bench.

— Member of lw6nod_const_info_s: open_relay

> Type: `int`

> Definition: `int lw6nod_const_info_s::open_relay`

> Wether the node acts as an open relay or not.

— Member of lw6nod_const_info_s: creation_timestamp

> Type: `int64_t`

> Definition: `int64_t lw6nod_const_info_s::creation_timestamp`

> The node creation timestamp.

— Member of lw6nod_const_info_s: idle_screenshot_size

> Type: `int`

> Definition: `int lw6nod_const_info_s::idle_screenshot_size`

> Size of the screenshot (in bytes) when in idle mode.

— Member of lw6nod_const_info_s: idle_screenshot_data

> Type: `void *`

> Definition: `void* lw6nod_const_info_s::idle_screenshot_data`

> Idle mode screenshot data. This is just a plain JPEG buffer, which will be used as a fallback if there's no real screenshot available.

— Struct: lw6nod_dyn_info_s

> Dynamic informations about a node, these are informations that vary through the node's life, so they are unset at object creation and can then be updated from game context.

— Member of lw6nod_dyn_info_s: community_id_int

> Type: `u_int64_t`

> Definition: `u_int64_t lw6nod_dyn_info_s::community_id_int`

> The ID of the community this node belongs to, as a 64-bit unsigned integer.

— Member of lw6nod_dyn_info_s: community_id_str

> Type: `char *`

> Definition: `char* lw6nod_dyn_info_s::community_id_str`

> The ID of the community this node belongs to, as a string (64-bit integer converted to hexa).

— Member of lw6nod_dyn_info_s: community_peers

> Type: `lw6nod_ref_info_t`

> Definition: `lw6nod_ref_info_t lw6nod_dyn_info_s::community_peers[LW6NOD_MAX_NB_PEERS]`

> The list of community members, you need to refer to the nb_nodes member to know quickly how many members they are but actually, in practice, there can be holes in this array, you need to check each slot, for instance 0 can be filled, 2 can be filled too, but 1 be empty. Note that we don't count ourselves in this list.

— Member of lw6nod_dyn_info_s: round

> Type: `int`

> Definition: `int lw6nod_dyn_info_s::round`

> The current round.

— Member of lw6nod_dyn_info_s: level

> Type: `char *`

> Definition: `char* lw6nod_dyn_info_s::level`

> The current level.

— Member of lw6nod_dyn_info_s: required_bench

> Type: `int`

> Definition: `int lw6nod_dyn_info_s::required_bench`

> The required bench to connect to this node.

— Member of lw6nod_dyn_info_s: nb_colors

> Type: `int`

> Definition: `int lw6nod_dyn_info_s::nb_colors`

> Number of colors playing.

— Member of lw6nod_dyn_info_s: max_nb_colors

> Type: `int`

> Definition: `int lw6nod_dyn_info_s::max_nb_colors`

> Maximum number of colors allowed to play.

— Member of lw6nod_dyn_info_s: nb_cursors

> Type: `int`

> Definition: `int lw6nod_dyn_info_s::nb_cursors`

> Number of cursors playing.

— Member of lw6nod_dyn_info_s: max_nb_cursors

> Type: `int`

> Definition: `int lw6nod_dyn_info_s::max_nb_cursors`

> Maximum number of cursors allowed to play.

— Member of lw6nod_dyn_info_s: nb_nodes

> Type: `int`

> Definition: `int lw6nod_dyn_info_s::nb_nodes`

> Number of nodes playing.

— Member of lw6nod_dyn_info_s: max_nb_nodes

> Type: `int`

> Definition: `int lw6nod_dyn_info_s::max_nb_nodes`

> Maximum number of nodes allowed to play.

— Member of lw6nod_dyn_info_s: game_screenshot_size

> Type: `int`

> Definition: `int lw6nod_dyn_info_s::game_screenshot_size`

> Size of the screenshot, in bytes.

— Member of lw6nod_dyn_info_s: game_screenshot_data

> Type: `void *`

> Definition: `void* lw6nod_dyn_info_s::game_screenshot_data`

> Game screenshot data. This is just a plain JPEG buffer, which will be served when peers and/or web clients want to gather informations about the game. This can be NULL, in that the fallback constant data will be used.

— Struct: lw6nod_info_s

> Informations about a node. Note that in practice this structure is just used to describe our current node, there might be several instances of this if a program instanciates several nodes, but another data structure is used to store information about peers.typedef struct lw6nod_info_s

— Member of lw6nod_info_s: mutex

> Type: `lw6sys_mutex_t *`

> Definition: `lw6sys_mutex_t* lw6nod_info_s::mutex`

> Mutex used to access dynamic informations.

— Member of lw6nod_info_s: const_info

> Type: `lw6nod_const_info_t`

> Definition: `lw6nod_const_info_t lw6nod_info_s::const_info`

> Constant informations, never changes.

— Member of lw6nod_info_s: dyn_info

> Type: `lw6nod_dyn_info_t`

> Definition: `lw6nod_dyn_info_t lw6nod_info_s::dyn_info`

> Dynamic informations, can be updated. Do not modify this directly, instead use appropriate functions which will use mutexes properly.

— Member of lw6nod_info_s: discovered_nodes

> Type: `lw6sys_hash_t *`

> Definition: `lw6sys_hash_t* lw6nod_info_s::discovered_nodes`

> List of discovered nodes, do not access this directly, instead use proper query functions which, in turn, will use mutexes properly.

— Member of lw6nod_info_s: verified_nodes

> Type: `lw6sys_list_t *`

> Definition: `lw6sys_list_t* lw6nod_info_s::verified_nodes`

> List of verified nodes, do not access this directly, instead use proper query functions which, in turn, will use mutexes properly.

— Struct: lw6nod_ref_info_s

> Reference information about a node, this is all you need to uniquely identify a node. In theory, only the ID are only the URL are enough, in practice it's not that bad to have some redundancy, plus it makes it easier and faster to connect to them and transmit informations.

— Member of lw6nod_ref_info_s: id_int

> Type: `u_int64_t`

> Definition: `u_int64_t lw6nod_ref_info_s::id_int`

> The id of the node, as an integer (64-bit unsigned).

— Member of lw6nod_ref_info_s: id_str

> Type: `char *`

> Definition: `char* lw6nod_ref_info_s::id_str`

> The id of the node, as a string (64-bit converted to hexa).

— Member of lw6nod_ref_info_s: url

> Type: `char *`

> Definition: `char* lw6nod_ref_info_s::url`

> The public URL of the node.