node.h File Reference

API for running a DHT node. More...

#include <stdint.h>
#include <sys/socket.h>
#include "bencode.h"

Include dependency graph for node.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	search_node
	Search node. More...
struct	ip_counter_entry
	External IP counter entry. More...
struct	ip_counter
	External IP counter. More...
struct	dht_node
	DHT node object. More...

Typedefs
typedef void(*	search_complete_t) (struct dht_node *n, const struct search_node *nodes, void *opaque)
	Search complete callback. More...
typedef void(*	node_output_t) (const unsigned char *data, size_t len, const struct sockaddr *dest, socklen_t addrlen, void *opaque)
	Node output callback. More...
typedef void(*	bootstrap_status_t) (int ready, void *opaque)
	Bootstrap status notification callback. More...
typedef struct search *	dht_search_t
	Search handle. More...

Enumerations
enum	dht_search_type { FIND_NODE, GET_PEERS, GET }
	Type of DHT search.

Functions
int	dht_node_init (struct dht_node *n, const unsigned char *id, node_output_t output, void *opaque)
	Initialize DHT node. More...
int	dht_node_start (struct dht_node *n)
	Start DHT node. More...
void	dht_node_input (struct dht_node *n, const unsigned char *data, size_t len, const struct sockaddr *src, socklen_t addrlen)
	Input a received UDP datagram. More...
void	dht_node_ping (struct dht_node *n, struct sockaddr *dest, socklen_t addrlen)
	Ping remote node. More...
void	dht_node_timeout (struct dht_node *n, struct timeval *tv)
	Get node timeout. More...
void	dht_node_work (struct dht_node *n)
	Service the node. More...
void	dht_node_cleanup (struct dht_node *n)
	Cleanup DHT node. More...
int	dht_node_search (struct dht_node *n, const unsigned char id[20], int search_type, search_complete_t callback, void *opaque, dht_search_t *handle)
	Start a search on the DHT. More...
void	dht_node_cancel (struct dht_node *n, dht_search_t handle)
	Cancel a pending DHT search. More...
void	dht_node_dump_buckets (struct dht_node *n)
	Dump the node's routing table. More...
void	dht_node_announce (struct dht_node *n, const unsigned char *info_hash, const struct search_node *nodes, int implied_port, int port)
	Send announce queries for an infohash. More...
void	dht_node_put_immutable (struct dht_node *n, const struct search_node *nodes, const struct bvalue *val)
	Store immutable data in the DHT. More...
void	dht_node_put_mutable (struct dht_node *n, const struct search_node *nodes, const unsigned char k[32], const unsigned char signature[64], const unsigned char *salt, size_t salt_len, int seq, const struct bvalue *val)
	Store mutable data in the DHT. More...
struct bvalue *	dht_node_save (const struct dht_node *n)
	Save node state. More...
int	dht_node_restore (const struct bvalue *dict, struct dht_node *n)
	Restore node state. More...
void	dht_node_set_bootstrap_callback (struct dht_node *n, bootstrap_status_t callback, void *opaque)
	Set bootstrap status notification callback. More...

Detailed Description

API for running a DHT node.

This file defines low-level methods for a dht_node object.

Typedef Documentation

typedef void(* bootstrap_status_t) (int ready, void *opaque)

Bootstrap status notification callback.

User-defined callback called when the node boostrap status changes. When ready is non-zero, the node is ready to handle new DHT searches. When ready is zero, the node is bootstraping.

Parameters

ready	Whether the node is ready.
opaque	User data pointer passed to dht_node_set_bootstrap_callback.

typedef struct search* dht_search_t

Search handle.

Handle to a pending DHT search.

typedef void(* node_output_t) (const unsigned char *data, size_t len, const struct sockaddr *dest, socklen_t addrlen, void *opaque)

Node output callback.

User-defined callback for sending UDP datagrams to a remote node.

Parameters

data	Pointer to the data buffer to send.
len	Length of the data buffer to send.
dest	Destination address
addrlen	Length of the dest parameter.
opaque	User data pointer passed to dht_node_init.

typedef void(* search_complete_t) (struct dht_node *n, const struct search_node *nodes, void *opaque)

Search complete callback.

This callback is called when a DHT search completes.

Parameters

n	The node handling the search.
nodes	Linked list of nodes found during the search. Sorted by increasing distance. If NULL, the search either returned no nodes or was cancelled.
opaque	User data pointer passed to dht_node_search.

Function Documentation

void dht_node_announce	(	struct dht_node *	n,
		const unsigned char *	info_hash,
		const struct search_node *	nodes,
		int	implied_port,
		int	port
	)

Send announce queries for an infohash.

Sends DHT announce queries for the given infohash. If implied_port is non-zero, them the port parameter will be ignored and the node's UDP port is used instead as the peer port. This function is only meant to be used with a list of nodes obtained as the result of a GET_PEERS search. Only the 8 nodes of the nodes list will be subject to the announce query. See dht_announce_peer for a higher level interface.

Parameters

n	The DHT node.
info_hash	the 160-bit infohash.
nodes	List of nodes sorted by increasing distance to the target infohash, as returned by dht_node_search.
implied_port	0 to use the port parameter, 1 to use the current node's UDP port number.
port	Announced peer's port number if implied_port is 0, ignored otherwise.

void dht_node_cancel	(	struct dht_node *	n,
		dht_search_t	handle
	)

Cancel a pending DHT search.

Cancels a currently running search and frees up associated ressources. The search completion callback will be called immediately with a NULL list of nodes.

Parameters

n	The DHT node.
handle	Handle to the search to cancel.

void dht_node_cleanup

(

struct dht_node *

n

)

Cleanup DHT node.

Cleans up the dht_node and frees all ressources used by the node. All the pending searches will be cancelled.

Parameters

n	The DHT node.

void dht_node_dump_buckets

(

struct dht_node *

n

)

Dump the node's routing table.

Outputs the node's bucket list for debugging purpose.

Parameters

n	The DHT node.

int dht_node_init	(	struct dht_node *	n,
		const unsigned char *	id,
		node_output_t	output,
		void *	opaque
	)

Initialize DHT node.

Initializes a dht_node structure with the given node ID id. If the id parameter is NULL, the node ID will be generated randomly. To remain platform independent, the library does not handle network operations by itself, therefore the user needs to provide output, a callback that takes care of sending UDP datagrams over the network. A very basic implementation of output could be:

static void output(const unsigned char *data, size_t len,
                   const struct sockaddr *dest, socklen_t addrlen,
                   void *opaque)
{
    sendto(*(int *)opaque, data, len, 0, dest, addrlen);
}

Parameters

n	Empty node structure to initialize.
id	Node identifier to use.
output	Datagram output callback.
opaque	Opaque pointer that will be passed to the output callback.

Returns

0 on success or -1 on allocation error.

void dht_node_input	(	struct dht_node *	n,
		const unsigned char *	data,
		size_t	len,
		const struct sockaddr *	src,
		socklen_t	addrlen
	)

Input a received UDP datagram.

This function must be called upon reception of a UDP datagram for the node. Note that his function may bring the node timeout forward. (see dht_node_timeout).

Parameters

n	The DHT node.
data	Data received.
len	Length of received data.
src	Sender address.
addrlen	Length of the src parameter.

void dht_node_ping	(	struct dht_node *	n,
		struct sockaddr *	dest,
		socklen_t	addrlen
	)

Ping remote node.

Sends a ping query to the specified host. Querying a node known by address will help speed-up the bootstrap process: if the remote hosts responds, it will immediately be added to the routing table and will be used in subsequent DHT searches.

Parameters

n	The DHT node.
dest	Address of the DHT node to ping.
addrlen	Length of the dest parameter.

void dht_node_put_immutable	(	struct dht_node *	n,
		const struct search_node *	nodes,
		const struct bvalue *	val
	)

Store immutable data in the DHT.

Send a "put" query to the specified nodes with the given value val to store as immutable data. Only the 8 first nodes of the nodes list will be subject to the announce query. See dht_put_immutable for a higher level interface.

Parameters

n	The DHT node.
nodes	List of nodes sorted by increasing distance to the target hash, as returned by dht_node_search.
val	Value to be stored on the target nodes.

void dht_node_put_mutable	(	struct dht_node *	n,
		const struct search_node *	nodes,
		const unsigned char	k[32],
		const unsigned char	signature[64],
		const unsigned char *	salt,
		size_t	salt_len,
		int	seq,
		const struct bvalue *	val
	)

Store mutable data in the DHT.

Send a "put" query to the specified nodes with the given value val to store as mutable data. Only the 8 first nodes of the nodes list will be subject to the put query. See dht_put_mutable for a higher level interface.

Parameters

n	The DHT node.
nodes	List of nodes sorted by increasing distance to the target hash, as returned by dht_node_search.
k	ed25519 public key used to authenticate the query.
signature	ed25519 signature of the query.
salt	Salt data added to compute the target hash.
salt_len	Length of the salt data (max=64).
seq	Sequence number.
val	Value to be stored on the target nodes.

int dht_node_restore	(	const struct bvalue *	dict,
		struct dht_node *	n
	)

Restore node state.

Restores the node to a previous state. The result of calling this function after the node has already started with dht_node_start is undefined.

Parameters

dict	The state to restore as a dictionary value.
n	The DHT node.

Returns

0 on success or -1 if dict is invalid (invalid version).

struct bvalue* dht_node_save

(

const struct dht_node *

n

)

Save node state.

Saves the state of a node into a dictionnary value ready to be serialized to a file. This function saves the node ID an the content of the node's routing table. This allows the node to be stopped and then restarted in a future invocation of the same software without having to go through the bootstrap process again.

Parameters

n	The DHT node.

Returns

The node's state as a dictionary value.

int dht_node_search	(	struct dht_node *	n,
		const unsigned char	id[20],
		int	search_type,
		search_complete_t	callback,
		void *	opaque,
		dht_search_t *	handle
	)

Start a search on the DHT.

Start a recursive search on the DHT. There are multiple types of search (FIND_NODE, GET_PEERS and GET), each using a different query method (respectively find_node, get_peers, and get), but the search algorithm remains the same in all cases. The returned search handle can be used to cancel a pending search with dht_node_cancel. The search completes when no nodes can be found closer to the target ID, the search_complete_t callback will then be called with a list of all the nodes found during the search. This is a low-level interface, consider using functions in peers.h or put.h instead. The returned search handle becomes invalid after the search completes.

Parameters

n	The DHT node.
search_type	Type of search. One of the dht_search_type enum values.
id	The search target.
callback	Function that will be called when the search completes.
opaque	Opaque pointer that will be passed to the callback when the search completes.
handle	Pointer to a variable that will receive the search handle.

Returns

0 if the search sucessfully started, or -1 in case of failure.

void dht_node_set_bootstrap_callback	(	struct dht_node *	n,
		bootstrap_status_t	callback,
		void *	opaque
	)

Set bootstrap status notification callback.

Register a callback that will be called when the node's bootstrap status changes. It allows the user to be notified when the node is ready to issue DHT searches.

Parameters

n	The DHT node.
callback	Bootstrap status callback.
opaque	Opaque pointer that will be passed to the callback.

Returns

bootstrap status.

int dht_node_start

(

struct dht_node *

n

)

Start DHT node.

Starts servicing the DHT node. Bootstrap node if the routing table is empty. Changing the node's ID or restoring a previous state must be done before calling this function.

Parameters

n	The node to start.

void dht_node_timeout	(	struct dht_node *	n,
		struct timeval *	tv
	)

Get node timeout.

Returns the amount of time after which the node needs to be serviced (by calling dht_node_work).

Parameters

n	The DHT node.
tv	A pointer to a timeval structure in which the timeout value will be returned.

void dht_node_work

(

struct dht_node *

n

)

Service the node.

The user is required to call this function every so often to perform maintenance work (routing table updates) on the node or make progress on pending searches. It is recommended to call this function every second or use dht_node_timeout to figure out when to call.

Parameters

n	The DHT node.