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

### 5.27 libnod

#### 5.27.1 Overview

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

#### 5.27.2 API

— 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 (char * program, char * version, char * codename, int stamp, u_int64_t id, char * url, char * title, char * description, 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, 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, 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

> 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, 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 (int mode)

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

> Runs the `nod` module test suite.

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