Struct AddTorrentParams 

pub struct AddTorrentParams {
    pub source: AddSource,
    pub category: Option<String>,
    pub tags: Vec<String>,
    pub download_dir: Option<PathBuf>,
    pub paused: Option<bool>,
    pub skip_checking: bool,
    pub content_layout: Option<ContentLayout>,
    pub preallocate_mode: Option<PreallocateMode>,
    pub auto_managed: Option<bool>,
    pub sequential_download: Option<bool>,
    pub prioritize_first_last_pieces: Option<bool>,
    pub file_priorities: Vec<FilePriority>,
}

Unified parameters for SessionHandle::add_torrent (M170).

Replaces the ad-hoc set of add_magnet, add_magnet_uri, add_torrent_bytes call shapes with a single params struct. Callers build the struct via the static constructors (magnet or bytes) and chain .with_category() / .with_tags() / .with_download_dir() / .paused().

Download-dir resolution (see add_torrent):

1. download_dir: Some(p) wins, if set.
2. Else, if category: Some(name) and the registry contains name, the registry’s save_path is used.
3. Else, if category: Some(name) and the registry does NOT contain name, the call fails with [Error::CategoryNotFound].
4. Else, falls back to Settings.download_dir.

skip_checking is reserved for M171+ (qBt skip_hash_check=true).

Fields

source: AddSource

The torrent source (magnet URI or raw .torrent bytes).

category: Option<String>

Optional qBt-compat category label resolved via the session’s CategoryRegistry at add-time.

tags: Vec<String>

M171: Per-torrent tags baked in at add time (qBt-compat). Multi- valued. An empty vec means “no tags” and is the default.

download_dir: Option<PathBuf>

Explicit download directory, overrides both category lookup and Settings.download_dir when Some.

paused: Option<bool>

Whether the torrent should be added in a paused state. None (the constructor default) means “use Settings::default_add_paused”; Some(v) is an explicit per-call override. The resolution happens in dispatch_add_torrent_m170 before the M170 post-add hooks run, so the actor sees a concrete bool either way.

skip_checking: bool

Reserved for M171+ — skip the initial re-hash on add.

content_layout: Option<ContentLayout>

M252/ER5: Content layout override for this add. None (the constructor default) derives from Settings::create_subfolder (true → Original, false → NoSubfolder); Some(layout) is an explicit per-add override and wins over the setting.

preallocate_mode: Option<PreallocateMode>

M254: preallocation override for this add. None uses Settings.preallocate_mode.

auto_managed: Option<bool>

M254: whether the session queue auto-manages this torrent. None (default) = true — today’s unconditional behaviour.

sequential_download: Option<bool>

M254: enable sequential downloading from the first dispatch.

prioritize_first_last_pieces: Option<bool>

M254: enable first/last-pieces-first ordering (M253) from add.

file_priorities: Vec<FilePriority>

M254: inline per-file priorities, honoured at the FIRST wanted-pieces build. Empty = all Normal. Shorter pads, longer truncates (multi-file counts unknown until metadata for magnets).

Implementations

impl AddTorrentParams

pub fn magnet(uri: impl Into<String>) -> Self

Build a magnet-source add with default knobs.

pub fn bytes(data: impl Into<Vec<u8>>) -> Self

Build a bytes-source add with default knobs.

pub fn with_category(self, name: impl Into<String>) -> Self

Assign a category label to the torrent. The session resolves the name against its registry at add-time; unknown names error out.

pub fn with_tags(self, tags: Vec<String>) -> Self

M171: Attach tags at add time. Tags are baked into the torrent’s config before TorrentActor::new, so the first stats() call returns them — no post-add spawn race.

pub fn with_content_layout(self, layout: ContentLayout) -> Self

M252/ER5: Override the content layout for this add. Original keeps the torrent’s own structure, Subfolder always wraps in a root folder named after the torrent, NoSubfolder strips the root folder. Unset, the layout derives from Settings::create_subfolder.

pub fn with_download_dir(self, dir: impl Into<PathBuf>) -> Self

Override the download directory for this torrent.

pub fn with_preallocate_mode(self, mode: PreallocateMode) -> Self

M254: override the preallocation mode for this torrent.

pub fn auto_managed(self, enabled: bool) -> Self

M254: opt this torrent out of (or explicitly into) session queue auto-management. Unset = auto-managed, today’s behaviour.

pub fn sequential_download(self, enabled: bool) -> Self

M254: enable sequential (in-order) downloading from the first dispatch — no post-add toggle round-trip.

pub fn prioritize_first_last_pieces(self, enabled: bool) -> Self

M254: enable first/last-pieces-first ordering (M253) from add.

pub fn with_file_priorities(self, priorities: Vec<FilePriority>) -> Self

M254: set per-file priorities inline at add. Empty = all Normal.

pub fn paused(self, paused: bool) -> Self

Toggle the paused-at-add flag. Wraps the explicit choice in Some(_) so the actor can distinguish “caller explicitly set this” from “caller did not touch it” (the latter falls back to Settings::default_add_paused).

pub fn skip_checking(self, skip: bool) -> Self

Toggle the skip-initial-check flag (M171+).

Trait Implementations

impl Clone for AddTorrentParams

fn clone(&self) -> AddTorrentParams

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AddTorrentParams

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.