root / dotorg / trunk / html / beps / bep_0009.html

Revision 11071, 10.7 kB (checked in by dave, 2 days ago)

update html, commit changes to the BEP index. Separate accepted from draft BEPs.

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