.. include:: header.rst

`home`__

__ reference.html

.. contents:: Table of contents
  :depth: 2
  :backlinks: none

.. raw:: html

	<a name="dht_storage_counters"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_storage_counters&labels=documentation&body=Documentation+under+heading+%22class+dht_storage_counters%22+could+be+improved">report issue</a>]</span>



dht_storage_counters
--------------------

Declared in "`libtorrent/kademlia/dht_storage.hpp`__"


__ include/libtorrent/kademlia/dht_storage.hpp

This structure hold the relevant `counters`__ for the storage


__ reference-Stats.html#counters


.. parsed-literal::
	

	struct dht_storage_counters
	{
	   void **reset** ();
	
	   std::int32_t **torrents**  = 0;
	   std::int32_t **peers**  = 0;
	   std::int32_t **immutable_data**  = 0;
	   std::int32_t **mutable_data**  = 0;
	};

.. raw:: html

	<a name="reset()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_counters%3A%3A%5Breset%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_counters%3A%3A%5Breset%28%29%5D%22+could+be+improved">report issue</a>]</span>



reset()
.......

.. parsed-literal::
	
	void **reset** ();
	

This member function set the `counters`__ to zero.


__ reference-Stats.html#counters

.. raw:: html

	<a name="dht_storage_interface"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_storage_interface&labels=documentation&body=Documentation+under+heading+%22class+dht_storage_interface%22+could+be+improved">report issue</a>]</span>



dht_storage_interface
---------------------

Declared in "`libtorrent/kademlia/dht_storage.hpp`__"


__ include/libtorrent/kademlia/dht_storage.hpp

The DHT storage interface is a pure virtual class that can
be implemented to customize how the data for the DHT is stored.

The default storage implementation uses three maps in RAM to save
the peers, mutable and immutable items and it's designed to
provide a fast and fully compliant behavior of the BEPs.

libtorrent comes with one built-in storage implementation:
``dht_default_storage`` (private non-accessible class). Its
constructor function is called `dht_default_storage_constructor()`__.
You should know that if this storage becomes full of DHT items,
the current implementation could degrade in performance.


__ reference-DHT.html#dht_default_storage_constructor()


.. parsed-literal::
	

	struct dht_storage_interface
	{
	   virtual void **update_node_ids** (std\:\:vector<node\_id> const& ids) = 0;
	   virtual bool **get_peers** (sha1\_hash const& info\_hash
	      , bool noseed, bool scrape, address const& requester
	      , entry& peers) const = 0;
	   virtual void **announce_peer** (sha1\_hash const& info\_hash
	      , tcp\:\:endpoint const& endp
	      , string\_view name, bool seed) = 0;
	   virtual bool **get_immutable_item** (sha1\_hash const& target
	      , entry& item) const = 0;
	   virtual void **put_immutable_item** (sha1\_hash const& target
	      , span<char const> buf
	      , address const& addr) = 0;
	   virtual bool **get_mutable_item_seq** (sha1\_hash const& target
	      , sequence\_number& seq) const = 0;
	   virtual bool **get_mutable_item** (sha1\_hash const& target
	      , sequence\_number seq, bool force\_fill
	      , entry& item) const = 0;
	   virtual void **put_mutable_item** (sha1\_hash const& target
	      , span<char const> buf
	      , signature const& sig
	      , sequence\_number seq
	      , public\_key const& pk
	      , span<char const> salt
	      , address const& addr) = 0;
	   virtual int **get_infohashes_sample** (entry& item) = 0;
	   virtual void **tick** () = 0;
	   virtual dht_storage_counters **counters** () const = 0;
	};

.. raw:: html

	<a name="update_node_ids()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Bupdate_node_ids%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Bupdate_node_ids%28%29%5D%22+could+be+improved">report issue</a>]</span>



update_node_ids()
.................

.. parsed-literal::
	
	virtual void **update_node_ids** (std\:\:vector<node\_id> const& ids) = 0;
	

This member function notifies the list of all node's ids
of each DHT running inside libtorrent. It's advisable
that the concrete implementation keeps a copy of this list
for an eventual prioritization when deleting an element
to make room for a new one.



.. raw:: html

	<a name="get_peers()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Bget_peers%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Bget_peers%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_peers()
...........

.. parsed-literal::
	
	virtual bool **get_peers** (sha1\_hash const& info\_hash
	      , bool noseed, bool scrape, address const& requester
	      , entry& peers) const = 0;
	

This function retrieve the peers tracked by the DHT
corresponding to the given info_hash. You can specify if
you want only seeds and/or you are scraping the data.

For future implementers:
If the torrent tracked contains a name, such a name
must be stored as a string in peers["n"]

If the scrape parameter is true, you should fill these keys:

   peers["BFpe"]
      with the standard bit representation of a
      256 bloom filter containing the downloaders
   peers["BFsd"]
      with the standard bit representation of a
      256 bloom filter containing the seeders

If the scrape parameter is false, you should fill the
key peers["values"] with a list containing a subset of
peers tracked by the given info_hash. Such a list should
consider the value of `settings_pack::dht_max_peers_reply`__.
If noseed is true only peers marked as no seed should be included.

returns true if the maximum number of peers are stored
for this info_hash.


__ reference-Settings.html#dht_max_peers_reply

.. raw:: html

	<a name="announce_peer()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Bannounce_peer%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Bannounce_peer%28%29%5D%22+could+be+improved">report issue</a>]</span>



announce_peer()
...............

.. parsed-literal::
	
	virtual void **announce_peer** (sha1\_hash const& info\_hash
	      , tcp\:\:endpoint const& endp
	      , string\_view name, bool seed) = 0;
	

This function is named announce_peer for consistency with the
upper layers, but has nothing to do with networking. Its only
responsibility is store the peer in such a way that it's returned
in the `entry`__ with the lookup_peers.

The ``name`` parameter is the name of the torrent if provided in
the announce_peer DHT message. The length of this value should
have a maximum length in the final storage. The default
implementation truncate the value for a maximum of 50 characters.


__ reference-Bencoding.html#entry

.. raw:: html

	<a name="get_immutable_item()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Bget_immutable_item%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Bget_immutable_item%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_immutable_item()
....................

.. parsed-literal::
	
	virtual bool **get_immutable_item** (sha1\_hash const& target
	      , entry& item) const = 0;
	

This function retrieves the immutable item given its target hash.

For future implementers:
The value should be returned as an `entry`__ in the key item["v"].

returns true if the item is found and the data is returned
inside the (`entry`__) out parameter item.


__ reference-Bencoding.html#entry
__ reference-Bencoding.html#entry

.. raw:: html

	<a name="put_immutable_item()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Bput_immutable_item%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Bput_immutable_item%28%29%5D%22+could+be+improved">report issue</a>]</span>



put_immutable_item()
....................

.. parsed-literal::
	
	virtual void **put_immutable_item** (sha1\_hash const& target
	      , span<char const> buf
	      , address const& addr) = 0;
	

Store the item's data. This layer is only for storage.
The authentication of the item is performed by the upper layer.

For implementers:
This data can be stored only if the target is not already
present. The implementation should consider the value of
`settings_pack::dht_max_dht_items`__.



__ reference-Settings.html#dht_max_dht_items

.. raw:: html

	<a name="get_mutable_item_seq()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Bget_mutable_item_seq%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Bget_mutable_item_seq%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_mutable_item_seq()
......................

.. parsed-literal::
	
	virtual bool **get_mutable_item_seq** (sha1\_hash const& target
	      , sequence\_number& seq) const = 0;
	

This function retrieves the sequence number of a mutable item.

returns true if the item is found and the data is returned
inside the out parameter seq.



.. raw:: html

	<a name="get_mutable_item()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Bget_mutable_item%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Bget_mutable_item%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_mutable_item()
..................

.. parsed-literal::
	
	virtual bool **get_mutable_item** (sha1\_hash const& target
	      , sequence\_number seq, bool force\_fill
	      , entry& item) const = 0;
	

This function retrieves the mutable stored in the DHT.

For implementers:
The item sequence should be stored in the key item["seq"].
if force_fill is true or (0 <= seq and seq < item["seq"])
the following keys should be filled
item["v"] - with the value no encoded.
item["sig"] - with a string representation of the signature.
item["k"] - with a string representation of the public key.

returns true if the item is found and the data is returned
inside the (`entry`__) out parameter item.


__ reference-Bencoding.html#entry

.. raw:: html

	<a name="put_mutable_item()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Bput_mutable_item%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Bput_mutable_item%28%29%5D%22+could+be+improved">report issue</a>]</span>



put_mutable_item()
..................

.. parsed-literal::
	
	virtual void **put_mutable_item** (sha1\_hash const& target
	      , span<char const> buf
	      , signature const& sig
	      , sequence\_number seq
	      , public\_key const& pk
	      , span<char const> salt
	      , address const& addr) = 0;
	

Store the item's data. This layer is only for storage.
The authentication of the item is performed by the upper layer.

For implementers:
The sequence number should be checked if the item is already
present. The implementation should consider the value of
`settings_pack::dht_max_dht_items`__.



__ reference-Settings.html#dht_max_dht_items

.. raw:: html

	<a name="get_infohashes_sample()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Bget_infohashes_sample%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Bget_infohashes_sample%28%29%5D%22+could+be+improved">report issue</a>]</span>



get_infohashes_sample()
.......................

.. parsed-literal::
	
	virtual int **get_infohashes_sample** (entry& item) = 0;
	

This function retrieves a sample info-hashes

For implementers:
The info-hashes should be stored in ["samples"] (N x 20 bytes).
the following keys should be filled
item["interval"] - the subset refresh interval in seconds.
item["num"] - number of info-hashes in storage.

Internally, this function is allowed to lazily evaluate, cache
and modify the actual sample to put in ``item``

returns the number of info-hashes in the sample.



.. raw:: html

	<a name="tick()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Btick%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Btick%28%29%5D%22+could+be+improved">report issue</a>]</span>



tick()
......

.. parsed-literal::
	
	virtual void **tick** () = 0;
	

This function is called periodically (non-constant frequency).

For implementers:
Use this functions for expire peers or items or any other
storage cleanup.



.. raw:: html

	<a name="counters()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_storage_interface%3A%3A%5Bcounters%28%29%5D&labels=documentation&body=Documentation+under+heading+%22dht_storage_interface%3A%3A%5Bcounters%28%29%5D%22+could+be+improved">report issue</a>]</span>



counters()
..........

.. parsed-literal::
	
	virtual dht_storage_counters **counters** () const = 0;
	

return stats `counters`__ for the store


__ reference-Stats.html#counters

.. raw:: html

	<a name="dht_state"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+dht_state&labels=documentation&body=Documentation+under+heading+%22class+dht_state%22+could+be+improved">report issue</a>]</span>



dht_state
---------

Declared in "`libtorrent/kademlia/dht_state.hpp`__"


__ include/libtorrent/kademlia/dht_state.hpp

This structure helps to store and load the state
of the ``dht_tracker``.
At this moment the library is only a dual stack
implementation of the DHT. See `BEP 32`_

.. _`BEP 32`: https://www.bittorrent.org/beps/bep_0032.html




.. parsed-literal::
	

	struct dht_state
	{
	   void **clear** ();
	
	   node_ids_t nids;
	   std::vector<udp::endpoint> nodes;
	   std::vector<udp::endpoint> nodes6;
	};

.. raw:: html

	<a name="nodes"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_state%3A%3A%5Bnodes%5D&labels=documentation&body=Documentation+under+heading+%22dht_state%3A%3A%5Bnodes%5D%22+could+be+improved">report issue</a>]</span>


nodes
	the bootstrap nodes saved from the buckets node
	


.. raw:: html

	<a name="nodes6"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_state%3A%3A%5Bnodes6%5D&labels=documentation&body=Documentation+under+heading+%22dht_state%3A%3A%5Bnodes6%5D%22+could+be+improved">report issue</a>]</span>


nodes6
	the bootstrap nodes saved from the IPv6 buckets node
	


.. raw:: html

	<a name="dht_default_storage_constructor()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:dht_default_storage_constructor%28%29&labels=documentation&body=Documentation+under+heading+%22dht_default_storage_constructor%28%29%22+could+be+improved">report issue</a>]</span>



dht_default_storage_constructor()
---------------------------------

Declared in "`libtorrent/kademlia/dht_storage.hpp`__"


__ include/libtorrent/kademlia/dht_storage.hpp

.. parsed-literal::
	
	std::unique_ptr<dht_storage_interface> **dht_default_storage_constructor** (
	   settings\_interface const& settings);
	

constructor for the default DHT storage. The DHT storage is responsible
for maintaining peers and mutable and immutable items announced and
stored/put to the DHT node.



.. raw:: html

	<a name="sign_mutable_item()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:sign_mutable_item%28%29&labels=documentation&body=Documentation+under+heading+%22sign_mutable_item%28%29%22+could+be+improved">report issue</a>]</span>



sign_mutable_item()
-------------------

Declared in "`libtorrent/kademlia/item.hpp`__"


__ include/libtorrent/kademlia/item.hpp

.. parsed-literal::
	
	signature **sign_mutable_item** (
	   span<char const> v
	   , span<char const> salt
	   , sequence\_number seq
	   , public\_key const& pk
	   , secret\_key const& sk);
	

given a byte range ``v`` and an optional byte range ``salt``, a
sequence number, public key ``pk`` (must be 32 bytes) and a secret key
``sk`` (must be 64 bytes), this function produces a signature which
is written into a 64 byte buffer pointed to by ``sig``. The caller
is responsible for allocating the destination buffer that's passed in
as the ``sig`` argument. Typically it would be allocated on the stack.



.. raw:: html

	<a name="announce_flags_t"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:announce_flags_t&labels=documentation&body=Documentation+under+heading+%22announce_flags_t%22+could+be+improved">report issue</a>]</span>



announce_flags_t
----------------

Declared in "`libtorrent/kademlia/announce_flags.hpp`__"


__ include/libtorrent/kademlia/announce_flags.hpp

.. raw:: html

	<a name="announce_flags_t::seed"></a>

seed
	announce to DHT as a seed
	


.. raw:: html

	<a name="announce_flags_t::implied_port"></a>

implied_port
	announce to DHT with the implied-port flag set. This tells the network to use
	your source UDP port as your listen port, rather than the one specified in
	the message. This may improve the chances of traversing NATs when using uTP.
	


.. raw:: html

	<a name="announce_flags_t::ssl_torrent"></a>

ssl_torrent
	Specify the port number for the SSL listen socket in the DHT announce.
	





.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 52`: https://www.bittorrent.org/beps/bep_0052.html
.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
