pub struct TorrentHandle { /* private fields */ }Expand description
Cloneable handle for interacting with a running torrent.
Implementations§
Source§impl TorrentHandle
impl TorrentHandle
Sourcepub async fn stats(&self) -> Result<TorrentStats>
pub async fn stats(&self) -> Result<TorrentStats>
Sourcepub async fn get_meta(&self) -> Result<Option<TorrentMetaV1>>
pub async fn get_meta(&self) -> Result<Option<TorrentMetaV1>>
v0.173.1: fetch the torrent’s current metadata from the TorrentActor.
Returns Ok(None) if metadata has not yet been assembled (magnet
pre-resolution), Ok(Some(meta)) once the info dict is known. Returns
Err(Shutdown) if the actor has already exited. Callers that need the
meta to exist should fall back to crate::Error::MetadataNotReady on
the Ok(None) branch.
This replaces SessionActor.TorrentEntry.meta as the single source of
truth: see docs/plans/2026-04-22-irontide-v0.173.1-qbt-v2-bug-sweep.md
for the Class A archaeology.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn add_peers(
&self,
peers: Vec<SocketAddr>,
source: PeerSource,
) -> Result<()>
pub async fn add_peers( &self, peers: Vec<SocketAddr>, source: PeerSource, ) -> Result<()>
Add peer addresses to the available-peer pool.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn pause(&self) -> Result<()>
pub async fn pause(&self) -> Result<()>
Pause the torrent session (disconnect peers, announce Stopped).
§Errors
Returns an error if the session is shut down.
Sourcepub async fn queue(&self) -> Result<()>
pub async fn queue(&self) -> Result<()>
Queue a torrent via auto-manage (system-managed pause).
§Errors
Returns an error if the session is shut down.
Sourcepub async fn set_category(&self, category: Option<String>) -> Result<()>
pub async fn set_category(&self, category: Option<String>) -> Result<()>
M170: update the qBt-compat category label on this torrent.
Pass None to clear the label. The change is visible via the
next stats() call and persists across save_resume_data.
§Errors
Returns an error if the session is shut down.
M171: replace this torrent’s tag set wholesale (qBt-compat).
Mirrors qBt’s addTags / removeTags wire behaviour at the API
layer — always a wholesale replacement at the engine layer. The
change is visible via the next stats() call and persists
across save_resume_data.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn resume(&self) -> Result<()>
pub async fn resume(&self) -> Result<()>
Resume a paused torrent session (reconnect, announce Started).
§Errors
Returns an error if the session is shut down.
Sourcepub async fn save_resume_data(&self) -> Result<FastResumeData>
pub async fn save_resume_data(&self) -> Result<FastResumeData>
Snapshot current torrent state into libtorrent-compatible resume data.
§Errors
Returns an error if the I/O operation fails.
Sourcepub async fn set_file_priority(
&self,
index: usize,
priority: FilePriority,
) -> Result<()>
pub async fn set_file_priority( &self, index: usize, priority: FilePriority, ) -> Result<()>
Set the download priority for a specific file.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn file_priorities(&self) -> Result<Vec<FilePriority>>
pub async fn file_priorities(&self) -> Result<Vec<FilePriority>>
Sourcepub async fn tracker_list(&self) -> Result<Vec<TrackerInfo>>
pub async fn tracker_list(&self) -> Result<Vec<TrackerInfo>>
Get the list of all configured trackers with their status.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn get_web_seeds(&self) -> Result<Vec<String>>
pub async fn get_web_seeds(&self) -> Result<Vec<String>>
M171 Lane B: snapshot the web seed URLs (BEP 19 + BEP 17 merged).
§Errors
Returns an error if the session is shut down.
Sourcepub async fn get_piece_states(&self) -> Result<Vec<u8>>
pub async fn get_piece_states(&self) -> Result<Vec<u8>>
M171 Lane B: snapshot the per-piece qBt state codes.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn get_piece_hashes(
&self,
offset: u32,
limit: u32,
) -> Result<Vec<String>>
pub async fn get_piece_hashes( &self, offset: u32, limit: u32, ) -> Result<Vec<String>>
M171 Lane B: paginated piece hash list.
offset and limit are clamped to the real hash count inside
the actor — callers can pass arbitrary values without overflow
concerns.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn force_reannounce(&self) -> Result<()>
pub async fn force_reannounce(&self) -> Result<()>
Force all trackers to re-announce immediately.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn open_file(&self, file_index: usize) -> Result<FileStream>
pub async fn open_file(&self, file_index: usize) -> Result<FileStream>
Open a streaming reader for a file within the torrent.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn move_storage(&self, new_path: PathBuf) -> Result<()>
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.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn set_download_limit(&self, bytes_per_sec: u64) -> Result<()>
pub async fn set_download_limit(&self, bytes_per_sec: u64) -> Result<()>
Set the per-torrent download rate limit in bytes/sec (0 = unlimited).
§Errors
Returns an error if the data cannot be parsed or I/O fails.
Sourcepub async fn set_upload_limit(&self, bytes_per_sec: u64) -> Result<()>
pub async fn set_upload_limit(&self, bytes_per_sec: u64) -> Result<()>
Set the per-torrent upload rate limit in bytes/sec (0 = unlimited).
§Errors
Returns an error if the data cannot be parsed or I/O fails.
Sourcepub async fn download_limit(&self) -> Result<u64>
pub async fn download_limit(&self) -> Result<u64>
Get the current per-torrent download rate limit in bytes/sec (0 = unlimited).
§Errors
Returns an error if the data cannot be parsed or I/O fails.
Sourcepub async fn upload_limit(&self) -> Result<u64>
pub async fn upload_limit(&self) -> Result<u64>
Get the current per-torrent upload rate limit in bytes/sec (0 = unlimited).
§Errors
Returns an error if the data cannot be parsed or I/O fails.
Sourcepub async fn set_sequential_download(&self, enabled: bool) -> Result<()>
pub async fn set_sequential_download(&self, enabled: bool) -> Result<()>
Enable or disable sequential (in-order) piece downloading.
§Errors
Returns an error if the data cannot be parsed or I/O fails.
Sourcepub async fn is_sequential_download(&self) -> Result<bool>
pub async fn is_sequential_download(&self) -> Result<bool>
Query whether sequential downloading is enabled.
§Errors
Returns an error if the data cannot be parsed or I/O fails.
Sourcepub async fn set_super_seeding(&self, enabled: bool) -> Result<()>
pub async fn set_super_seeding(&self, enabled: bool) -> Result<()>
Sourcepub async fn is_super_seeding(&self) -> Result<bool>
pub async fn is_super_seeding(&self) -> Result<bool>
Query whether BEP 16 super seeding mode is enabled.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn set_seed_mode(&self, enabled: bool) -> Result<()>
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.
Sourcepub async fn add_tracker(&self, url: String) -> Result<()>
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.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn force_recheck(&self) -> Result<()>
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.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn rename_file(
&self,
file_index: usize,
new_name: String,
) -> Result<()>
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.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn set_max_connections(&self, limit: usize) -> Result<()>
pub async fn set_max_connections(&self, limit: usize) -> Result<()>
Set the per-torrent maximum number of connections (0 = use global default).
§Errors
Returns an error if the connection or binding fails.
Sourcepub async fn max_connections(&self) -> Result<usize>
pub async fn max_connections(&self) -> Result<usize>
Get the current per-torrent maximum connection limit (0 = use global default).
§Errors
Returns an error if the connection or binding fails.
Sourcepub async fn set_max_uploads(&self, limit: usize) -> Result<()>
pub async fn set_max_uploads(&self, limit: usize) -> Result<()>
Set the per-torrent maximum number of upload slots (unchoke slots).
§Errors
Returns an error if the data cannot be parsed or I/O fails.
Sourcepub async fn max_uploads(&self) -> Result<usize>
pub async fn max_uploads(&self) -> Result<usize>
Get the current per-torrent maximum upload slots (unchoke slots).
§Errors
Returns an error if the data cannot be parsed or I/O fails.
Sourcepub async fn get_peer_info(&self) -> Result<Vec<PeerInfo>>
pub async fn get_peer_info(&self) -> Result<Vec<PeerInfo>>
Sourcepub async fn get_download_queue(&self) -> Result<Vec<PartialPieceInfo>>
pub async fn get_download_queue(&self) -> Result<Vec<PartialPieceInfo>>
Get in-flight piece download status (the download queue).
§Errors
Returns an error if the data cannot be parsed or I/O fails.
Sourcepub async fn have_piece(&self, index: u32) -> Result<bool>
pub async fn have_piece(&self, index: u32) -> Result<bool>
Check whether a specific piece has been downloaded.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn piece_availability(&self) -> Result<Vec<u32>>
pub async fn piece_availability(&self) -> Result<Vec<u32>>
Get per-piece availability counts from connected peers.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn file_progress(&self) -> Result<Vec<u64>>
pub async fn file_progress(&self) -> Result<Vec<u64>>
Sourcepub async fn info_hashes(&self) -> Result<InfoHashes>
pub async fn info_hashes(&self) -> Result<InfoHashes>
Get the torrent’s identity hashes (v1 and/or v2).
§Errors
Returns an error if the session is shut down.
Sourcepub async fn torrent_file(&self) -> Result<Option<TorrentMetaV1>>
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.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn torrent_file_v2(&self) -> Result<Option<TorrentMetaV2>>
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.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn force_dht_announce(&self) -> Result<()>
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.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn read_piece(&self, index: u32) -> Result<Bytes>
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.
§Errors
Returns an error if the data cannot be parsed or I/O fails.
Sourcepub async fn flush_cache(&self) -> Result<()>
pub async fn flush_cache(&self) -> Result<()>
Flush the disk write cache, ensuring all buffered writes are persisted.
§Errors
Returns an error if the session is shut down.
Sourcepub fn is_valid(&self) -> bool
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.
Sourcepub async fn clear_error(&self) -> Result<()>
pub async fn clear_error(&self) -> Result<()>
Clear any error state on the torrent and resume if it was paused due to error.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn file_status(&self) -> Result<Vec<FileStatus>>
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.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn flags(&self) -> Result<TorrentFlags>
pub async fn flags(&self) -> Result<TorrentFlags>
Read the current torrent state as a [TorrentFlags] bitflag set.
§Errors
Returns an error if the session is shut down.
Sourcepub async fn set_flags(&self, flags: TorrentFlags) -> Result<()>
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.).
§Errors
Returns an error if the session is shut down.
Sourcepub async fn unset_flags(&self, flags: TorrentFlags) -> Result<()>
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.).
§Errors
Returns an error if the session is shut down.
Sourcepub async fn connect_peer(&self, addr: SocketAddr) -> Result<()>
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.
§Errors
Returns an error if the connection or binding fails.
Trait Implementations§
Source§impl Clone for TorrentHandle
impl Clone for TorrentHandle
Source§fn clone(&self) -> TorrentHandle
fn clone(&self) -> TorrentHandle
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more