Represents a single torrent within a TorrentClient session. More...

#include <torrent.h>

Inheritance diagram for Torrent:

Collaboration diagram for Torrent:

Public Types
enum	State { Idle , FetchingMetadata , Checking , Downloading , Seeding , Paused , Error }
	Lifecycle state of a torrent. More...

Signals
void	stateChanged (Torrent::State state)
	Emitted when the torrent transitions to a new State.

void	progressUpdated (double ratio)
	Emitted periodically during download with the current progress ratio (0.0–1.0).

void	fileCompleted (int fileIndex, const QString &filePath)
	Emitted when an individual file finishes downloading.

void	downloadComplete ()
	Emitted once when the entire torrent download completes.

void	metadataReceived ()
	Emitted when metadata is received (magnet links only).

void	error (const QString &message)
	Emitted on torrent errors (tracker failures, I/O errors, etc.).

void	trackerAnnounced (const QString &url)
	Emitted when a tracker announce succeeds.

void	trackerError (const QString &url, const QString &message)
	Emitted when a tracker announce fails.

void	storageMoved (const QString &newPath)
	Emitted when moveStorage() completes successfully.

void	storageMoveError (const QString &error)
	Emitted when moveStorage() fails.

void	fileRenamed (int fileIndex, const QString &newName)
	Emitted when renameFile() completes successfully.

void	fileRenameError (int fileIndex, const QString &error)
	Emitted when renameFile() fails.

Public Member Functions
	Torrent (QObject *parent=nullptr)

void	start ()
	Resume downloading/seeding.

void	stop ()
	Stop the torrent and reset state to Idle.

void	pause ()
	Pause the torrent, keeping its state recoverable via resume().

void	resume ()
	Resume a paused torrent.

State	state () const
	Current lifecycle state.

QString	name () const
	Human-readable torrent name.

QByteArray	infoHash () const
	Raw 20-byte SHA-1 info hash.

QString	infoHashHex () const
	Info hash as a lowercase hex string (40 characters).

double	progress () const
	Download progress as a ratio from 0.0 to 1.0.

qint64	bytesDownloaded () const
	Total bytes downloaded so far.

qint64	totalSize () const
	Total size of all selected files in bytes.

int	connectedPeers () const
	Number of currently connected peers.

qint64	downloadRate () const
	Current download rate in bytes/sec.

qint64	uploadRate () const
	Current upload rate in bytes/sec.

qint64	totalUploaded () const
	Total bytes uploaded over the lifetime of this torrent.

double	ratio () const
	Share ratio (uploaded / downloaded).

int	totalPieces () const
	Total number of pieces in this torrent.

int	downloadedPieces () const
	Number of pieces that have been downloaded and verified.

int	pieceSize () const
	Size of each piece in bytes.

int	eta () const
	Estimated seconds remaining until download completes.

bool	hasMetadata () const
	Whether torrent metadata has been received.

int	fileCount () const
	Number of files in the torrent.

QString	fileName (int index) const
	Relative path of a file within the torrent.

QStringList	fileNames () const
	List of all file paths in the torrent.

qint64	fileSize (int index) const
	Size of a file in bytes.

void	setFilePriority (int index, int priority)
	Set the download priority for a single file.

void	setAllFilePriorities (int priority)
	Set the same download priority for every file.

int	findFileByName (const QString &partialName) const
	Find a file by partial name (case-insensitive substring match).

int	filePriority (int index) const
	Get the current download priority for a file.

QList< qint64 >	fileProgress () const
	Get per-file download progress as a list of byte counts.

void	renameFile (int index, const QString &newName)
	Rename a file within the torrent.

QString	downloadDirectory () const
	The directory where this torrent's data is being saved.

QString	outputPath () const
	Full output path (save_path + torrent name).

void	moveStorage (const QString &newPath)
	Move the torrent's data to a new directory.

bool	isSequentialDownload () const
	Whether pieces are requested in sequential order.

void	setSequentialDownload (bool enabled)
	Enable or disable sequential piece downloading.

bool	isAutoManaged () const
	Whether libtorrent auto-manages this torrent's queue position.

void	setAutoManaged (bool enabled)
	Enable or disable libtorrent's auto-managed mode.

int	downloadLimit () const
	Per-torrent download rate limit in bytes/sec.

void	setDownloadLimit (int bytesPerSecond)
	Set the per-torrent download rate limit.

int	uploadLimit () const
	Per-torrent upload rate limit in bytes/sec.

void	setUploadLimit (int bytesPerSecond)
	Set the per-torrent upload rate limit.

int	maxConnections () const
	Maximum number of peer connections for this torrent.

void	setMaxConnections (int value)
	Set the maximum peer connections for this torrent.

int	maxUploads () const
	Maximum number of upload slots for this torrent.

void	setMaxUploads (int value)
	Set the maximum upload slots for this torrent.

double	seedRatioLimit () const
	Target share ratio after which the torrent is auto-paused.

void	setSeedRatioLimit (double ratio)
	Set a share-ratio target; the torrent pauses when it is reached.

QStringList	trackers () const
	List of tracker URLs currently attached to this torrent.

void	addTracker (const QString &url)
	Append a tracker URL.

void	removeTracker (const QString &url)
	Remove a tracker by URL.

void	forceReannounce ()
	Force an immediate re-announce to all trackers.

QList< PeerInfo >	peers () const
	Snapshot of all currently connected peers.

void	banPeer (const QHostAddress &address)
	Ban a peer by IP address.

void	saveResumeData ()
	Request an asynchronous resume-data save.

void	setHandle (void *handle)

void *	handle () const

void	setMagnetLink (const MagnetLink &link)

void	setInfoHash (const QByteArray &hash)

void	setDownloadDirectory (const QString &dir)

void	updateFromStatus ()

void	checkSeedRatio ()

Detailed Description

Represents a single torrent within a TorrentClient session.

Torrent objects are created by TorrentClient::addTorrent() and provide a Qt-friendly interface over a libtorrent torrent handle. All state updates are driven by TorrentClient::processAlerts() and delivered as Qt signals.

Note: Do not construct Torrent objects directly; use TorrentClient::addTorrent().

Definition at line 20 of file torrent.h.

Member Enumeration Documentation

◆ State

enum Torrent::State

Lifecycle state of a torrent.

Enumerator
Idle	Torrent is stopped or not yet started.
FetchingMetadata	Downloading torrent metadata (magnet link resolution).
Checking	Verifying existing data on disk.
Downloading	Actively downloading pieces.
Seeding	Download complete; uploading to peers.
Paused	Explicitly paused by the user.
Error	An unrecoverable error occurred.

Definition at line 28 of file torrent.h.

Member Function Documentation

◆ addTracker()

void Torrent::addTracker ( const QString & url )

Append a tracker URL.

Parameters

url	The tracker announce URL.

◆ banPeer()

void Torrent::banPeer ( const QHostAddress & address )

Ban a peer by IP address.

Adds the address to the session IP filter with a deny rule and disconnects the peer if currently connected. The ban persists for the lifetime of the session.

Parameters

address The peer's IP address to ban.

◆ downloadDirectory()

QString Torrent::downloadDirectory ( ) const

inline

The directory where this torrent's data is being saved.

Definition at line 192 of file torrent.h.

◆ downloadLimit()

int Torrent::downloadLimit ( ) const

Per-torrent download rate limit in bytes/sec.

0 = unlimited.

◆ eta()

int Torrent::eta ( ) const

Estimated seconds remaining until download completes.

Returns: Seconds remaining, or -1 if the rate is zero or unknown.

◆ fileCount()

int Torrent::fileCount ( ) const

Number of files in the torrent.

Requires metadata.

◆ fileName()

QString Torrent::fileName ( int index ) const

Relative path of a file within the torrent.

Parameters

index Zero-based file index.

Returns: Relative file path, or empty string if out of range.

◆ filePriority()

int Torrent::filePriority ( int index ) const

Get the current download priority for a file.

Parameters

index Zero-based file index.

Returns: Priority value (0 = skip, 1 = low, 4 = normal, 7 = highest), or -1 if invalid.

◆ fileProgress()

QList< qint64 > Torrent::fileProgress ( ) const

Get per-file download progress as a list of byte counts.

Returns: A list with one entry per file containing bytes downloaded so far. Empty list if no metadata is available.

◆ fileSize()

qint64 Torrent::fileSize ( int index ) const

Size of a file in bytes.

Parameters

index Zero-based file index.

Returns: File size, or 0 if out of range or no metadata.

◆ findFileByName()

int Torrent::findFileByName ( const QString & partialName ) const

Find a file by partial name (case-insensitive substring match).

Parameters

partialName Substring to search for.

Returns: Zero-based file index, or -1 if not found.

◆ handle()

void * Torrent::handle ( ) const

inline

Definition at line 319 of file torrent.h.

◆ hasMetadata()

bool Torrent::hasMetadata ( ) const

inline

Whether torrent metadata has been received.

File management methods require metadata. For magnet links, metadata is fetched from peers after the torrent is added.

Definition at line 121 of file torrent.h.

◆ infoHash()

QByteArray Torrent::infoHash ( ) const

inline

Raw 20-byte SHA-1 info hash.

Definition at line 67 of file torrent.h.

◆ infoHashHex()

QString Torrent::infoHashHex ( ) const

inline

Info hash as a lowercase hex string (40 characters).

Definition at line 69 of file torrent.h.

◆ moveStorage()

void Torrent::moveStorage ( const QString & newPath )

Move the torrent's data to a new directory.

The move is asynchronous. On completion, storageMoved() is emitted; on failure, storageMoveError() is emitted.

Parameters

newPath Destination directory.

◆ name()

QString Torrent::name ( ) const

Human-readable torrent name.

Returns the name from torrent metadata if available, otherwise falls back to the magnet link display name or a truncated info hash.

◆ outputPath()

QString Torrent::outputPath ( ) const

Full output path (save_path + torrent name).

For single-file torrents this is the file path; for multi-file torrents this is the containing directory.

◆ peers()

QList< PeerInfo > Torrent::peers ( ) const

Snapshot of all currently connected peers.

Each PeerInfo captures identity, transfer rates, progress, and flags at the time of the call. The list is not updated automatically; call again to refresh.

Returns: List of PeerInfo value objects.

◆ pieceSize()

int Torrent::pieceSize ( ) const

Size of each piece in bytes.

Requires metadata.

◆ ratio()

double Torrent::ratio ( ) const

Share ratio (uploaded / downloaded).

Returns: 0.0 if nothing has been downloaded yet.

◆ removeTracker()

void Torrent::removeTracker ( const QString & url )

Remove a tracker by URL.

Parameters

url	The tracker announce URL to remove.

◆ renameFile()

void Torrent::renameFile	(	int	index,
		const QString &	newName
	)

Rename a file within the torrent.

The rename is asynchronous. On completion, fileRenamed() is emitted; on failure, fileRenameError() is emitted.

Parameters

index	Zero-based file index.
newName	New relative path for the file.

◆ saveResumeData()

void Torrent::saveResumeData ( )

Request an asynchronous resume-data save.

The result arrives via TorrentClient::resumeDataSaved() or TorrentClient::resumeDataFailed().

◆ seedRatioLimit()

double Torrent::seedRatioLimit ( ) const

inline

Target share ratio after which the torrent is auto-paused.

Returns: 0.0 means no limit (seed indefinitely).

Definition at line 254 of file torrent.h.

◆ setAllFilePriorities()

void Torrent::setAllFilePriorities ( int priority )

Set the same download priority for every file.

Parameters

priority 0 = skip, 1 = low, 4 = normal, 7 = highest.

◆ setDownloadDirectory()

void Torrent::setDownloadDirectory ( const QString & dir )

inline

Definition at line 325 of file torrent.h.

◆ setDownloadLimit()

void Torrent::setDownloadLimit ( int bytesPerSecond )

Set the per-torrent download rate limit.

Pass 0 for unlimited.

◆ setFilePriority()

void Torrent::setFilePriority	(	int	index,
		int	priority
	)

Set the download priority for a single file.

Parameters

index	Zero-based file index.
priority	0 = skip, 1 = low, 4 = normal, 7 = highest.

◆ setInfoHash()

void Torrent::setInfoHash ( const QByteArray & hash )

inline

Definition at line 323 of file torrent.h.

◆ setMagnetLink()

void Torrent::setMagnetLink ( const MagnetLink & link )

inline

Definition at line 321 of file torrent.h.

◆ setSeedRatioLimit()

void Torrent::setSeedRatioLimit ( double ratio )

Set a share-ratio target; the torrent pauses when it is reached.

Parameters

ratio Target ratio (e.g. 1.0 = upload as much as downloaded). 0 = no limit.

◆ setSequentialDownload()

void Torrent::setSequentialDownload ( bool enabled )

Enable or disable sequential piece downloading.

Useful for streaming: the first pieces arrive before later ones, so playback can begin before the download finishes.

◆ setUploadLimit()

void Torrent::setUploadLimit ( int bytesPerSecond )

Set the per-torrent upload rate limit.

Pass 0 for unlimited.

◆ state()

State Torrent::state ( ) const

inline

Current lifecycle state.

Definition at line 54 of file torrent.h.

◆ totalPieces()

int Torrent::totalPieces ( ) const

Total number of pieces in this torrent.

Requires metadata.

◆ uploadLimit()

int Torrent::uploadLimit ( ) const

Per-torrent upload rate limit in bytes/sec.

0 = unlimited.

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

include/Kanoop/torrent/torrent.h

Public Types

Signals

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ State

Member Function Documentation

◆ addTracker()

◆ banPeer()

◆ downloadDirectory()

◆ downloadLimit()

◆ eta()

◆ fileCount()

◆ fileName()

◆ filePriority()

◆ fileProgress()

◆ fileSize()

◆ findFileByName()

◆ handle()

◆ hasMetadata()

◆ infoHash()

◆ infoHashHex()

◆ moveStorage()

◆ name()

◆ outputPath()

◆ peers()

◆ pieceSize()

◆ ratio()

◆ removeTracker()

◆ renameFile()

◆ saveResumeData()

◆ seedRatioLimit()

◆ setAllFilePriorities()

◆ setDownloadDirectory()

◆ setDownloadLimit()

◆ setFilePriority()

◆ setInfoHash()

◆ setMagnetLink()

◆ setSeedRatioLimit()

◆ setSequentialDownload()

◆ setUploadLimit()

◆ state()

◆ totalPieces()

◆ uploadLimit()