Qt wrapper around a libtorrent session. More...

#include <torrentclient.h>

Inheritance diagram for TorrentClient:

Collaboration diagram for TorrentClient:

Public Types
enum	EncryptionMode { EncryptionEnabled , EncryptionForced , EncryptionDisabled }
	Peer connection encryption policy. More...

Signals
void	torrentAdded (Torrent *torrent)
	Emitted after a torrent is successfully added to the session.

void	torrentRemoved (const QByteArray &infoHash)
	Emitted after a torrent is removed.

void	torrentStateChanged (Torrent *torrent, Torrent::State state)
	Emitted when any torrent transitions to a new state.

void	torrentComplete (Torrent *torrent)
	Emitted when a torrent finishes downloading and enters seeding.

void	listenSucceeded (const QString &address, int port)
	Emitted when the session begins listening on an interface.

void	listenFailed (const QString &address, int port, const QString &error)
	Emitted when binding to a listen interface fails.

void	externalAddressDetected (const QString &address)
	Emitted when the session's external (public) IP is detected.

void	dhtBootstrapComplete ()
	Emitted when the DHT routing table is initially populated.

void	sessionStatsReceived (const SessionStats &stats)
	Emitted in response to requestSessionStats().

void	resumeDataSaved (const QByteArray &infoHash)
	Emitted when a torrent's resume data is successfully written to disk.

void	resumeDataFailed (const QByteArray &infoHash, const QString &error)
	Emitted when saving resume data for a torrent fails.

Public Member Functions
	TorrentClient (QObject *parent=nullptr)
	Construct a TorrentClient with DHT and LSD enabled by default.

Torrent *	addTorrent (const MagnetLink &magnetLink, const QString &downloadDirectory=QString())
	Add a torrent from a magnet link.

Torrent *	addTorrent (const QString &torrentFilePath, const QString &downloadDirectory=QString())
	Add a torrent from a .torrent file on disk.

Torrent *	addTorrent (const QByteArray &torrentData, const QString &downloadDirectory=QString())
	Add a torrent from raw .torrent file bytes.

void	removeTorrent (Torrent *torrent, bool deleteFiles=false)
	Remove a torrent from the session.

QList< Torrent * >	torrents () const
	Return all managed torrents.

Torrent *	findTorrent (const QByteArray &infoHash) const
	Find a torrent by its 20-byte SHA-1 info hash.

QString	defaultDownloadDirectory () const
	Default save path for new torrents when no override is given.

void	setDefaultDownloadDirectory (const QString &value)
	Set the default save path for new torrents.

QNetworkProxy	networkProxy () const
	Current SOCKS5 proxy configuration.

void	setNetworkProxy (const QNetworkProxy &value)
	Route all libtorrent traffic through a SOCKS5 proxy.

int	downloadRateLimit () const
	Global download rate limit in bytes/sec.

void	setDownloadRateLimit (int bytesPerSecond)
	Set the global download rate limit in bytes/sec.

int	uploadRateLimit () const
	Global upload rate limit in bytes/sec.

void	setUploadRateLimit (int bytesPerSecond)
	Set the global upload rate limit in bytes/sec.

int	maxConnections () const
	Maximum number of simultaneous connections across all torrents.

void	setMaxConnections (int value)
	Set the global connection limit.

int	maxUploads () const
	Maximum number of unchoke slots (upload slots).

void	setMaxUploads (int value)
	Set the maximum number of unchoke slots.

QString	listenInterfaces () const
	Current listen interface string.

void	setListenInterfaces (const QString &value)
	Set the listen interfaces for incoming connections.

bool	isDhtEnabled () const
	Whether the Distributed Hash Table (DHT) is enabled.

void	setDhtEnabled (bool enabled)
	Enable or disable DHT.

bool	isLsdEnabled () const
	Whether Local Service Discovery (LSD) is enabled.

void	setLsdEnabled (bool enabled)
	Enable or disable LSD.

EncryptionMode	encryptionMode () const
	Current peer connection encryption policy.

void	setEncryptionMode (EncryptionMode mode)
	Set the peer connection encryption policy.

QString	userAgent () const
	The user-agent string sent to trackers and peers.

void	setUserAgent (const QString &value)
	Set the user-agent string.

SessionStats	sessionStats () const
	Compute an aggregate snapshot of session statistics.

void	requestSessionStats ()
	Post an asynchronous session-stats request to libtorrent.

void	addIpFilter (const QHostAddress &first, const QHostAddress &last)
	Block a range of IP addresses.

void	removeIpFilter (const QHostAddress &first, const QHostAddress &last)
	Remove a previously added IP filter range.

int	loadBlocklist (const QString &filePath)
	Load a P2P-format blocklist from a file.

void	clearIpFilter ()
	Remove all IP filter rules, allowing all addresses.

QString	resumeDataDirectory () const
	Directory where .fastresume files are stored.

void	setResumeDataDirectory (const QString &path)
	Set the resume-data directory and create it if it doesn't exist.

void	saveAllResumeData ()
	Request resume-data saves for every managed torrent.

void	loadResumeData ()
	Scan the resume-data directory and re-add all found torrents.

void	startAll ()
	Resume all paused/stopped torrents.

void	stopAll ()
	Pause all active torrents.

void	processAlerts ()
	Process pending libtorrent alerts.

Detailed Description

Qt wrapper around a libtorrent session.

TorrentClient owns the underlying libtorrent session and manages the lifecycle of all Torrent objects added to it. It polls for libtorrent alerts on a 500 ms timer and translates them into Qt signals.

Typical usage:

auto* client = new TorrentClient(this);
client->setDefaultDownloadDirectory("/tmp/downloads");
client->setResumeDataDirectory("/tmp/resume");
client->loadResumeData();
 
Torrent* t = client->addTorrent(MagnetLink(uri));
connect(t, &Torrent::downloadComplete, this, &MyApp::onDone);

Definition at line 32 of file torrentclient.h.

Member Enumeration Documentation

◆ EncryptionMode

enum TorrentClient::EncryptionMode

Peer connection encryption policy.

Enumerator
EncryptionEnabled	Prefer encrypted connections, allow plaintext fallback.
EncryptionForced	Require encryption; reject plaintext peers.
EncryptionDisabled	Disable encryption entirely.

Definition at line 40 of file torrentclient.h.

Constructor & Destructor Documentation

◆ TorrentClient()

TorrentClient::TorrentClient ( QObject * parent = nullptr )

explicit

Construct a TorrentClient with DHT and LSD enabled by default.

Parameters

parent Optional QObject parent.

Member Function Documentation

◆ addIpFilter()

void TorrentClient::addIpFilter	(	const QHostAddress &	first,
		const QHostAddress &	last
	)

Block a range of IP addresses.

Peers connecting from addresses in the range will be rejected. Call with the same start and end to block a single address.

Parameters

first	Start of the IP range (inclusive).
last	End of the IP range (inclusive).

◆ addTorrent() [1/3]

Torrent * TorrentClient::addTorrent	(	const MagnetLink &	magnetLink,
		const QString &	downloadDirectory = `QString()`
	)

Add a torrent from a magnet link.

Parameters

magnetLink	The parsed magnet link.
downloadDirectory	Save path override. Uses defaultDownloadDirectory() if empty.

Returns: Pointer to the new Torrent, or nullptr if a duplicate or invalid.

◆ addTorrent() [2/3]

Torrent * TorrentClient::addTorrent	(	const QByteArray &	torrentData,
		const QString &	downloadDirectory = `QString()`
	)

Add a torrent from raw .torrent file bytes.

Parameters

torrentData	The bencoded torrent data.
downloadDirectory	Save path override. Uses defaultDownloadDirectory() if empty.

Returns: Pointer to the new Torrent, or nullptr on failure.

◆ addTorrent() [3/3]

Torrent * TorrentClient::addTorrent	(	const QString &	torrentFilePath,
		const QString &	downloadDirectory = `QString()`
	)

Add a torrent from a .torrent file on disk.

Parameters

torrentFilePath	Path to the .torrent file.
downloadDirectory	Save path override. Uses defaultDownloadDirectory() if empty.

Returns: Pointer to the new Torrent, or nullptr on failure.

◆ defaultDownloadDirectory()

QString TorrentClient::defaultDownloadDirectory ( ) const

inline

Default save path for new torrents when no override is given.

Definition at line 102 of file torrentclient.h.

◆ downloadRateLimit()

int TorrentClient::downloadRateLimit ( ) const

Global download rate limit in bytes/sec.

0 means unlimited.

◆ findTorrent()

Torrent * TorrentClient::findTorrent ( const QByteArray & infoHash ) const

Find a torrent by its 20-byte SHA-1 info hash.

Parameters

infoHash Raw 20-byte hash.

Returns: Matching Torrent pointer, or nullptr if not found.

◆ listenInterfaces()

QString TorrentClient::listenInterfaces ( ) const

Current listen interface string.

Format: "address:port" pairs, comma-separated. Example: "0.0.0.0:6881,[::]:6881"

◆ loadBlocklist()

int TorrentClient::loadBlocklist ( const QString & filePath )

Load a P2P-format blocklist from a file.

Supports the widely-used P2P plaintext format where each line is: "description:startIP-endIP". Lines starting with # are ignored.

Parameters

filePath Path to the blocklist file.

Returns: Number of ranges loaded, or -1 on file error.

◆ loadResumeData()

void TorrentClient::loadResumeData ( )

Scan the resume-data directory and re-add all found torrents.

Call this at startup after setResumeDataDirectory() to restore the previous session state.

◆ maxConnections()

int TorrentClient::maxConnections ( ) const

Maximum number of simultaneous connections across all torrents.

0 = unlimited.

◆ maxUploads()

int TorrentClient::maxUploads ( ) const

Maximum number of unchoke slots (upload slots).

0 = unlimited.

◆ networkProxy()

QNetworkProxy TorrentClient::networkProxy ( ) const

inline

Current SOCKS5 proxy configuration.

Definition at line 109 of file torrentclient.h.

◆ processAlerts()

void TorrentClient::processAlerts ( )

Process pending libtorrent alerts.

Called automatically every 500 ms by an internal timer. Can also be called manually for tighter polling. Translates libtorrent alerts into the appropriate Qt signals on TorrentClient and Torrent.

◆ removeIpFilter()

void TorrentClient::removeIpFilter	(	const QHostAddress &	first,
		const QHostAddress &	last
	)

Remove a previously added IP filter range.

Parameters

first	Start of the IP range (inclusive).
last	End of the IP range (inclusive).

◆ removeTorrent()

void TorrentClient::removeTorrent	(	Torrent *	torrent,
		bool	deleteFiles = `false`
	)

Remove a torrent from the session.

Parameters

torrent	The torrent to remove. Becomes invalid after this call.
deleteFiles	If `true`, also delete downloaded data from disk.

◆ requestSessionStats()

void TorrentClient::requestSessionStats ( )

Post an asynchronous session-stats request to libtorrent.

When the stats are ready, the sessionStatsReceived() signal is emitted.

◆ resumeDataDirectory()

QString TorrentClient::resumeDataDirectory ( ) const

inline

Directory where .fastresume files are stored.

Definition at line 239 of file torrentclient.h.

◆ saveAllResumeData()

void TorrentClient::saveAllResumeData ( )

Request resume-data saves for every managed torrent.

Each torrent's resume data is written asynchronously. The resumeDataSaved() or resumeDataFailed() signal fires per torrent once the save completes.

◆ sessionStats()

SessionStats TorrentClient::sessionStats ( ) const

Compute an aggregate snapshot of session statistics.

Iterates all managed torrents and sums their transfer totals, rates, and peer counts. Also queries the DHT routing table size.

Returns: A SessionStats value object.

◆ setDefaultDownloadDirectory()

void TorrentClient::setDefaultDownloadDirectory ( const QString & value )

inline

Set the default save path for new torrents.

Definition at line 104 of file torrentclient.h.

◆ setDownloadRateLimit()

void TorrentClient::setDownloadRateLimit ( int bytesPerSecond )

Set the global download rate limit in bytes/sec.

Pass 0 for unlimited.

◆ setListenInterfaces()

void TorrentClient::setListenInterfaces ( const QString & value )

Set the listen interfaces for incoming connections.

Parameters

value Comma-separated "address:port" pairs.

◆ setNetworkProxy()

void TorrentClient::setNetworkProxy ( const QNetworkProxy & value )

Route all libtorrent traffic through a SOCKS5 proxy.

Supports both plain SOCKS5 and SOCKS5 with username/password authentication. Pass a default-constructed QNetworkProxy to disable.

Parameters

value The proxy configuration.

◆ setResumeDataDirectory()

void TorrentClient::setResumeDataDirectory ( const QString & path )

Set the resume-data directory and create it if it doesn't exist.

Parameters

path	Filesystem path for .fastresume files.

◆ setUploadRateLimit()

void TorrentClient::setUploadRateLimit ( int bytesPerSecond )

Set the global upload rate limit in bytes/sec.

Pass 0 for unlimited.

◆ torrentRemoved

void TorrentClient::torrentRemoved ( const QByteArray & infoHash )

signal

Emitted after a torrent is removed.

infoHash identifies the removed torrent.

◆ torrents()

QList< Torrent * > TorrentClient::torrents ( ) const

inline

Return all managed torrents.

Definition at line 90 of file torrentclient.h.

◆ uploadRateLimit()

int TorrentClient::uploadRateLimit ( ) const

Global upload rate limit in bytes/sec.

0 means unlimited.

The documentation for this class was generated from the following file:

include/Kanoop/torrent/torrentclient.h

Public Types

Signals

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ EncryptionMode

Constructor & Destructor Documentation

◆ TorrentClient()

Member Function Documentation

◆ addIpFilter()

◆ addTorrent() [1/3]

◆ addTorrent() [2/3]

◆ addTorrent() [3/3]

◆ defaultDownloadDirectory()

◆ downloadRateLimit()

◆ findTorrent()

◆ listenInterfaces()

◆ loadBlocklist()

◆ loadResumeData()

◆ maxConnections()

◆ maxUploads()

◆ networkProxy()

◆ processAlerts()

◆ removeIpFilter()

◆ removeTorrent()

◆ requestSessionStats()

◆ resumeDataDirectory()

◆ saveAllResumeData()

◆ sessionStats()

◆ setDefaultDownloadDirectory()

◆ setDownloadRateLimit()

◆ setListenInterfaces()

◆ setNetworkProxy()

◆ setResumeDataDirectory()

◆ setUploadRateLimit()

◆ torrentRemoved

◆ torrents()

◆ uploadRateLimit()