root / dotorg / v3 / html / metadata_extension.html

Revision 9922, 6.9 kB (checked in by arvid, 13 months ago)

added the generated html as well

Line 
1<?xml version="1.0" encoding="utf-8" ?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
7<title></title>
8<link rel="stylesheet" href="css/screen.css" type="text/css" />
9</head>
10<body>
11<div class="document">
12
13<div id="upper" class="clear">
14<div id="wrap">
15<div id="header">
16<h1><a href="./index.html">BitTorrent<span>.org</span></a></h1>
17</div>
18<div id="nav">
19<ul>
20<li><a href="./index.html">Home</a></li>
21<li><a href="./introduction.html">For Users</a></li>
22<li><span>For Developers</span></li>
23<!-- <li><a href="./blog">Blog</a></li> -->
24<li><a href="./donate.html">Donate!</a></li>
25</ul>
26</div> <!-- nav -->
27<!-- ### Begin Content ### -->
28<div id="second">
29
30
31
32<div class="section" id="metadata-extension">
33<h1>metadata extension</h1>
34<p>The purpose of this extension is to allow clients to join a swarm and
35complete a download without the need of downloading a .torrent file
36first. This extension instead allows clients to download the metadata
37from peers. It makes it possible to support <em>magnet links</em>, a link
38on a web page only containing enough information to join the swarm
39(the info hash).</p>
40<div class="section" id="metadata">
41<h2>metadata</h2>
42<p>This extension only transfers the info-dictionary part of the .torrent
43file. This part can be validated by the info-hash. In this document, that
44part of the .torrent file is referred to as <em>the metadata</em>.</p>
45<p>The metadata is plit up in 16kiB pieces. The pieces are indexed starting
46from 0 for the first 16kiB of metadata.</p>
47</div>
48<div class="section" id="extension-header">
49<h2>extension header</h2>
50<p>The metadata extension uses the <a class="reference" href="extension_protocol.html">extension protocol</a> to advertize its
51existence. It adds the &quot;ut_metadata&quot; entry to the &quot;m&quot; dictionary in the
52extension header hand-shake message. This identifies the message code
53used for this message. It also adds &quot;metadata_size&quot; to the handshake
54message (not the &quot;m&quot; dictionary) specifying an integer value of the
55number of bytes of the metadata.</p>
56<p>Example extension handshake message:</p>
57<pre class="literal-block">
58{'m': {'ut_metadata', 3}, 'metadata_size': 31235}
59</pre>
60</div>
61<div class="section" id="extension-message">
62<h2>extension message</h2>
63<p>The extension messages are bencoded. There are 3 different kinds of messages:</p>
64<ol class="arabic simple" start="0">
65<li>request</li>
66<li>data</li>
67<li>reject</li>
68</ol>
69<p>The bencoded messages have a key &quot;msg_type&quot; which value is an integer
70corresponding to the type of message. They also have a key &quot;piece&quot;, which
71indicates which part of the metadata this message refers to.</p>
72<div class="section" id="request">
73<h3>request</h3>
74<p>The <tt class="docutils literal"><span class="pre">request</span></tt> message does not have any additional keys in the dictionary.
75The response to this message, from a peer supporting the extension, is either
76a <tt class="docutils literal"><span class="pre">reject</span></tt> or a <tt class="docutils literal"><span class="pre">data</span></tt> message. The response MUST have the same <tt class="docutils literal"><span class="pre">piece</span></tt>
77as the request did.</p>
78<p>A peer MUST verify that any piece it sends passes the info-hash verification.
79i.e. until the peer has the entire metadata, it cannot run SHA-1 to verify that
80it yields the same hash as the info-hash. Peers that do not have the entire
81metadata MUST respond with a <tt class="docutils literal"><span class="pre">reject</span></tt> message to any metadata request.</p>
82<p>Example:</p>
83<pre class="literal-block">
84{'msg_type': 0, 'piece': 0}
85d8:msg_typei0e5:piecei0ee
86</pre>
87<p>That request message requests the first metadata piece.</p>
88</div>
89<div class="section" id="data">
90<h3>data</h3>
91<p>The <tt class="docutils literal"><span class="pre">data</span></tt> message adds another entry to the dictionary, &quot;total_size&quot;. This
92key has the same semantics as the &quot;metadata_size&quot; in the extension header. This
93is an integer.</p>
94<p>The metadata piece is appended to the bencoded dictionary, it is not a part of
95the dictionary, but it is a part of the message (the length prefix MUST include it).</p>
96<p>If the piece is the last piece of the metadata, it may be less than 16kiB. If it
97is not the last piece of the metadata, it MUST be 16kiB.</p>
98<p>Example:</p>
99<pre class="literal-block">
100{'msg_type': 1, 'piece': 0, 'total_size': 3425}
101d8:msg_typei1e5:piecei0e10:total_sizei34256eexxxxxxxx...
102</pre>
103<p>The <tt class="docutils literal"><span class="pre">x</span></tt> represents binary data (the metadata).</p>
104</div>
105<div class="section" id="reject">
106<h3>reject</h3>
107<p>The <tt class="docutils literal"><span class="pre">reject</span></tt> message does not have any additional keys in its message.
108It SHOULD be interpreted as the peer does not have the piece of metadata
109that was requested.</p>
110<p>Clients MAY implement flood protection by rejecting <tt class="docutils literal"><span class="pre">request</span></tt> messages
111after a certain number of them have been served. Typically the number of
112pieces of metadata times a factor.</p>
113<p>Example:</p>
114<pre class="literal-block">
115{'msg_type': 2, 'piece': 0}
116d8:msg_typei1e5:piecei0ee
117</pre>
118</div>
119</div>
120<div class="section" id="magnet-uri-format">
121<h2>magnet URI format</h2>
122<p>The magnet URI format is:</p>
123<pre class="literal-block">
124magnet:?xt=urn:btih:&lt;info-hash&gt;&amp;dn=&lt;name&gt;&amp;tr=&lt;tracker-url&gt;
125</pre>
126<dl class="docutils">
127<dt>&lt;info-hash&gt;</dt>
128<dd>Is the info-hash encoded as base32.</dd>
129</dl>
130<p><tt class="docutils literal"><span class="pre">xt</span></tt> is the only mandatory parameter. <tt class="docutils literal"><span class="pre">dn</span></tt> is the display name that may be
131used by the client to display while waiting for metadata. <tt class="docutils literal"><span class="pre">tr</span></tt> is a tracker
132url, if there is one. If there are multiple trackers, multiple <tt class="docutils literal"><span class="pre">tr</span></tt> entries
133may be included.</p>
134<p>Both <tt class="docutils literal"><span class="pre">dn</span></tt> and <tt class="docutils literal"><span class="pre">tr</span></tt> are optional.</p>
135<p>If no tracker is specified, the client SHOULD use the DHT to acquire peers.</p>
136</div>
137<div class="section" id="authors">
138<h2>authors</h2>
139<div class="line-block">
140<div class="line"><a class="reference" href="mailto:greg&#37;&#52;&#48;bittorrent&#46;com">Greg Hazel</a></div>
141<div class="line"><a class="reference" href="mailto:arvid&#37;&#52;&#48;bittorrent&#46;com">Arvid Norberg</a></div>
142</div>
143</div>
144</div>
145
146</div>
147        <div id="footer">
148<hr/>
149<p>Copyright 2006 BitTorrent.org</p>
150</div>
151
152</div>
153</body>
154</html>
Note: See TracBrowser for help on using the browser.