Struct lava_torrent::torrent::v1::TorrentBuilder

pub struct TorrentBuilder { /* private fields */ }

Builder for creating Torrents from files.

This struct is used for creating Torrents, so that you can encode/serialize them to .torrent files. If you want to read existing .torrent files then use Torrent::read_from_file() or Torrent::read_from_bytes().

Required fields: path and piece_length. They are set when calling the constructor new().

Optional fields can be set by calling the corresponding methods (e.g. set_announce()). Fields can be updated in the same way.

Notes

Hidden Files

*nix hidden files/dirs are ignored.

Reasoning: when handling these special “files”, there are many decisions to make:

• Should they be ignored, included, or selectively ignored/included?
• Should included/ignored entries be marked specially (e.g. BEP 47)?
• Should users be allowed to configure the settings?
• If users can configure the settings, what would be the ideal defaults?
• …

Apparently it’s not easy to make these decisions. Therefore these files are ignored for now. Clients like Deluge and qBittorrent also ignore hidden entries.

Parallel Hashing

By default, pieces are hashed in parallel. The default level of parallelism is equal to the number of physical cores. To adjust the parallelism level or to force single-threaded hashing, use set_num_threads(). Note that this setting is specific to each builder and not global.

Implementations

impl TorrentBuilder

pub fn new<P>(path: P, piece_length: Integer) -> TorrentBuilderwhere P: AsRef<Path>,

Create a new TorrentBuilder with required fields set.

The caller has to ensure that the inputs are valid, as this method does not validate its inputs. If they turn out to be invalid, calling build() later will fail.

NOTE: A valid piece_length is larger than 0 AND is a power of 2.

pub fn build(self) -> Result<Torrent, LavaTorrentError>

Build a Torrent from this TorrentBuilder.

If name is not set, then the last component of path will be used as the Torrent’s name field.

build() does not provide comprehensive validation of any input. Basic cases such as setting announce to an empty string will be detected and Err will be returned. But more complicated cases such as using an invalid url as announce won’t be detected. Again, the caller has to ensure that the values given to a TorrentBuilder are valid.

pub fn build_non_blocking(self) -> Result<TorrentBuild, LavaTorrentError>

Like build(), but non-blocking.

Example

use lava_torrent::torrent::v1::TorrentBuilder;

let build = TorrentBuilder::new("dir/", 1048576).build_non_blocking().unwrap();

while !build.is_finished() {
    println!("torrent build progress: {}%", build.get_progress());
    std::thread::sleep(std::time::Duration::from_millis(100));
}

let torrent = build.get_output().unwrap();
torrent.write_into_file("sample.torrent").unwrap();

pub fn set_announce(self, announce: Option<String>) -> TorrentBuilder

Set the announce field of the Torrent to be built.

Calling this method multiple times will simply override previous settings.

The caller has to ensure that announce is valid, as this method does not validate its value. If announce turns out to be invalid, calling build() later will fail.

pub fn set_announce_list(self, announce_list: AnnounceList) -> TorrentBuilder

Set the announce_list field of the Torrent to be built.

Calling this method multiple times will simply override previous settings.

The caller has to ensure that announce_list is valid, as this method does not validate its value. If announce_list turns out to be invalid, calling build() later will fail.

pub fn set_name(self, name: String) -> TorrentBuilder

Set the name field of the Torrent to be built.

Calling this method multiple times will simply override previous settings.

The caller has to ensure that name is valid, as this method does not validate its value. If name turns out to be invalid, calling build() later will fail.

pub fn set_path<P>(self, path: P) -> TorrentBuilderwhere P: AsRef<Path>,

Set the path to the file(s) from which the Torrent will be built.

Calling this method multiple times will simply override previous settings.

The caller has to ensure that path is valid, as this method does not validate its value. If path turns out to be invalid, calling build() later will fail.

pub fn set_piece_length(self, piece_length: Integer) -> TorrentBuilder

Set the piece_length field of the Torrent to be built.

Calling this method multiple times will simply override previous settings.

The caller has to ensure that piece_length is valid, as this method does not validate its value. If piece_length turns out to be invalid, calling build() later will fail.

NOTE: A valid piece_length is larger than 0 AND is a power of 2.

pub fn add_extra_field(self, key: String, val: BencodeElem) -> TorrentBuilder

Add an extra field to Torrent (i.e. to the root dictionary).

Calling this method multiple times with the same key will simply override previous settings.

The caller has to ensure that key and val are valid, as this method does not validate their values. If they turn out to be invalid, calling build() later will fail.

pub fn add_extra_info_field( self, key: String, val: BencodeElem ) -> TorrentBuilder

Add an extra info field to Torrent (i.e. to the info dictionary).

Calling this method multiple times with the same key will simply override previous settings.

The caller has to ensure that key and val are valid, as this method does not validate their values. If they turn out to be invalid, calling build() later will fail.

pub fn set_privacy(self, is_private: bool) -> TorrentBuilder

Make the Torrent private or public, as defined in BEP 27.

Calling this method multiple times will simply override previous settings.

pub fn set_num_threads(self, num_threads: usize) -> TorrentBuilder

Change the number of threads used when hashing pieces.

If set to 0, the number of threads used will be equal to the number of physical cores. This is also the default behavior.

Set this to 1 if you prefer single-threaded hashing.

Trait Implementations

impl Clone for TorrentBuilder

fn clone(&self) -> TorrentBuilder

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for TorrentBuilder

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

Formats the value using the given formatter.

impl Default for TorrentBuilder

fn default() -> TorrentBuilder

Returns the “default value” for a type.

impl PartialEq<TorrentBuilder> for TorrentBuilder

fn eq(&self, other: &TorrentBuilder) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for TorrentBuilder

impl StructuralEq for TorrentBuilder

impl StructuralPartialEq for TorrentBuilder