Enum MagnetError

Source
pub enum MagnetError {
    NotAMagnetURL,
}
Expand description

§What is a magnet url

A magnet is a URI scheme that identifies files by their hash, normally used in peer to peer file sharing networks (like Bittorrent). Basically, a magnet link identifies a torrent you want to download, and tells the torrent client how to download it. They make it very easy to share files over the internet, and use a combination of DHT and trackers to tell your torrent client where other peers who can share the file with you are.

§Why is magnet_url

While working on a side project, I realized that I had the misfortune of trying to get the component parts of a magnet-url and then do further processing of them. I quickly wrote some Regex for it, but then I realized that this would be really useful for other projects that are dealing with torrents in Rust. By making it modifiable, too, it would allow for the creation of custom magnet links, which would also be useful for torrent based projects.

§Why use magnet_url

magnet_url has the goal of, as you may have guessed, parsing the parts of magnets. It does this using some relatively simple regexes. The crate is designed to be very simple and efficient, with a lot of flexibility. It’s also designed to be relatively easy to handle errors, and modification of its source is greatly encouraged through documentation and its license.

§How to use this crate

Parsing a magnet is very simple:

use magnet_url::Magnet;
let magneturl = Magnet::new("magnet:?xt=urn:btih:08ada5a7a6183aae1e09d831df6748d566095a10&dn=Sintel&tr=udp%3A%2F%2Fexplodie.org%3A6969&tr=udp%3A%2F%2Ftracker.coppersurfer.tk%3A6969&tr=udp%3A%2F%2Ftracker.empire-js.us%3A1337&tr=udp%3A%2F%2Ftracker.leechers-paradise.org%3A6969&tr=udp%3A%2F%2Ftracker.opentrackr.org%3A1337&tr=wss%3A%2F%2Ftracker.btorrent.xyz&tr=wss%3A%2F%2Ftracker.fastcast.nz&tr=wss%3A%2F%2Ftracker.openwebtorrent.com&ws=https%3A%2F%2Fwebtorrent.io%2Ftorrents%2F&xs=https%3A%2F%2Fwebtorrent.io%2Ftorrents%2Fsintel.torrent");

This returns the Magnet struct, which is made up of the fields listed below this section, wrapped aroud a Result<Magnet, MagnetError>. To access one of these fields is also very simple:

use magnet_url::Magnet;
let magneturl = Magnet::new("magnet:?xt=urn:btih:08ada5a7a6183aae1e09d831df6748d566095a10&dn=Sintel&tr=udp%3A%2F%2Fexplodie.org%3A6969&tr=udp%3A%2F%2Ftracker.coppersurfer.tk%3A6969&tr=udp%3A%2F%2Ftracker.empire-js.us%3A1337&tr=udp%3A%2F%2Ftracker.leechers-paradise.org%3A6969&tr=udp%3A%2F%2Ftracker.opentrackr.org%3A1337&tr=wss%3A%2F%2Ftracker.btorrent.xyz&tr=wss%3A%2F%2Ftracker.fastcast.nz&tr=wss%3A%2F%2Ftracker.openwebtorrent.com&ws=https%3A%2F%2Fwebtorrent.io%2Ftorrents%2F&xs=https%3A%2F%2Fwebtorrent.io%2Ftorrents%2Fsintel.torrent").unwrap();
println!("{:?}", magneturl.dn);

If you’d like to modify parts of the magnet_url to customize it, that can be done as well!

use magnet_url::Magnet;
let mut magneturl = Magnet::new("magnet:?xt=urn:btih:08ada5a7a6183aae1e09d831df6748d566095a10&dn=Sintel&tr=udp%3A%2F%2Fexplodie.org%3A6969&tr=udp%3A%2F%2Ftracker.coppersurfer.tk%3A6969&tr=udp%3A%2F%2Ftracker.empire-js.us%3A1337&tr=udp%3A%2F%2Ftracker.leechers-paradise.org%3A6969&tr=udp%3A%2F%2Ftracker.opentrackr.org%3A1337&tr=wss%3A%2F%2Ftracker.btorrent.xyz&tr=wss%3A%2F%2Ftracker.fastcast.nz&tr=wss%3A%2F%2Ftracker.openwebtorrent.com&ws=https%3A%2F%2Fwebtorrent.io%2Ftorrents%2F&xs=https%3A%2F%2Fwebtorrent.io%2Ftorrents%2Fsintel.torrent").unwrap();
println!("{:?}", magneturl.dn);
magneturl.dn = Some(String::from("hello_world"));
println!("{:?}", magneturl.dn);

In fact, you can construct your own magnet url as well, as long as you fill in all the parameters!

use magnet_url::Magnet;
//Note, this magnet won't actually download, sorry :/
Magnet {
    dn: Some("hello_world".to_string()),
    hash_type: Some("sha1".to_string()),
    xt: Some("2aae6c35c94fcfb415dbe95f408b9ce91ee846ed".to_string()),
    xl: Some(1234567890),
    tr: vec!["https://example.com/".to_string()],
    kt: Some("cool+stuff".to_string()),
    ws: None,
    acceptable_source: None,
    mt: None,
    xs: None,
};

From a Magnet struct, you can generate a magnet string again

use magnet_url::Magnet;
//Note, this magnet won't actually download, sorry :/
let magnet_struct = Magnet {
    dn: Some("hello_world".to_string()),
    hash_type: Some("sha1".to_string()),
    xt: Some("2aae6c35c94fcfb415dbe95f408b9ce91ee846ed".to_string()),
    xl: Some(1234567890),
    tr: vec!["https://example.com/".to_string()],
    kt: Some("cool+stuff".to_string()),
    ws: None,
    acceptable_source: None,
    mt: None,
    xs: None,
};

let magnet_string = magnet_struct.to_string();
println!("{}", magnet_string);

Invalid magnet url’s will result in an Error, which can be handled appropriately

use magnet_url::Magnet;
let _magnet_link = Magnet::new("https://example.com").unwrap();

The various ways the new function can fail

Variants§

§

NotAMagnetURL

Trait Implementations§

Source§

impl Clone for MagnetError

Source§

fn clone(&self) -> MagnetError

Returns a copy of the value. Read more
1.0.0 · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for MagnetError

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Hash for MagnetError

Source§

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher. Read more
1.3.0 · Source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
Source§

impl PartialEq for MagnetError

Source§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
Source§

impl StructuralPartialEq for MagnetError

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dst: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.