Magnet
From Develop
Contents |
Design Document: Magnet links
The Magnet a URI scheme is an open standard which specifies a file to be downloaded, but not how the file should be downloaded. Basic magnet link support will be available in Miro 4.0. This design document covers what and how it is supported.
Requirements, Use Cases and User Stories
Michaela is surfing the web and does not know what a magnet link is, but clicks on the link and wants everything to work.
Monica gets sent a magnet link from her friend and wants to download it with Miro.
Peter already has the magnet.exe utility on his computer without knowing because it was delivered with other BitTorrent clients. He installs Miro and wants to be able to choose Miro when clicking on a magnet link.
Diana is a power user and uses Miro and other BitTorrent applications side by side and wants to be able to choose which application to use when clicking on a Magnet link. So she installs the magnet.exe utility.
Research Links
Wikipedia article on the Magnet URI scheme: http://en.wikipedia.org/wiki/Magnet_URI
http://magnet-uri.sourceforge.net/magnet-draft-overview.txt
http://msdn.microsoft.com/en-us/library/aa767914%28VS.85%29.aspx
http://forum.vuze.com/thread.jspa?threadID=79692&tstart=0
magnet.exe utility. http://sourceforge.net/projects/magnethandler/
Best source on magnet info hash encoding I have been able to find. http://wiki.vuze.com/w/Magnet_link
The comments for bug 16794 have details on magnet info hash encoding issues. http://bugzilla.pculture.org/show_bug.cgi?id=16794
Design
What is supported
Miro only supports torrent magnet links. This means magnet links of the following format:
magnet:?xt=urn:btih:BITTORRENT_INFO_HASH
Where BITTORENT_INFO_HASH is a hex or base32 encoded BitTorrent info hash (in other BitTorrent applications info hashes usually hex encoded).
Ways to download magnet links in Miro 4.0:
- File->"Download Item"
- Clicking on a magnet link in a browser
- Downloading from a website
Other download methods are not yet supported.
The Miro downloader
Libtorrent supports magnet links.The majority of the magnet work is making the Miro downloader support magnet links. The main problem is that torrents added through a magnet link only receive their metadata after the download is started in libtorrent.
Procedure for torrent downloads:
- get torrent link
- download torrent file
- extract metadata
- begin download
Procedure for magnet downloads:
- get magnet link
- begin download
- extract metadata
This changed procedure requires quite some changes in the downloader codebase.
Association policies
Windows and Linux
Miro checks the association at each startup and associates with the magnet protocol if no other program is associated already.
Windows only
magnet.exe
Windows apparently only can associate with one application at once with a protocol. To solve this one can install the tool magnet.exe and associate it with the magnet protocol. Applications which can handle the magnet protocol can then register with magnet.exe. When the user clicks on a magnet link, the magnet.exe tool is run and presents the user with a list of all programs which can handle magnet links.
Miro always tries to register with magnet.exe, even if magnet.exe is not installed. However because of security restrictions, it is not possible to register on Windows Vista or newer, since magnet.exe only works with HKEY_LOCAL_MACHINE.
Keys for magnet association
In Gconf
- /desktop/gnome/url-handlers/magnet/command miro "%s"
- /desktop/gnome/url-handlers/magnet/enabled True
- /desktop/gnome/url-handlers/magnet/needs_terminal False
On Windows
This is a short and incomplete overview of which registry keys are used on Windows. The values set are not written down here.
- HKEY_CURRENT_USER\Software\Classes\.magnet
- HKEY_CURRENT_USER\MIME\Database\Content Type\application/x-magnet
- HKEY_CURRENT_USER\Software\Classes\magnet
- HKEY_CURRENT_USER\Software\Classes\magnet\DefaultIcon
- HKEY_CURRENT_USER\Software\Classes\magnet\shell\open\command
Magnet.exe keys:
- HKEY_LOCAL_MACHINE\SOFTWARE\magnet\handlers\Miro
- HKEY_LOCAL_MACHINE\SOFTWARE\magnet\handlers\Miro\Type
Possible todos
- Downloading from feed
- Downloading from a video search
- Downloading an item from Miro Guide
- Add schema to gconf keys
- Add support for magnet links with empty BTIH section (needs support in libtorrent)
- Support non-torrent magnet links
- Look into how one could associate the magnet protocol in KDE based browsers
