libtorrent

https://www.libtorrent.org/
Admin
libtorrent is a feature-complete C++ BitTorrent implementation focusing on efficiency, scalability,...
Tokens:828,381
Snippets:5,614
Trust Score:9.4
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install libtorrent with vcpkg

Source: https://www.libtorrent.org/building.html

Install libtorrent via the vcpkg dependency manager. Run these commands in order to clone vcpkg, bootstrap it, integrate it with your build system, and install the libtorrent port.

```shell
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install libtorrent

```

--------------------------------

### Install libtorrent with b2 install

Source: https://www.libtorrent.org/building.html

Installs libtorrent to /usr/local. Change the --prefix argument to install to a different location.

```bash
b2 install --prefix=/usr/local

```

--------------------------------

### SOCKS5 stream connection and handshake setup

Source: https://www.libtorrent.org/todo.html

Shows the SOCKS5 stream connection setup: name lookup, async connect, and the start of the SOCKS5 handshake. It opens the socket if needed, connects to the resolved endpoint, and prepares the authentication method buffer (no auth or username/password) for SOCKS version 5.

```cpp
			}, std::move(handler)));
	}

private:

	template <typename Handler>
	void name_lookup(error_code const& e, tcp::resolver::results_type ips
		, Handler h)
	{
		COMPLETE_ASYNC("socks5_stream::name_lookup");
		if (handle_error(e, std::move(h))) return;

		auto i = ips.begin();
		if (!m_sock.is_open())
		{
			error_code ec;
			m_sock.open(i->endpoint().protocol(), ec);
			if (handle_error(ec, std::move(h))) return;
		}

		ADD_OUTSTANDING_ASYNC("socks5_stream::connected");
		m_sock.async_connect(i->endpoint(), aux::wrap_allocator(
			[this](error_code const& ec, Handler hn)
			{ connected(ec, std::move(hn)); }, std::move(h)));
	}

	template <typename Handler>
	void connected(error_code const& e, Handler h)
	{
		COMPLETE_ASYNC("socks5_stream::connected");
		if (handle_error(e, std::move(h))) return;

		using namespace libtorrent::aux;
		if (m_version == 5)
		{
			// send SOCKS5 authentication methods
			m_buffer.resize(m_user.empty()?3:4);
			char* p = &m_buffer[0];
			write_uint8(5, p); // SOCKS VERSION 5
			if (m_user.empty())
			{
				write_uint8(1, p); // 1 authentication method (no auth)
				write_uint8(0, p); // no authentication
			}
			else
			{
				write_uint8(2, p); // 2 authentication methods
				write_uint8(0, p); // no authentication
				write_uint8(2, p); // username/password
			}
			ADD_OUTSTANDING_ASYNC("socks5_stream::handshake1");


```

--------------------------------

### Install libtorrent python bindings

Source: https://www.libtorrent.org/python_binding.html

Installs the built libtorrent python bindings into the current Python environment.

```bash
python setup.py install

```

--------------------------------

### Customize build and install in one command

Source: https://www.libtorrent.org/python_binding.html

Runs build_ext with custom b2 arguments and installation in a single command to ensure the custom settings are applied.

```bash
python setup.py build_ext --b2-args="optimization=space" install

```

--------------------------------

### Creating a torrent file example

Source: https://www.libtorrent.org/single-page-ref.html

Example of creating a torrent file: list files, create a create_torrent object, add tracker and creator, set piece hashes, generate buffer, and write to file. Also shows alternative bencode generation.

```cpp
// recursively create a list of all files in the directory
auto fs = list_files("./my_torrent");

create_torrent t(std::move(fs));
t.add_tracker("http://my.tracker.com/announce");
t.set_creator("libtorrent example");

// reads the files and calculates the hashes
set_piece_hashes(t, ".");

ofstream out("my_torrent.torrent", std::ios_base::binary);
std::vector<char> buf = t.generate_buf();
out.write(buf.data(), buf.size());

// alternatively, generate an entry and encode it directly to an ostream
// iterator
bencode(std::ostream_iterator<char>(out), t.generate());

```

--------------------------------

### UDP tracker connection constructor and start in udp_tracker_connection.cpp

Source: https://www.libtorrent.org/todo.html

Shows the constructor and start method of udp_tracker_connection. The comment suggests supporting authentication via tracker_req().auth.

```cpp
		udp_tracker_connection::m_connection_cache;

	std::mutex udp_tracker_connection::m_cache_mutex;

	udp_tracker_connection::udp_tracker_connection(
		io_context& ios
		, tracker_manager& man
		, tracker_request const& req
		, std::weak_ptr<request_callback> c)
		: tracker_connection(man, req, ios, std::move(c))
		, m_transaction_id(0)
		, m_attempts(0)
		, m_state(action_t::error)
		, m_abort(false)
	{
		update_transaction_id();
	}

	void udp_tracker_connection::start()
	{
		std::string hostname;
		std::string protocol;
		int port;
		error_code ec;

		std::tie(protocol, std::ignore, hostname, port, std::ignore)
			= parse_url_components(tracker_req().url, ec);
		if (port == -1) port = protocol == "http" ? 80 : 443;

		if (ec)
		{
			tracker_connection::fail(ec, operation_t::parse_address);
			return;
		}

		aux::session_settings const& settings = m_man.settings();

		int const proxy_type = settings.get_int(settings_pack::proxy_type);

		if (settings.get_bool(settings_pack::proxy_hostnames)
			&& (proxy_type == settings_pack::socks5
				|| proxy_type == settings_pack::socks5_pw))
		{
			m_hostname = hostname;
			m_target.port(std::uint16_t(port));
			start_announce();
		}
		else
		{
			using namespace std::placeholders;
			ADD_OUTSTANDING_ASYNC("udp_tracker_connection::name_lookup");


```

--------------------------------

### Simple libtorrent Python usage example

Source: https://www.libtorrent.org/python_binding.html

A basic example of using the libtorrent Python module to create a session, add a torrent from a file path, and poll for alerts while printing progress. It demonstrates the use of set_alert_fd() indirectly by showing the typical alert polling loop with pop_alerts(). The example assumes the torrent file path is passed as a command-line argument.

```python
import sys
import time

import libtorrent as lt

ses = lt.session({"listen_interfaces": "0.0.0.0:6881"})

atp = lt.add_torrent_params()
atp.ti = lt.torrent_info(sys.argv[1])
atp.save_path = "."
h = ses.add_torrent(atp)
s = h.status()
print("starting", s.name)

while not s.is_seeding:
    s = h.status()

    print(
        "\r%.2f%% complete (down: %.1f kB/s up: %.1f kB/s peers: %d) %s"
        % (
            s.progress * 100,
            s.download_rate / 1000,
            s.upload_rate / 1000,
            s.num_peers,
            s.state,
        ),
        end=" ",
    )

    alerts = ses.pop_alerts()
    for a in alerts:
        if a.category() & lt.alert.category_t.error_notification:
            print(a)

    sys.stdout.flush()

    time.sleep(1)

print(h.status().name, "complete")
```

--------------------------------

### Configure b2 with auto-detected Python

Source: https://www.libtorrent.org/python_binding.html

Minimal configuration for b2 to find a Python installation via auto-detection. May be sufficient if b2 can detect the Python installation automatically.

```jam
using python : 3.7 ;
```

--------------------------------

### Start DHT and create dht_tracker in session_impl.cpp

Source: https://www.libtorrent.org/todo.html

Shows the DHT startup logic in session_impl.cpp:6070, including logging guards, creation of dht_tracker with a send_udp_packet_listen callback, and registration of listen sockets and router nodes. The snippet is truncated at the loop over m_dht_nodes.

```cpp
#ifndef TORRENT_DISABLE_LOGGING
			session_log("not starting DHT, outstanding router lookups: %d"
				, m_outstanding_router_lookups);
#endif
			return;
		}

		if (m_abort)
		{
#ifndef TORRENT_DISABLE_LOGGING
			session_log("not starting DHT, aborting");
#endif
			return;
		}

#ifndef TORRENT_DISABLE_LOGGING
		session_log("starting DHT, running: %s, router lookups: %d"
			, m_dht ? "true" : "false", m_outstanding_router_lookups);
#endif

		m_dht_storage = m_dht_storage_constructor(m_settings);
		m_dht = std::make_shared<dht::dht_tracker>(
			static_cast<dht::dht_observer*>(this)
			, m_io_context
			, [this](aux::listen_socket_handle const& sock
				, udp::endpoint const& ep
				, span<char const> p
				, error_code& ec
				, udp_send_flags_t const flags)
				{ send_udp_packet_listen(sock, ep, p, ec, flags); }
			, m_settings
			, m_stats_counters
			, *m_dht_storage
			, std::move(m_dht_state));

		for (auto& s : m_listen_sockets)
		{
			if (s->ssl != transport::ssl
				&& !(s->flags & listen_socket_t::local_network))
			{
				m_dht->new_socket(s);
			}
		}

		for (auto const& n : m_dht_router_nodes)
		{
			m_dht->add_router_node(n);
		}

		for (auto const& n : m_dht_nodes)
		{


```

--------------------------------

### pe_crypto.cpp:32 - Encryption includes and export_key start

Source: https://www.libtorrent.org/todo.html

The first part of the pe_crypto.cpp file, showing the conditional compilation guard, includes, the dh_prime constant, and the beginning of the export_key function. The comment at the top indicates a desire to get the literal working, and the code is truncated at the point where the export_bits call is made.

```cpp
*/
```

```cpp
#if !defined TORRENT_DISABLE_ENCRYPTION

#include <cstdint>
#include <algorithm>
#include <random>

#include "libtorrent/aux_/disable_warnings_push.hpp"
#include <boost/multiprecision/integer.hpp>
#include "libtorrent/aux_/disable_warnings_pop.hpp"

#include "libtorrent/aux_/random.hpp"
#include "libtorrent/aux_/alloca.hpp"
#include "libtorrent/aux_/pe_crypto.hpp"
#include "libtorrent/hasher.hpp"

namespace libtorrent::aux {

	namespace {
		key_t const dh_prime
			("0xFFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD129024E088A67CC74020BBEA63B139B22514A08798E3404DDEF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245E485B576625E7EC6F44C42E9A63A36210000000000090563");
	}

	std::array<char, 96> export_key(key_t const& k)
	{
		std::array<char, 96> ret;
		auto* begin = reinterpret_cast<std::uint8_t*>(ret.data());
		std::uint8_t* end = mp::export_bits(k, begin, 8);



```

--------------------------------

### libtorrent session state example with session_params and SIGINT shutdown

Source: https://www.libtorrent.org/tutorial-ref.html

Complete libtorrent example that loads and saves session parameters to ".session", loads resume data from ".resume_file", adds a magnet link, and shuts down on SIGINT by saving resume data. Requires a magnet URL as the single command-line argument; the session is configured with an alert mask for error, storage, and status categories.

```cpp
#include <iostream>
#include <thread>
#include <chrono>
#include <fstream>
#include <csignal>

#include <libtorrent/session.hpp>
#include <libtorrent/session_params.hpp>
#include <libtorrent/add_torrent_params.hpp>
#include <libtorrent/torrent_handle.hpp>
#include <libtorrent/alert_types.hpp>
#include <libtorrent/bencode.hpp>
#include <libtorrent/torrent_status.hpp>
#include <libtorrent/read_resume_data.hpp>
#include <libtorrent/write_resume_data.hpp>
#include <libtorrent/error_code.hpp>
#include <libtorrent/magnet_uri.hpp>

namespace {

using clk = std::chrono::steady_clock;

// return the name of a torrent status enum
char const* state(lt::torrent_status::state_t s)
{
#ifdef __clang__
#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wcovered-switch-default"
#endif
  switch(s) {
    case lt::torrent_status::checking_files: return "checking";
    case lt::torrent_status::downloading_metadata: return "dl metadata";
    case lt::torrent_status::downloading: return "downloading";
    case lt::torrent_status::finished: return "finished";
    case lt::torrent_status::seeding: return "seeding";
    case lt::torrent_status::checking_resume_data: return "checking resume";
    default: return "<>";
  }
#ifdef __clang__
#pragma clang diagnostic pop
#endif
}

std::vector<char> load_file(char const* filename)
{
  std::ifstream ifs(filename, std::ios_base::binary);
  ifs.unsetf(std::ios_base::skipws);
  return {std::istream_iterator<char>(ifs), std::istream_iterator<char>()};
}

// set when we're exiting
std::atomic<bool> shut_down{false};

void sighandler(int) { shut_down = true; }

} // anonymous namespace

int main(int argc, char const* argv[]) try
{
  if (argc != 2) {
    std::cerr << "usage: " << argv[0] << " <magnet-url>" << std::endl;
    return 1;
  }

  // load session parameters
  auto session_params = load_file(".session");
  lt::session_params params = session_params.empty()
    ? lt::session_params() : lt::read_session_params(session_params);
  params.settings.set_int(lt::settings_pack::alert_mask
    , lt::alert_category::error
    | lt::alert_category::storage
    | lt::alert_category::status);

  lt::session ses(params);
  clk::time_point last_save_resume = clk::now();

  // load resume data from disk and pass it in as we add the magnet link
  auto buf = load_file(".resume_file");

  lt::add_torrent_params magnet = lt::parse_magnet_uri(argv[1]);
  if (buf.size()) {
    lt::add_torrent_params atp = lt::read_resume_data(buf);
    if (atp.info_hashes == magnet.info_hashes) magnet = std::move(atp);
  }
  magnet.save_path = "."; // save in current dir
  ses.async_add_torrent(std::move(magnet));

  // this is the handle we'll set once we get the notification of it being
  // added
  lt::torrent_handle h;

  std::signal(SIGINT, &sighandler);

  // set when we're exiting
  bool done = false;
  for (;;) {
    std::vector<lt::alert*> alerts;
    ses.pop_alerts(&alerts);

    if (shut_down) {
      shut_down = false;
      auto const handles = ses.get_torrents();
      if (handles.size() == 1) {
        handles[0].save_resume_data(lt::torrent_handle::only_if_modified
          | lt::torrent_handle::save_info_dict);
        done = true;
      }
    }

```

--------------------------------

### file_slice struct definition

Source: https://www.libtorrent.org/reference-Storage.html

Defines a window of a file in a torrent. The file_index refers to the index of the file in the torrent_info; use file_path() with the file_index to get the path and filename. The offset is the byte offset where the range starts, and size is the number of bytes in the range; size + offset will never exceed the file size.

```cpp
struct file_slice
{
   file_index_t file_index;
   std::int64_t offset;
   std::int64_t size;
};

```

--------------------------------

### Build libtorrent on Windows with Boost.Build

Source: https://www.libtorrent.org/building.html

Sets up Boost environment variables, bootstraps Boost.Build, configures the MSVC toolset, and builds libtorrent on Windows. Assumes the boost package is saved to C:\boost_1_69_0.

```batch
set BOOST_ROOT=c:\boost_1_69_0
set BOOST_BUILD_PATH=%BOOST_ROOT%\tools\build
(cd %BOOST_ROOT% && .\bootstrap.bat)
echo using msvc ; >>%HOMEDRIVE%%HOMEPATH%\user-config.jam
%BOOST_ROOT%\b2.exe --hash release

```

--------------------------------

### Build libtorrent python bindings with setup.py

Source: https://www.libtorrent.org/python_binding.html

Builds the libtorrent python bindings using the default setup.py invocation, which calls b2 under the hood.

```bash
python setup.py build

```

--------------------------------

### piece_picker::pick_pieces with hardcoded 2048 partial limit

Source: https://www.libtorrent.org/todo.html

Shows the start of piece_picker::pick_pieces, including the check that caps partial pieces at 2048 blocks (32 MiB) and prioritizes partials when the limit is exceeded. The comment notes the limit should be made configurable. The snippet includes assertions and setup for backup blocks and ignored pieces.

```cpp
	// indicating which path thought the picker we took to arrive at the
	// returned block picks.
	picker_flags_t piece_picker::pick_pieces(typed_bitfield<piece_index_t> const& pieces
		, std::vector<piece_block>& interesting_blocks, int num_blocks
		, int prefer_contiguous_blocks, aux::torrent_peer* peer
		, picker_options_t options, std::vector<piece_index_t> const& suggested_pieces
		, int num_peers
		, counters& pc
		) const
	{
		TORRENT_ASSERT(peer == nullptr || peer->in_use);
		picker_flags_t ret;

		// prevent the number of partial pieces to grow indefinitely
		// make this scale by the number of peers we have. For large
		// scale clients, we would have more peers, and allow a higher
		// threshold for the number of partials
		// the second condition is to make sure we cap the number of partial
		// _bytes_. The larger the pieces are, the fewer partial pieces we want.
		// 2048 corresponds to 32 MiB
		const int num_partials = int(m_downloads[piece_pos::piece_downloading].size());
		if (num_partials > num_peers * 3 / 2
			|| num_partials * blocks_per_piece() > 2048)
		{
			// if we have too many partial pieces, prioritize completing
			// them. In order for this to have an affect, also disable
			// prefer whole pieces (otherwise partial pieces would be de-prioritized)
			options |= prioritize_partials;
			prefer_contiguous_blocks = 0;

			ret |= picker_log_alert::partial_ratio;
		}

		if (prefer_contiguous_blocks) ret |= picker_log_alert::prefer_contiguous;

		// only one of rarest_first and sequential can be set.
		TORRENT_ASSERT(((options & rarest_first) ? 1 : 0)
			+ ((options & sequential) ? 1 : 0) <= 1);
#ifdef TORRENT_EXPENSIVE_INVARIANT_CHECKS
		INVARIANT_CHECK;
#endif
		TORRENT_ASSERT(num_blocks > 0);
		TORRENT_ASSERT(pieces.size() == int(m_piece_map.size()));

		TORRENT_ASSERT(!m_priority_boundaries.empty() || m_dirty);

		// this will be filled with blocks that we should not request
		// unless we can't find num_blocks among the other ones.
		std::vector<piece_block> backup_blocks;
		std::vector<piece_index_t> ignored_pieces;

```

--------------------------------

### Install Python module with b2

Source: https://www.libtorrent.org/python_binding.html

Install the Python module to the default python user site. Use python-install-scope to change the installation scope.

```shell
b2 release python=3.7 install_module
```

--------------------------------

### Customize libtorrent build with b2-args

Source: https://www.libtorrent.org/python_binding.html

Customizes the build by passing b2 arguments through the build_ext step. This example sets the toolset and link flags.

```bash
python setup.py build_ext --b2-args="toolset=msvc-14.2 linkflags=-L../../src/.libs"

```

--------------------------------

### DHT put test cleanup and dht_dual_stack node setup

Source: https://www.libtorrent.org/todo.html

Shows the tail of a DHT put test and the start of the dht_dual_stack test. The put test verifies that after sending a response from the farthest node, exactly one put is counted and eight packets remain outstanding. The dual-stack test sets up two DHT nodes (IPv4 and IPv6) with a get_foreign_node callback and seeds both tables with the same node ID on different endpoints.

```cpp
			args.nodes({nodes[8]});

		send_dht_response(t.dht_node, response, nodes[i].ep(), args);
		g_sent_packets.erase(packet);

		// once we've sent the response from the farthest node, we're done
		if (i == 0) break;
	}

	TEST_EQUAL(g_put_count, 1);
	// k nodes should now have outstanding put requests
	TEST_EQUAL(g_sent_packets.size(), 8);

	g_sent_packets.clear();
	g_put_item.clear();
	g_put_count = 0;
}

TORRENT_TEST(dht_dual_stack)
{
	auto sett = test_settings();
	mock_socket s;
	auto sock4 = dummy_listen_socket4();
	auto sock6 = dummy_listen_socket6();
	obs observer;
	counters cnt;
	node* node4p = nullptr, *node6p = nullptr;
	auto get_foreign_node = [&](node_id const&, string_view const family)
	{
		if (family == "n4") return node4p;
		if (family == "n6") return node6p;
		TEST_CHECK(false);
		return static_cast<node*>(nullptr);
	};
	std::unique_ptr<dht_storage_interface> dht_storage(dht_default_storage_constructor(sett));
	dht_storage->update_node_ids({node_id(nullptr)});
	dht::node node4(sock4, &s, sett, node_id(nullptr), &observer, cnt, get_foreign_node, *dht_storage);
	dht::node node6(sock6, &s, sett, node_id(nullptr), &observer, cnt, get_foreign_node, *dht_storage);
	node4p = &node4;
	node6p = &node6;

	// DHT should be running on port 48199 now
	bdecode_node response;
	char error_string[200];
	bool ret;

	node_id id = to_hash("3123456789abcdef01232456789abcdef0123456");
	node4.m_table.node_seen(id, udp::endpoint(addr("4.4.4.4"), 4440), 10);
	node6.m_table.node_seen(id, udp::endpoint(addr("4::4"), 4441), 10);

	// v4 node requesting v6 nodes

```

--------------------------------

### get message

Source: https://www.libtorrent.org/dht_store.html

API documentation for the get message used to retrieve immutable items from the DHT.

```APIDOC
## [get] get message

### Description
Sends a get message to retrieve an immutable item from the DHT by its SHA-1 hash. The response includes the item, a write token, and nodes close to the target.

### Method
get

### Endpoint
get message

### Parameters
#### Request Body
- **a** (object) - Required - Contains the request arguments.
  - **id** (string) - Required - 20 byte id of sending node.
  - **target** (string) - Required - SHA-1 hash of the item to retrieve.
- **t** (string) - Required - Transaction-id.
- **y** (string) - Required - Must be "q" for query.
- **q** (string) - Required - Must be "get".

### Request Example
{
  "a": {
    "id": "<20 byte id of sending node>",
    "target": "<SHA-1 hash of item>"
  },
  "t": "<transaction-id>",
  "y": "q",
  "q": "get"
}

### Response
#### Success Response
- **r** (object) - Contains the response data.
  - **id** (string) - 20 byte id of sending node.
  - **token** (string) - Write token.
  - **v** (any bencoded type) - The item whose SHA-1 hash matches 'target'.
  - **nodes** (string) - IPv4 nodes close to 'target'.
  - **nodes6** (string) - IPv6 nodes close to 'target'.
- **t** (string) - Transaction-id.
- **y** (string) - Must be "r" for response.

#### Response Example
{
  "r": {
    "id": "<20 byte id of sending node>",
    "token": "<write token>",
    "v": "<any bencoded type whose SHA-1 hash matches 'target'>",
    "nodes": "<IPv4 nodes close to 'target'>",
    "nodes6": "<IPv6 nodes close to 'target'>"
  },
  "t": "<transaction-id>",
  "y": "r"
}
```

--------------------------------

### client_test command-line usage

Source: https://www.libtorrent.org/client_test.html

Shows the command-line syntax for starting the client_test program with one or more torrent files. The program accepts any number of torrent files as arguments.

```text
client_test <filename1.torrent> <filename2.torrent> ...

```

--------------------------------

### alert_category::peer

Source: https://www.libtorrent.org/include/libtorrent/alert.hpp

Enables alerts when peers send invalid requests, get banned, or get snubbed.

```APIDOC
## [GET] /alert_category/peer

### Description
Enables alerts when peers send invalid requests, get banned, or get snubbed.

### Method
GET

### Endpoint
/alert_category/peer

### Parameters
None

### Response
#### Success Response (200)
- **value** (bit) - The bit flag value.

#### Response Example
{
  "value": 2
}
```

--------------------------------

### libtorrent magnet URI download with resume data

Source: https://www.libtorrent.org/tutorial-ref.html

Complete libtorrent example that adds a torrent from a magnet URI, monitors alerts, saves resume data, and prints download progress. Requires a magnet URL as the sole command-line argument; exits with usage message if missing. Saves resume data to .resume_file and periodically every 30 seconds, and prints progress updates every 200 ms.

```cpp
#include <iostream>
#include <thread>
#include <chrono>
#include <fstream>

#include <libtorrent/session.hpp>
#include <libtorrent/session_params.hpp>
#include <libtorrent/add_torrent_params.hpp>
#include <libtorrent/torrent_handle.hpp>
#include <libtorrent/alert_types.hpp>
#include <libtorrent/bencode.hpp>
#include <libtorrent/torrent_status.hpp>
#include <libtorrent/read_resume_data.hpp>
#include <libtorrent/write_resume_data.hpp>
#include <libtorrent/error_code.hpp>
#include <libtorrent/magnet_uri.hpp>

namespace {

using clk = std::chrono::steady_clock;

// return the name of a torrent status enum
char const* state(lt::torrent_status::state_t s)
{
#ifdef __clang__
#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wcovered-switch-default"
#endif
  switch(s) {
    case lt::torrent_status::checking_files: return "checking";
    case lt::torrent_status::downloading_metadata: return "dl metadata";
    case lt::torrent_status::downloading: return "downloading";
    case lt::torrent_status::finished: return "finished";
    case lt::torrent_status::seeding: return "seeding";
    case lt::torrent_status::checking_resume_data: return "checking resume";
    default: return "<>";
  }
#ifdef __clang__
#pragma clang diagnostic pop
#endif
}

} // anonymous namespace

int main(int argc, char const* argv[]) try
{
  if (argc != 2) {
    std::cerr << "usage: " << argv[0] << " <magnet-url>" << std::endl;
    return 1;
  }

  lt::settings_pack pack;
  pack.set_int(lt::settings_pack::alert_mask
    , lt::alert_category::error
    | lt::alert_category::storage
    | lt::alert_category::status);

  lt::session ses(pack);
  clk::time_point last_save_resume = clk::now();

  // load resume data from disk and pass it in as we add the magnet link
  std::ifstream ifs(".resume_file", std::ios_base::binary);
  ifs.unsetf(std::ios_base::skipws);
  std::vector<char> buf{std::istream_iterator<char>(ifs)
    , std::istream_iterator<char>()};

  lt::add_torrent_params magnet = lt::parse_magnet_uri(argv[1]);
  if (buf.size()) {
    lt::add_torrent_params atp = lt::read_resume_data(buf);
    if (atp.info_hashes == magnet.info_hashes) magnet = std::move(atp);
  }
  magnet.save_path = "."; // save in current dir
  ses.async_add_torrent(std::move(magnet));

  // this is the handle we'll set once we get the notification of it being
  // added
  lt::torrent_handle h;

  // set when we're exiting
  bool done = false;
  for (;;) {
    std::vector<lt::alert*> alerts;
    ses.pop_alerts(&alerts);

    for (lt::alert const* a : alerts) {
      if (auto at = lt::alert_cast<lt::add_torrent_alert>(a)) {
        h = at->handle;
      }
      // if we receive the finished alert or an error, we're done
      if (lt::alert_cast<lt::torrent_finished_alert>(a)) {
        h.save_resume_data(lt::torrent_handle::only_if_modified
          | lt::torrent_handle::save_info_dict);
        done = true;
      }
      if (lt::alert_cast<lt::torrent_error_alert>(a)) {
        std::cout << a->message() << std::endl;
        done = true;
        h.save_resume_data(lt::torrent_handle::only_if_modified
          | lt::torrent_handle::save_info_dict);
      }

      // when resume data is ready, save it
      if (auto rd = lt::alert_cast<lt::save_resume_data_alert>(a)) {
        std::ofstream of(".resume_file", std::ios_base::binary);
        of.unsetf(std::ios_base::skipws);
        auto const b = write_resume_data_buf(rd->params);
        of.write(b.data(), int(b.size()));
        if (done) goto done;
      }

      if (lt::alert_cast<lt::save_resume_data_failed_alert>(a)) {
        if (done) goto done;
      }

      if (auto st = lt::alert_cast<lt::state_update_alert>(a)) {
        if (st->status.empty()) continue;

        // we only have a single torrent, so we know which one
        // the status is for
        lt::torrent_status const& s = st->status[0];
        std::cout << '\r' << state(s.state) << ' '
          << (s.download_payload_rate / 1000) << " kB/s "
          << (s.total_done / 1000) << " kB ("
          << (s.progress_ppm / 10000) << "%) downloaded ("
          << s.num_peers << " peers)\x1b[K";
        std::cout.flush();
      }
    }
    std::this_thread::sleep_for(std::chrono::milliseconds(200));

    // ask the session to post a state_update_alert, to update our
    // state output for the torrent
    ses.post_torrent_updates();

    // save resume data once every 30 seconds
    if (clk::now() - last_save_resume > std::chrono::seconds(30)) {
      h.save_resume_data(lt::torrent_handle::only_if_modified
        | lt::torrent_handle::save_info_dict);
      last_save_resume = clk::now();
    }
  }

done:
  std::cout << "\ndone, shutting down" << std::endl;
}
catch (std::exception& e)
{
  std::cerr << "Error: " << e.what() << std::endl;
}

```

--------------------------------

### set_alert_fd and Example Usage

Source: https://www.libtorrent.org/python_binding.html

Documentation for the Python-specific set_alert_fd function and an example usage of the libtorrent Python bindings.

```APIDOC
## set_alert_fd

### Description
Sets a file descriptor that will have 1 byte written to it to notify the client that there are new alerts to be popped. This is the Python-compatible alternative to `set_alert_notify()`, which is not compatible with Python due to potential deadlocks.

### Method
N/A (function call)

### Endpoint
N/A (function call)

### Parameters
- **fd** (int) - Required - The file descriptor to be written to when new alerts are available. The file descriptor should be set to non-blocking mode to avoid stalling libtorrent's internal thread.

### Request Example
N/A

### Response
N/A

### Notes
- The file descriptor should be set to non-blocking mode.
- Can be used with `socket.socketpair()`, for example. The file descriptor is what `fileno()` returns on a socket.

## Example Usage

### Description
A simple example of using the libtorrent Python bindings to download a torrent and monitor its progress.

### Code
```python
import sys
import time

import libtorrent as lt

ses = lt.session({"listen_interfaces": "0.0.0.0:6881"})

atp = lt.add_torrent_params()
atp.ti = lt.torrent_info(sys.argv[1])
atp.save_path = "."
h = ses.add_torrent(atp)
s = h.status()
print("starting", s.name)

while not s.is_seeding:
    s = h.status()

    print(
        "\r%.2f%% complete (down: %.1f kB/s up: %.1f kB/s peers: %d) %s"
        % (
            s.progress * 100,
            s.download_rate / 1000,
            s.upload_rate / 1000,
            s.num_peers,
            s.state,
        ),
        end=" ",
    )

    alerts = ses.pop_alerts()
    for a in alerts:
        if a.category() & lt.alert.category_t.error_notification:
            print(a)

    sys.stdout.flush()

    time.sleep(1)

print(h.status().name, "complete")
```
```

--------------------------------

### Install Python module to custom path

Source: https://www.libtorrent.org/python_binding.html

Install the Python module to a custom path using the python-install-path feature.

```shell
b2 release python=3.7 install_module python-install-path=/home/foobar/python-site/
```

--------------------------------

### Build libtorrent for a specific Python version

Source: https://www.libtorrent.org/python_binding.html

Builds the bindings for a specific Python version by invoking setup.py with that interpreter. The example shows building for python3.7.

```bash
# build for python3.7
python3.7 setup.py build
# build for python3.7
python3.7 setup.py build

```

--------------------------------

### get

Source: https://www.libtorrent.org/dht_store.html

The get message retrieves a stored value from the DHT. It sends a target hash and receives the value, signature, and related metadata.

```APIDOC
## get

### Description
The get message is used to retrieve a stored value from the DHT. It sends a target hash and receives the value, signature, and related metadata.

### Method
q (query)

### Endpoint
Not applicable (DHT message)

### Parameters
#### Request Body
- **a** (object) - Required - The arguments object containing:
  - **id** (string) - Required - 20 byte id of sending node
  - **target** (string) - Required - 20 byte SHA-1 hash of public key and salt
- **t** (string) - Required - transaction-id
- **y** (string) - Required - "q"
- **q** (string) - Required - "get"

### Request Example
{
  "a": {
    "id": "<20 byte id of sending node>",
    "target": "<20 byte SHA-1 hash of public key and salt>"
  },
  "t": "<transaction-id>",
  "y": "q",
  "q": "get"
}

### Response
#### Success Response
- **r** (object) - The response object containing:
  - **id** (string) - 20 byte id of sending node
  - **k** (string) - ed25519 public key (32 bytes string)
  - **nodes** (string) - IPv4 nodes close to 'target'
  - **nodes6** (string) - IPv6 nodes close to 'target'
  - **seq** (integer) - monotonically increasing sequence number
  - **sig** (string) - ed25519 signature (64 bytes string)
  - **token** (string) - write-token
  - **v** (any) - any bencoded type, whose encoded size <= 1000
- **t** (string) - transaction-id
- **y** (string) - "r"

#### Response Example
{
  "r": {
    "id": "<20 byte id of sending node>",
    "k": "<ed25519 public key>",
    "nodes": "<IPv4 nodes>",
    "nodes6": "<IPv6 nodes>",
    "seq": 1,
    "sig": "<ed25519 signature>",
    "token": "<write-token>",
    "v": "<value>"
  },
  "t": "<transaction-id>",
  "y": "r"
}

### Signature Verification
On the storage node, the signature MUST be verified before accepting the store command. The data MUST be stored under the SHA-1 hash of the public key and the salt (if present). On the requesting nodes, the key they get back from a `get` request MUST be verified to hash to the target ID the lookup was made for, as well as verifying the signature. If any of these fail, the response SHOULD be considered invalid.
```

--------------------------------

### session::start() applying session_params flags

Source: https://www.libtorrent.org/todo.html

Code from session.cpp:261 showing how session::start() applies flags from the session_params object. It uses SET_BOOL and SET_INT macros to copy DHT and settings flags, then constructs the session_impl, loads extensions and DHT state, sets an IP filter if provided, and starts the session.

```cpp
		SET_BOOL(restrict_routing_ips);
		SET_BOOL(restrict_search_ips);
		SET_BOOL(extended_routing_table);
		SET_BOOL(aggressive_lookups);
		SET_BOOL(privacy_lookups);
		SET_BOOL(enforce_node_id);
		SET_BOOL(ignore_dark_internet);
		SET_INT(block_timeout);
		SET_INT(block_ratelimit);
		SET_BOOL(read_only);
		SET_INT(item_lifetime);
		SET_INT(upload_rate_limit);
		SET_INT(sample_infohashes_interval);
		SET_INT(max_infohashes_sample_count);
#undef SET_BOOL
#undef SET_INT
		}
#endif
#endif

		m_impl = std::make_shared<aux::session_impl>(std::ref(*ios)
			, std::move(params.settings)
			, std::move(params.disk_io_constructor)
			, flags);
		*static_cast<session_handle*>(this) = session_handle(m_impl);

#ifndef TORRENT_DISABLE_EXTENSIONS
		for (auto& ext : params.extensions)
		{
			ext->load_state(params.ext_state);
			m_impl->add_ses_extension(std::move(ext));
		}
#endif

#ifndef TORRENT_DISABLE_DHT
		m_impl->set_dht_state(std::move(params.dht_state));

		TORRENT_ASSERT(params.dht_storage_constructor);
		m_impl->set_dht_storage(std::move(params.dht_storage_constructor));
#endif

		if (!params.ip_filter.empty())
		{
			std::shared_ptr<ip_filter> copy = std::make_shared<ip_filter>(std::move(params.ip_filter));
			m_impl->set_ip_filter(std::move(copy));
		}

		m_impl->start_session();

		if (internal_executor)
		{

```

--------------------------------

### Exception handling wrapper and start_session() beginning (session_impl.cpp:566)

Source: https://www.libtorrent.org/todo.html

Shows a try-catch block that catches system_error, std::exception, and unknown errors, posting alerts and pausing. Also shows the beginning of session_impl::start_session() with SSL setup. The comment asks if this could be moved into init() and posted to the io_context.

```cpp
	try
#endif
	{
		(this->*f)(std::forward<Args>(a)...);
	}
#ifndef BOOST_NO_EXCEPTIONS
	catch (system_error const& e) {
		alerts().emplace_alert<session_error_alert>(e.code(), e.what());
		pause();
	} catch (std::exception const& e) {
		alerts().emplace_alert<session_error_alert>(error_code(), e.what());
		pause();
	} catch (...) {
		alerts().emplace_alert<session_error_alert>(error_code(), "unknown error");
		pause();
	}
#endif

	// This function is called by the creating thread, not in the message loop's
	// io_context thread.
	void session_impl::start_session()
	{
#ifndef TORRENT_DISABLE_LOGGING
		session_log("start session");
#endif

#if TORRENT_USE_SSL
		error_code ec;
		m_ssl_ctx.set_default_verify_paths(ec);
#ifndef TORRENT_DISABLE_LOGGING
		if (ec) session_log("SSL set_default verify_paths failed: %s", ec.message().c_str());
		ec.clear();
#endif
#if defined TORRENT_WINDOWS && defined TORRENT_USE_OPENSSL && !defined TORRENT_WINRT

```

--------------------------------

### Immutable get response

Source: https://www.libtorrent.org/dht_store.html

Response to a get request, including the value, a write token, and lists of close IPv4 and IPv6 nodes.

```json
{
        "r":
        {
                "id": _<20 byte id of sending node (string)>_,
                "token": _<write token (string)>_,
                "v": _<any bencoded type whose SHA-1 hash matches 'target'>_,
                "nodes": _<IPv4 nodes close to 'target'>_,
                "nodes6": _<IPv6 nodes close to 'target'>_
        },
        "t": _<transaction-id>_,
        "y": "r",
}

```

--------------------------------

### Create torrent with new API

Source: https://www.libtorrent.org/upgrade_to_2.1-ref.html

Builds a file list from a directory, creates a torrent, adds a tracker, sets the creator, calculates piece hashes, and writes the torrent file. Use this to create a torrent with the new API.

```cpp
// recursively create a list of all files in the directory
auto files = list_files("./my_torrent");

create_torrent t(std::move(files));
t.add_tracker("http://my.tracker.com/announce");
t.set_creator("libtorrent example");

// reads the files and calculates the hashes
set_piece_hashes(t, ".");

ofstream out("my_torrent.torrent", std::ios_base::binary);
bencode(std::ostream_iterator<char>(out), t.generate());
```

--------------------------------

### Install Python module system-wide

Source: https://www.libtorrent.org/python_binding.html

Install the Python module to the system site instead of the user site. The python-install-scope feature accepts 'user' (default) and 'system'.

```shell
b2 release python=3.7 install_module python-install-scope=system
```
Tokens:
Raw