root / dotorg / v6 / html / beps / bep_0009.html

Revision 10595, 10.1 kB (checked in by dave, 11 months ago)

generated html with fixes from Arvid. Plus refining some text in bep_0008. Fixed makefile.

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/bep.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<table class="rfc2822 docutils field-list" frame="void" rules="none">
33<col class="field-name" />
34<col class="field-body" />
35<tbody valign="top">
36<tr class="field"><th class="field-name">BEP:</th><td class="field-body">9</td>
37</tr>
38<tr class="field"><th class="field-name">Title:</th><td class="field-body">Metadata Extension</td>
39</tr>
40<tr class="field"><th class="field-name">Version:</th><td class="field-body">10561</td>
41</tr>
42<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference external" href="https://svn.bittorrent.com/trac.cgi/browser/dotorg/trunk/html/beps/bep_0009.rst">2008-02-06 10:01:00 -0800 (Wed, 06 Feb 2008)</a></td>
43</tr>
44<tr class="field"><th class="field-name">Author:</th><td class="field-body">Greg Hazel &lt;greg&#32;&#97;t&#32;bittorrent.com&gt;, Arvid Norberg &lt;arvid&#32;&#97;t&#32;bittorrent.com&gt;</td>
45</tr>
46<tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
47</tr>
48<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
49</tr>
50<tr class="field"><th class="field-name">Created:</th><td class="field-body">31-Jan-2008</td>
51</tr>
52<tr class="field"><th class="field-name">Post-History:</th><td class="field-body"></td>
53</tr>
54</tbody>
55</table>
56<hr />
57<div class="contents topic" id="contents">
58<p class="topic-title first">Contents</p>
59<ul class="simple">
60<li><a class="reference internal" href="#metadata" id="id7">metadata</a></li>
61<li><a class="reference internal" href="#extension-header" id="id8">extension header</a></li>
62<li><a class="reference internal" href="#extension-message" id="id9">extension message</a><ul>
63<li><a class="reference internal" href="#request" id="id10">request</a></li>
64<li><a class="reference internal" href="#data" id="id11">data</a></li>
65<li><a class="reference internal" href="#reject" id="id12">reject</a></li>
66</ul>
67</li>
68<li><a class="reference internal" href="#magnet-uri-format" id="id13">magnet URI format</a></li>
69<li><a class="reference internal" href="#id2" id="id14">References</a></li>
70</ul>
71</div>
72<p>The purpose of this extension is to allow clients to join a swarm and
73complete a download without the need of downloading a .torrent file
74first. This extension instead allows clients to download the metadata
75from peers. It makes it possible to support <em>magnet links</em>, a link
76on a web page only containing enough information to join the swarm
77(the info hash).</p>
78<div class="section" id="metadata">
79<h1>metadata</h1>
80<p>This extension only transfers the info-dictionary part of the .torrent
81file. This part can be validated by the info-hash. In this document, that
82part of the .torrent file is referred to as <em>the metadata</em>.</p>
83<p>The metadata is handled in bocks of 16KiB (65536 Bytes). The metadata blocks
84are indexed starting at 0. All blocks are 16KiB except the last block which may
85be smaller.</p>
86</div>
87<div class="section" id="extension-header">
88<h1>extension header</h1>
89<p>The metadata extension uses the extension protocol (specified in <a class="reference external" href="http://www.bittorrent.org/beps/bep_0010.html">BEP 0010</a> <a class="footnote-reference" href="#id3" id="id4">[2]</a>
90) to advertize its existence. It adds the &quot;ut_metadata&quot; entry to the &quot;m&quot;
91dictionary in the extension header hand-shake message. This identifies the
92message code used for this message. It also adds &quot;metadata_size&quot; to the
93handshake message (not the &quot;m&quot; dictionary) specifying an integer value of the
94number of bytes of the metadata.</p>
95<p>Example extension handshake message:</p>
96<pre class="literal-block">
97{'m': {'ut_metadata', 3}, 'metadata_size': 31235}
98</pre>
99</div>
100<div class="section" id="extension-message">
101<h1>extension message</h1>
102<p>The extension messages are bencoded. There are 3 different kinds of messages:</p>
103<ol class="arabic simple" start="0">
104<li>request</li>
105<li>data</li>
106<li>reject</li>
107</ol>
108<p>The bencoded messages have a key &quot;msg_type&quot; which value is an integer
109corresponding to the type of message. They also have a key &quot;piece&quot;, which
110indicates which part of the metadata this message refers to.</p>
111<div class="section" id="request">
112<h2>request</h2>
113<p>The <tt class="docutils literal"><span class="pre">request</span></tt> message does not have any additional keys in the dictionary.
114The response to this message, from a peer supporting the extension, is either
115a <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>
116as the request did.</p>
117<p>A peer MUST verify that any piece it sends passes the info-hash verification.
118i.e. until the peer has the entire metadata, it cannot run SHA-1 to verify that
119it yields the same hash as the info-hash. Peers that do not have the entire
120metadata MUST respond with a <tt class="docutils literal"><span class="pre">reject</span></tt> message to any metadata request.</p>
121<p>Example:</p>
122<pre class="literal-block">
123{'msg_type': 0, 'piece': 0}
124d8:msg_typei0e5:piecei0ee
125</pre>
126<p>That request message requests the first metadata piece.</p>
127</div>
128<div class="section" id="data">
129<h2>data</h2>
130<p>The <tt class="docutils literal"><span class="pre">data</span></tt> message adds another entry to the dictionary, &quot;total_size&quot;. This
131key has the same semantics as the &quot;metadata_size&quot; in the extension header. This
132is an integer.</p>
133<p>The metadata piece is appended to the bencoded dictionary, it is not a part of
134the dictionary, but it is a part of the message (the length prefix MUST include it).</p>
135<p>If the piece is the last piece of the metadata, it may be less than 16kiB. If it
136is not the last piece of the metadata, it MUST be 16kiB.</p>
137<p>Example:</p>
138<pre class="literal-block">
139{'msg_type': 1, 'piece': 0, 'total_size': 3425}
140d8:msg_typei1e5:piecei0e10:total_sizei34256eexxxxxxxx...
141</pre>
142<p>The <tt class="docutils literal"><span class="pre">x</span></tt> represents binary data (the metadata).</p>
143</div>
144<div class="section" id="reject">
145<h2>reject</h2>
146<p>The <tt class="docutils literal"><span class="pre">reject</span></tt> message does not have any additional keys in its message.
147It SHOULD be interpreted as the peer does not have the piece of metadata
148that was requested.</p>
149<p>Clients MAY implement flood protection by rejecting <tt class="docutils literal"><span class="pre">request</span></tt> messages
150after a certain number of them have been served. Typically the number of
151pieces of metadata times a factor.</p>
152<p>Example:</p>
153<pre class="literal-block">
154{'msg_type': 2, 'piece': 0}
155d8:msg_typei1e5:piecei0ee
156</pre>
157</div>
158</div>
159<div class="section" id="magnet-uri-format">
160<h1>magnet URI format</h1>
161<p>The magnet URI format is:</p>
162<pre class="literal-block">
163magnet:?xt=urn:btih:&lt;info-hash&gt;&amp;dn=&lt;name&gt;&amp;tr=&lt;tracker-url&gt;
164</pre>
165<dl class="docutils">
166<dt>&lt;info-hash&gt;</dt>
167<dd>Is the info-hash encoded as base32 <a class="footnote-reference" href="#base32" id="id1">[1]</a></dd>
168</dl>
169<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
170used by the client to display while waiting for metadata. <tt class="docutils literal"><span class="pre">tr</span></tt> is a tracker
171url, if there is one. If there are multiple trackers, multiple <tt class="docutils literal"><span class="pre">tr</span></tt> entries
172may be included.</p>
173<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>
174<p>If no tracker is specified, the client SHOULD use the DHT (<a class="reference external" href="bep_0005.html">BEP 0005</a> <a class="footnote-reference" href="#id5" id="id6">[3]</a>) to acquire peers.</p>
175<table class="docutils footnote" frame="void" id="base32" rules="none">
176<colgroup><col class="label" /><col /></colgroup>
177<tbody valign="top">
178<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td><a class="reference external" href="http://www.ietf.org/rfc/rfc3548.txt">http://www.ietf.org/rfc/rfc3548.txt</a></td></tr>
179</tbody>
180</table>
181<!-- Local Variables:
182mode: indented-text
183indent-tabs-mode: nil
184sentence-end-double-space: t
185fill-column: 70
186coding: utf-8
187End: -->
188</div>
189<div class="section" id="id2">
190<h1>References</h1>
191<table class="docutils footnote" frame="void" id="id3" rules="none">
192<colgroup><col class="label" /><col /></colgroup>
193<tbody valign="top">
194<tr><td class="label"><a class="fn-backref" href="#id4">[2]</a></td><td><a class="reference external" href="http://www.bittorrent.org/beps/bep_0010.html">http://www.bittorrent.org/beps/bep_0010.html</a></td></tr>
195</tbody>
196</table>
197<table class="docutils footnote" frame="void" id="id5" rules="none">
198<colgroup><col class="label" /><col /></colgroup>
199<tbody valign="top">
200<tr><td class="label"><a class="fn-backref" href="#id6">[3]</a></td><td><a class="reference external" href="bep_0005.html">bep_0005.html</a></td></tr>
201</tbody>
202</table>
203</div>
204
205
206</div>
207        <div id="footer">
208<hr/>
209</div>
210
211</div>
212</body>
213</html>
Note: See TracBrowser for help on using the browser.