Struct TorrentHandle 

pub struct TorrentHandle { /* private fields */ }

Cloneable handle for interacting with a running torrent.

Implementations

impl TorrentHandle

pub async fn stats(&self) -> Result<TorrentStats>

Query current torrent statistics.

pub async fn add_peers( &self, peers: Vec<SocketAddr>, source: PeerSource, ) -> Result<()>

Add peer addresses to the available-peer pool.

pub async fn pause(&self) -> Result<()>

Pause the torrent session (disconnect peers, announce Stopped).

pub async fn resume(&self) -> Result<()>

Resume a paused torrent session (reconnect, announce Started).

pub async fn shutdown(&self) -> Result<()>

Gracefully shut down the torrent session.

pub async fn save_resume_data(&self) -> Result<FastResumeData>

Snapshot current torrent state into libtorrent-compatible resume data.

pub async fn set_file_priority( &self, index: usize, priority: FilePriority, ) -> Result<()>

Set the download priority for a specific file.

pub async fn file_priorities(&self) -> Result<Vec<FilePriority>>

Get the current per-file priorities.

pub async fn tracker_list(&self) -> Result<Vec<TrackerInfo>>

Get the list of all configured trackers with their status.

pub async fn force_reannounce(&self) -> Result<()>

Force all trackers to re-announce immediately.

pub async fn scrape(&self) -> Result<Option<(String, ScrapeInfo)>>

Scrape trackers for seeder/leecher counts.

pub async fn open_file(&self, file_index: usize) -> Result<FileStream>

Open a streaming reader for a file within the torrent.

pub async fn move_storage(&self, new_path: PathBuf) -> Result<()>

Move torrent data files to a new download directory.

Relocates existing files (rename or copy+delete), re-registers storage with the disk manager, and fires a StorageMoved alert on success.

pub async fn set_download_limit(&self, bytes_per_sec: u64) -> Result<()>

Set the per-torrent download rate limit in bytes/sec (0 = unlimited).

pub async fn set_upload_limit(&self, bytes_per_sec: u64) -> Result<()>

Set the per-torrent upload rate limit in bytes/sec (0 = unlimited).

pub async fn download_limit(&self) -> Result<u64>

Get the current per-torrent download rate limit in bytes/sec (0 = unlimited).

pub async fn upload_limit(&self) -> Result<u64>

Get the current per-torrent upload rate limit in bytes/sec (0 = unlimited).

pub async fn set_sequential_download(&self, enabled: bool) -> Result<()>

Enable or disable sequential (in-order) piece downloading.

pub async fn is_sequential_download(&self) -> Result<bool>

Query whether sequential downloading is enabled.

pub async fn set_super_seeding(&self, enabled: bool) -> Result<()>

Enable or disable BEP 16 super seeding mode.

pub async fn is_super_seeding(&self) -> Result<bool>

Query whether BEP 16 super seeding mode is enabled.

pub async fn set_seed_mode(&self, enabled: bool) -> Result<()>

Enable or disable user-requested seed-only mode (M159).

When enabled is true, the actor stops scheduling new block requests and cancels all in-flight requests, but keeps existing peers connected and continues serving uploads. Toggling back to false restores normal piece scheduling.

Errors

Returns crate::Error::Shutdown if the torrent actor has terminated.

pub async fn add_tracker(&self, url: String) -> Result<()>

Add a new tracker URL to this torrent (fire-and-forget).

The URL is validated and deduplicated by the tracker manager.

pub async fn replace_trackers(&self, urls: Vec<String>) -> Result<()>

Replace all tracker URLs for this torrent.

pub async fn force_recheck(&self) -> Result<()>

Trigger a full piece verification (force recheck).

Transitions the torrent through Checking state, clears all piece completion data, re-verifies every piece against its hash, then transitions to Seeding (all valid) or Downloading (some missing). Returns after the check is complete.

pub async fn rename_file( &self, file_index: usize, new_name: String, ) -> Result<()>

Rename a file within the torrent on disk.

Changes the filename of the specified file (by index) to new_name. The file stays in the same directory; only the filename component changes. Fires a FileRenamed alert on success.

pub async fn set_max_connections(&self, limit: usize) -> Result<()>

Set the per-torrent maximum number of connections (0 = use global default).

pub async fn max_connections(&self) -> Result<usize>

Get the current per-torrent maximum connection limit (0 = use global default).

pub async fn set_max_uploads(&self, limit: usize) -> Result<()>

Set the per-torrent maximum number of upload slots (unchoke slots).

pub async fn max_uploads(&self) -> Result<usize>

Get the current per-torrent maximum upload slots (unchoke slots).

pub async fn get_peer_info(&self) -> Result<Vec<PeerInfo>>

Get per-peer details for all connected peers.

pub async fn get_download_queue(&self) -> Result<Vec<PartialPieceInfo>>

Get in-flight piece download status (the download queue).

pub async fn have_piece(&self, index: u32) -> Result<bool>

Check whether a specific piece has been downloaded.

pub async fn piece_availability(&self) -> Result<Vec<u32>>

Get per-piece availability counts from connected peers.

pub async fn file_progress(&self) -> Result<Vec<u64>>

Get per-file bytes-downloaded progress.

pub async fn info_hashes(&self) -> Result<InfoHashes>

Get the torrent’s identity hashes (v1 and/or v2).

pub async fn torrent_file(&self) -> Result<Option<TorrentMetaV1>>

Get the full v1 metainfo, if available.

Returns None for magnet links before metadata has been received.

pub async fn torrent_file_v2(&self) -> Result<Option<TorrentMetaV2>>

Get the full v2 metainfo, if available.

Returns None if the torrent is not a v2/hybrid torrent, or for magnet links before metadata has been received.

pub async fn force_dht_announce(&self) -> Result<()>

Force an immediate DHT announce for this torrent.

Fire-and-forget at the torrent level — the DHT announce is best-effort.

pub async fn read_piece(&self, index: u32) -> Result<Bytes>

Read all data for a specific piece from disk.

Returns the complete piece data as Bytes. The piece must have been downloaded already; use have_piece to check first.

pub async fn flush_cache(&self) -> Result<()>

Flush the disk write cache, ensuring all buffered writes are persisted.

pub fn is_valid(&self) -> bool

Check whether this handle refers to a live torrent.

Returns false after the torrent has been removed or shut down. This is a synchronous check on the channel state — no command dispatch.

pub async fn clear_error(&self) -> Result<()>

Clear any error state on the torrent and resume if it was paused due to error.

pub async fn file_status(&self) -> Result<Vec<FileStatus>>

Get per-file open/mode status based on the current torrent state.

Returns one crate::types::FileStatus entry per file in the torrent.

pub async fn flags(&self) -> Result<TorrentFlags>

Read the current torrent state as a [TorrentFlags] bitflag set.

pub async fn set_flags(&self, flags: TorrentFlags) -> Result<()>

Set (enable) the specified torrent flags.

Delegates to the underlying operations (pause/resume, sequential download, etc.).

pub async fn unset_flags(&self, flags: TorrentFlags) -> Result<()>

Unset (disable) the specified torrent flags.

Delegates to the underlying operations (pause/resume, sequential download, etc.).

pub async fn connect_peer(&self, addr: SocketAddr) -> Result<()>

Immediately initiate a peer connection to the given address.

Bypasses the normal peer selection queue — the connection attempt starts right away. Fire-and-forget: no reply is sent.

Trait Implementations

impl Clone for TorrentHandle

fn clone(&self) -> TorrentHandle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.