Data Structures
struct	lws_dht_hash

struct	lws_dht_info

Macros
#define	DHT_MAX_PEERS 2048

#define	DHT_MAX_HASHES 16384

#define	DHT_MAX_SEARCHES 1024

#define	DHT_SEARCH_EXPIRE_TIME (62 * 60)

Typedefs
typedef struct lws_dht_hash	lws_dht_hash_t

typedef void	lws_dht_callback_t(void closure, int event, const lws_dht_hash_t info_hash, const void *data, size_t data_len)

typedef int	lws_dht_blacklist_cb_t(const struct sockaddr *sa, size_t salen)

typedef void	lws_dht_hash_cb_t(void hash_return, int hash_size, const void v1, int len1, const void v2, int len2, const void v3, int len3)

typedef void	lws_dht_capture_announce_cb_t(struct lws_dht_ctx ctx, lws_dht_hash_t hash, const struct sockaddr *fromaddr, unsigned short prt)

typedef struct lws_dht_info	lws_dht_info_t

Enumerations
enum	{ LWS_DHT_HASH_TYPE_UNKNOWN = 0 , LWS_DHT_HASH_TYPE_SHA1 = 0x11 , LWS_DHT_HASH_TYPE_SHA256 = 0x12 , LWS_DHT_HASH_TYPE_SHA512 = 0x13 , LWS_DHT_HASH_TYPE_BLAKE3 = 0x1e }

enum	lws_dht_event_t { LWS_DHT_EVENT_NONE , LWS_DHT_EVENT_VALUES , LWS_DHT_EVENT_VALUES6 , LWS_DHT_EVENT_SEARCH_DONE , LWS_DHT_EVENT_SEARCH_DONE6 , LWS_DHT_EVENT_EXTERNAL_ADDR , LWS_DHT_EVENT_EXTERNAL_ADDR6 }

Functions
LWS_VISIBLE LWS_EXTERN lws_dht_hash_t *	lws_dht_hash_create (int type, int len, const uint8_t *data)

LWS_VISIBLE LWS_EXTERN void	lws_dht_hash_destroy (lws_dht_hash_t **p)

LWS_VISIBLE LWS_EXTERN struct lws_dht_ctx *	lws_dht_create (const lws_dht_info_t *info)

LWS_VISIBLE LWS_EXTERN void	lws_dht_destroy (struct lws_dht_ctx **pctx)

LWS_VISIBLE LWS_EXTERN int	lws_dht_insert_node (struct lws_dht_ctx ctx, const lws_dht_hash_t id, struct sockaddr *sa, size_t salen)

LWS_VISIBLE LWS_EXTERN int	lws_dht_ping_node (struct lws_dht_ctx ctx, struct sockaddr sa, size_t salen)

LWS_VISIBLE LWS_EXTERN int	lws_dht_search (struct lws_dht_ctx ctx, const lws_dht_hash_t id, int port, int af, lws_dht_callback_t callback, void closure)

LWS_VISIBLE LWS_EXTERN int	lws_dht_nodes (struct lws_dht_ctx ctx, int af, int good_return, int dubious_return, int cached_return, int *incoming_return)

LWS_VISIBLE LWS_EXTERN void	lws_dht_dump_tables (struct lws_dht_ctx *ctx)

LWS_VISIBLE LWS_EXTERN int	lws_dht_get_nodes (struct lws_dht_ctx ctx, struct sockaddr_in sin, int num, struct sockaddr_in6 sin6, int *num6)

LWS_VISIBLE LWS_EXTERN int	lws_dht_get_external_addr (struct lws_dht_ctx ctx, struct sockaddr_storage ss, size_t *sslen)

Variables
const struct lws_protocols	lws_dht_protocol

Detailed Description

Distributed Hash Table (DHT) API

Lws provides a Mainline DHT implementation that can be used to track external IP addresses and find nodes/peers in a P2P network.

Data Structure Documentation

◆ lws_dht_hash

struct lws_dht_hash

struct lws_dht_hash - DHT hash/ID structure

Parameters

type	LWS_DHT_HASH_TYPE_...
len	length of the ID in bytes
id	the ID bytes

Definition at line 51 of file lws-dht.h.

Collaboration diagram for lws_dht_hash:

Data Fields
uint8_t	type
uint8_t	len
uint8_t	id[]

◆ lws_dht_info

struct lws_dht_info

struct lws_dht_info - Initialization parameters for DHT

Parameters

vhost	vhost to attach UDP wsi to
cb	callback for DHT events
closure	user-defined closure for cb
id	DHT ID (optional, NULL = random)
v	version string (optional, NULL = default)
port	UDP port to listen on
ipv6	enable IPv6
legacy	if set, on wire: no multihash, 20-byte assumed
aux	0 (sha1), or MULTIHASH_TYPE_...
iface	interface to bind to
blacklist_cb	(optional) user blacklist cb
hash_cb	(optional) user hash cb
capture_announce_cb	(optional) user capture announce cb

Definition at line 186 of file lws-dht.h.

Collaboration diagram for lws_dht_info:

Data Fields
struct lws_vhost *	vhost
lws_dht_callback_t *	cb
void *	closure
const lws_dht_hash_t *	id
const char *	v
int	port
uint8_t	ipv6:1
uint8_t	legacy:1
uint8_t	aux
const char *	iface
lws_dht_blacklist_cb_t *	blacklist_cb
lws_dht_hash_cb_t *	hash_cb
lws_dht_capture_announce_cb_t *	capture_announce_cb

Macro Definition Documentation

◆ DHT_MAX_PEERS

#define DHT_MAX_PEERS 2048

#include <include/libwebsockets/lws-dht.h>

Definition at line 144 of file lws-dht.h.

◆ DHT_MAX_HASHES

#define DHT_MAX_HASHES 16384

#include <include/libwebsockets/lws-dht.h>

Definition at line 147 of file lws-dht.h.

◆ DHT_MAX_SEARCHES

#define DHT_MAX_SEARCHES 1024

#include <include/libwebsockets/lws-dht.h>

Definition at line 150 of file lws-dht.h.

◆ DHT_SEARCH_EXPIRE_TIME

#define DHT_SEARCH_EXPIRE_TIME (62 * 60)

#include <include/libwebsockets/lws-dht.h>

Definition at line 153 of file lws-dht.h.

Typedef Documentation

◆ lws_dht_hash_t

typedef struct lws_dht_hash lws_dht_hash_t

#include <include/libwebsockets/lws-dht.h>

struct lws_dht_hash - DHT hash/ID structure

Parameters

type	LWS_DHT_HASH_TYPE_...
len	length of the ID in bytes
id	the ID bytes

◆ lws_dht_callback_t

typedef void lws_dht_callback_t(void *closure, int event, const lws_dht_hash_t *info_hash, const void *data, size_t data_len)

#include <include/libwebsockets/lws-dht.h>

lws_dht_callback_t() - DHT event callback

Parameters

closure	user-defined closure pointer
event	LWS_DHT_EVENT_...
info_hash	the hash related to the event
data	event-specific data
data_len	length of event-specific data

Definition at line 99 of file lws-dht.h.

◆ lws_dht_blacklist_cb_t

typedef int lws_dht_blacklist_cb_t(const struct sockaddr *sa, size_t salen)

#include <include/libwebsockets/lws-dht.h>

lws_dht_blacklist_cb_t() - DHT blacklist check callback

Parameters

sa	sockaddr to check
salen	length of sockaddr

Returns: 0 if the address is allowed, non-zero if it is blacklisted.

Definition at line 110 of file lws-dht.h.

◆ lws_dht_hash_cb_t

typedef void lws_dht_hash_cb_t(void *hash_return, int hash_size, const void *v1, int len1, const void *v2, int len2, const void *v3, int len3)

#include <include/libwebsockets/lws-dht.h>

lws_dht_hash_cb_t() - Custom hash function for DHT

Parameters

hash_return	where to store the hash result
hash_size	size of the hash result buffer
v1	first data chunk
len1	length of first chunk
v2	second data chunk (optional)
len2	length of second chunk
v3	third data chunk (optional)
len3	length of third chunk

Definition at line 125 of file lws-dht.h.

◆ lws_dht_capture_announce_cb_t

typedef void lws_dht_capture_announce_cb_t(struct lws_dht_ctx *ctx, lws_dht_hash_t *hash, const struct sockaddr *fromaddr, unsigned short prt)

#include <include/libwebsockets/lws-dht.h>

lws_dht_capture_announce_cb_t() - Captured announce callback

Parameters

ctx	DHT context
hash	the announced hash
fromaddr	where the announce came from
prt	the port announced

Definition at line 139 of file lws-dht.h.

◆ lws_dht_info_t

typedef struct lws_dht_info lws_dht_info_t

#include <include/libwebsockets/lws-dht.h>

struct lws_dht_info - Initialization parameters for DHT

Parameters

vhost	vhost to attach UDP wsi to
cb	callback for DHT events
closure	user-defined closure for cb
id	DHT ID (optional, NULL = random)
v	version string (optional, NULL = default)
port	UDP port to listen on
ipv6	enable IPv6
legacy	if set, on wire: no multihash, 20-byte assumed
aux	0 (sha1), or MULTIHASH_TYPE_...
iface	interface to bind to
blacklist_cb	(optional) user blacklist cb
hash_cb	(optional) user hash cb
capture_announce_cb	(optional) user capture announce cb

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

#include <include/libwebsockets/lws-dht.h>

Enumerator
LWS_DHT_HASH_TYPE_UNKNOWN
LWS_DHT_HASH_TYPE_SHA1
LWS_DHT_HASH_TYPE_SHA256
LWS_DHT_HASH_TYPE_SHA512
LWS_DHT_HASH_TYPE_BLAKE3

Definition at line 57 of file lws-dht.h.

     {
        LWS_DHT_HASH_TYPE_UNKNOWN      = 0,
        LWS_DHT_HASH_TYPE_SHA1            = 0x11, /* 20 bytes */
        LWS_DHT_HASH_TYPE_SHA256        = 0x12, /* 32 bytes */
        LWS_DHT_HASH_TYPE_SHA512        = 0x13, /* 64 bytes */
        LWS_DHT_HASH_TYPE_BLAKE3        = 0x1e, /* 32 bytes */
};

◆ lws_dht_event_t

enum lws_dht_event_t

#include <include/libwebsockets/lws-dht.h>

enum lws_dht_event_t - DHT events reported via callback

Enumerator
LWS_DHT_EVENT_NONE
LWS_DHT_EVENT_VALUES	Peers for requested hash found
LWS_DHT_EVENT_VALUES6	IPv6 peers for requested hash found
LWS_DHT_EVENT_SEARCH_DONE	Search operation completed
LWS_DHT_EVENT_SEARCH_DONE6	IPv6 search operation completed
LWS_DHT_EVENT_EXTERNAL_ADDR	External IPv4 address determined
LWS_DHT_EVENT_EXTERNAL_ADDR6	External IPv6 address determined

Definition at line 158 of file lws-dht.h.

             {
        LWS_DHT_EVENT_NONE,
        LWS_DHT_EVENT_VALUES,               
        LWS_DHT_EVENT_VALUES6,             
        LWS_DHT_EVENT_SEARCH_DONE,     
        LWS_DHT_EVENT_SEARCH_DONE6,   
        LWS_DHT_EVENT_EXTERNAL_ADDR, 
        LWS_DHT_EVENT_EXTERNAL_ADDR6,       
} lws_dht_event_t;

Function Documentation

◆ lws_dht_hash_create()

LWS_VISIBLE LWS_EXTERN lws_dht_hash_t * lws_dht_hash_create	(	int	type,
		int	len,
		const uint8_t *	data )

#include <include/libwebsockets/lws-dht.h>

lws_dht_hash_create() - Create a DHT hash from data

Parameters

type	LWS_DHT_HASH_TYPE_...
len	length of data
data	the data to hash or use as ID

This creates a new lws_dht_hash_t object on the heap.

Returns: pointer to the new hash, or NULL on failure.

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_dht_hash_destroy()

LWS_VISIBLE LWS_EXTERN void lws_dht_hash_destroy ( lws_dht_hash_t ** p )

#include <include/libwebsockets/lws-dht.h>

lws_dht_hash_destroy() - Destroy a DHT hash

Parameters

p	pointer to the hash pointer to destroy

Frees the hash and sets the pointer to NULL.

◆ lws_dht_create()

LWS_VISIBLE LWS_EXTERN struct lws_dht_ctx * lws_dht_create ( const lws_dht_info_t * info )

#include <include/libwebsockets/lws-dht.h>

lws_dht_create() - Create a DHT context

Parameters

info	initialization parameters

Returns: pointer to DHT context or NULL on failure.

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_dht_destroy()

LWS_VISIBLE LWS_EXTERN void lws_dht_destroy ( struct lws_dht_ctx ** pctx )

#include <include/libwebsockets/lws-dht.h>

lws_dht_destroy() - Destroy a DHT context

Parameters

pctx	pointer to the DHT context pointer to destroy

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_dht_insert_node()

LWS_VISIBLE LWS_EXTERN int lws_dht_insert_node	(	struct lws_dht_ctx *	ctx,
		const lws_dht_hash_t *	id,
		struct sockaddr *	sa,
		size_t	salen )

#include <include/libwebsockets/lws-dht.h>

lws_dht_insert_node() - Manually insert a node into the DHT

Parameters

ctx	DHT context
id	ID of the node
sa	sockaddr of the node
salen	length of sockaddr

Returns: 1 if successful, 0 if it already exists, or -1 on error.

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_dht_ping_node()

LWS_VISIBLE LWS_EXTERN int lws_dht_ping_node	(	struct lws_dht_ctx *	ctx,
		struct sockaddr *	sa,
		size_t	salen )

#include <include/libwebsockets/lws-dht.h>

lws_dht_ping_node() - Ping a node to verify it is alive

Parameters

ctx	DHT context
sa	sockaddr of the node
salen	length of sockaddr

Returns: number of bytes sent on success, or -1 on error.

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_dht_search()

LWS_VISIBLE LWS_EXTERN int lws_dht_search	(	struct lws_dht_ctx *	ctx,
		const lws_dht_hash_t *	id,
		int	port,
		int	af,
		lws_dht_callback_t *	callback,
		void *	closure )

#include <include/libwebsockets/lws-dht.h>

lws_dht_search() - Perform an asynchronous search for a hash

Parameters

ctx	DHT context
id	hash to search for
port	port to search on
af	address family (AF_INET, AF_INET6, or 0 for both)
callback	search completion/result callback
closure	closure for `callback`

This performs an iterative, asynchronous search for the requested hash. If port is non-zero, it also announces our availability for this hash.

Results (peers/values) are delivered to the callback as they are found via LWS_DHT_EVENT_VALUES or LWS_DHT_EVENT_VALUES6 events.

The callback is also called with event LWS_DHT_EVENT_SEARCH_DONE (or LWS_DHT_EVENT_SEARCH_DONE6) when the search operation has exhausted all potential nodes or reached a timeout.

Returns: 1 if search started successfully, 0 if answered locally (callback still called), or -1 on error.

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_dht_nodes()

LWS_VISIBLE LWS_EXTERN int lws_dht_nodes	(	struct lws_dht_ctx *	ctx,
		int	af,
		int *	good_return,
		int *	dubious_return,
		int *	cached_return,
		int *	incoming_return )

#include <include/libwebsockets/lws-dht.h>

lws_dht_nodes() - Get statistics about DHT nodes

Parameters

ctx	DHT context
af	address family (AF_INET, AF_INET6)
good_return	count of known good nodes
dubious_return	count of dubious nodes
cached_return	count of cached nodes
incoming_return	count of incoming nodes

Returns: total number of good + dubious nodes.

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_dht_dump_tables()

LWS_VISIBLE LWS_EXTERN void lws_dht_dump_tables ( struct lws_dht_ctx * ctx )

#include <include/libwebsockets/lws-dht.h>

lws_dht_dump_tables() - Log the state of DHT routing tables

Parameters

ctx	DHT context

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_dht_get_nodes()

LWS_VISIBLE LWS_EXTERN int lws_dht_get_nodes	(	struct lws_dht_ctx *	ctx,
		struct sockaddr_in *	sin,
		int *	num,
		struct sockaddr_in6 *	sin6,
		int *	num6 )

#include <include/libwebsockets/lws-dht.h>

lws_dht_get_nodes() - Get a list of known nodes

Parameters

ctx	DHT context
sin	buffer for IPv4 nodes
num	in/out count for IPv4 nodes
sin6	buffer for IPv6 nodes
num6	in/out count for IPv6 nodes

Returns: total number of nodes filled (v4 + v6).

References LWS_EXTERN, and LWS_VISIBLE.

◆ lws_dht_get_external_addr()

LWS_VISIBLE LWS_EXTERN int lws_dht_get_external_addr	(	struct lws_dht_ctx *	ctx,
		struct sockaddr_storage *	ss,
		size_t *	sslen )

#include <include/libwebsockets/lws-dht.h>

lws_dht_get_external_addr() - Get our external IP and port as determined by STUN

Parameters

ctx	DHT context
ss	buffer for external address and port
sslen	length of buffer/written address

Returns: 0 on success, or -1 if the address and port are not yet determined.

Variable Documentation

◆ lws_dht_protocol

const struct lws_protocols lws_dht_protocol

extern

#include <include/libwebsockets/lws-dht.h>

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Distributed Hash Table (DHT) API

Data Structure Documentation

◆ lws_dht_hash

◆ lws_dht_info

Macro Definition Documentation

◆ DHT_MAX_PEERS

◆ DHT_MAX_HASHES

◆ DHT_MAX_SEARCHES

◆ DHT_SEARCH_EXPIRE_TIME

Typedef Documentation

◆ lws_dht_hash_t

◆ lws_dht_callback_t

◆ lws_dht_blacklist_cb_t

◆ lws_dht_hash_cb_t

◆ lws_dht_capture_announce_cb_t

◆ lws_dht_info_t

Enumeration Type Documentation

◆ anonymous enum

◆ lws_dht_event_t

Function Documentation

◆ lws_dht_hash_create()

◆ lws_dht_hash_destroy()

◆ lws_dht_create()

◆ lws_dht_destroy()

◆ lws_dht_insert_node()

◆ lws_dht_ping_node()

◆ lws_dht_search()

◆ lws_dht_nodes()

◆ lws_dht_dump_tables()

◆ lws_dht_get_nodes()

◆ lws_dht_get_external_addr()

Variable Documentation

◆ lws_dht_protocol