wornvirtue
/
premiere-libtorrent
forked from premiere/premiere-libtorrent
1
0
Fork 0
Code Pull Requests Activity
premiere-libtorrent/docs/extension_protocol.html

253 lines
11 KiB
HTML
Raw Normal View History

merged back the asio development branch
2006-04-25 23:04:48 +02:00
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
added build notes for vs.net 2005, removed old code from ip_filter.cpp, fixed problem where the stats could become incorrect in case of very high cpu load, added asserts in storage::read() to make sure one is not trying to read out of bounds.
2006-07-26 12:21:25 +02:00
<meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
merged back the asio development branch
2006-04-25 23:04:48 +02:00
<title></title>
<meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com Ludvig Strigeus, ludde&#64;utorrent.com" />
added a projects page (listing some projects using libtorrent), including some screenshots thumbnails. Regenterated some docs, with new stylesheet.
2006-06-20 01:26:38 +02:00
<link rel="stylesheet" href="style.css" type="text/css" />
merged back the asio development branch
2006-04-25 23:04:48 +02:00
</head>
<body>
<div class="document">
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Arvid Norberg, <a class="reference" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a>
Ludvig Strigeus, <a class="last reference" href="mailto:ludde&#64;utorrent.com">ludde&#64;utorrent.com</a></td></tr>
</tbody>
</table>
added build notes for vs.net 2005, removed old code from ip_filter.cpp, fixed problem where the stats could become incorrect in case of very high cpu load, added asserts in storage::read() to make sure one is not trying to read out of bounds.
2006-07-26 12:21:25 +02:00
<div class="section" id="extension-protocol-for-bittorrent">
<h1><a name="extension-protocol-for-bittorrent">extension protocol for bittorrent</a></h1>
merged back the asio development branch
2006-04-25 23:04:48 +02:00
<p>The intention of this protocol is to provide a simple and thin transport
for extensions to the bittorrent protocol. Supporting this protocol makes
it easy to add new extensions without interfering with the standard
bittorrent protocol or clients that don't support this extension or the
one you want to add.</p>
<p>To advertise to other clients that you support, one bit from the reserved
bytes is used.</p>
<p>The bit selected for the extension protocol is bit 20 from the right (counting
starts at 0). So (reserved_byte[5] &amp; 0x10) is the expression to use for checking
if the client supports extended messaging.</p>
<p>Once support for the protocol is established, the client is supposed to
support 1 new message:</p>
<table border="1" class="docutils">
<colgroup>
<col width="86%" />
<col width="14%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">id</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">extended</span></tt></td>
<td>20</td>
</tr>
</tbody>
</table>
<p>This message is sent as any other bittorrent message, with a 4 byte length
prefix and a single byte identifying the message (the single byte being 20
in this case). At the start of the payload of the message, is a single byte
message identifier. This identifier can refer to different extension messages
and only one ID is specified, 0. If the ID is 0, the message is a handshake
message which is described below. The layout of a general <tt class="docutils literal"><span class="pre">extended</span></tt> message
follows (including the message headers used by the bittorrent protocol):</p>
<table border="1" class="docutils">
<colgroup>
<col width="15%" />
<col width="85%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">size</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>uint32_t</td>
<td>length prefix. Specifies the number of bytes for the
entire message. (Big endian)</td>
</tr>
<tr><td>uint8_t</td>
<td>bittorrent message ID, = 20</td>
</tr>
<tr><td>uint8_t</td>
<td>extended message ID. 0 = handshake, &gt;0 = extended
message as specified by the handshake.</td>
</tr>
</tbody>
</table>
added build notes for vs.net 2005, removed old code from ip_filter.cpp, fixed problem where the stats could become incorrect in case of very high cpu load, added asserts in storage::read() to make sure one is not trying to read out of bounds.
2006-07-26 12:21:25 +02:00
<div class="section" id="handshake-message">
<h2><a name="handshake-message">handshake message</a></h2>
merged back the asio development branch
2006-04-25 23:04:48 +02:00
<p>The payload of the handshake message is a bencoded dictionary. All items
in the dictionary are optional. Any unknown names should be ignored
by the client. All parts of the dictionary are case sensitive.
This is the defined item in the dictionary:</p>
<table border="1" class="docutils">
<colgroup>
<col width="11%" />
<col width="89%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>m</td>
doc updates and started adding documentation for new plugin interface
2006-11-27 01:04:20 +01:00
<td><p class="first">Dictionary of supported extension messages which maps
names of extensions to an extended message ID for each
extension message. The only requirement on these IDs
is that no extension message share the same one. Setting
merged back the asio development branch
2006-04-25 23:04:48 +02:00
an extension number to zero means that the extension is
not supported/disabled. The client should ignore any
doc updates and started adding documentation for new plugin interface
2006-11-27 01:04:20 +01:00
extension names it doesn't recognize.</p>
<p class="last">The extension message IDs are the IDs used to send the
extension messages to the peer sending this handshake.
i.e. The IDs are local to this particular peer.</p>
</td>
merged back the asio development branch
2006-04-25 23:04:48 +02:00
</tr>
</tbody>
</table>
doc updates and started adding documentation for new plugin interface
2006-11-27 01:04:20 +01:00
<p>Here are some other items that an implementation may choose to support:</p>
merged back the asio development branch
2006-04-25 23:04:48 +02:00
<table border="1" class="docutils">
<colgroup>
<col width="11%" />
<col width="89%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>p</td>
<td>Local TCP listen port. Allows each side to learn about
the TCP port number of the other side. Note that there is
no need for the receiving side of the connection to send
this extension message, since its port number is already
known.</td>
</tr>
<tr><td>v</td>
<td>Client name and version (as an utf-8 string).
This is a much more reliable way of identifying the
client than relying on the peer id encoding.</td>
</tr>
added a setting for max outstanding requests, and a limit for BitComet since it's known to have a very low limit, also added an extension header to specify it. Fixed another unnecessary delay spotted by Tianhao Qiu. Cleaned up the logging class a bit. Fixed a bug that would cause an assert when removing a torrent queued for checking.
2006-05-15 00:30:05 +02:00
<tr><td>reqq</td>
<td>An integer, the number of outstanding request messages
this client supports without dropping any. The default in
in libtorrent is 250.</td>
</tr>
merged back the asio development branch
2006-04-25 23:04:48 +02:00
</tbody>
</table>
<p>The handshake dictionary could also include extended handshake
information, such as support for encrypted headers or anything
imaginable.</p>
<p>An example of what the payload of a handshake message could look like:</p>
<table border="1" class="docutils">
<colgroup>
<col width="36%" />
<col width="64%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head" colspan="2">Dictionary</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">m</span></tt></td>
<td><table border="1" class="first last docutils">
<colgroup>
<col width="88%" />
<col width="12%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head" colspan="2">Dictionary</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">LT_metadata</span></tt></td>
<td>1</td>
</tr>
doc updates and started adding documentation for new plugin interface
2006-11-27 01:04:20 +01:00
<tr><td><tt class="docutils literal"><span class="pre">ut_pex</span></tt></td>
merged back the asio development branch
2006-04-25 23:04:48 +02:00
<td>2</td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">p</span></tt></td>
<td>6881</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">v</span></tt></td>
<td>&quot;µTorrent 1.2&quot;</td>
</tr>
</tbody>
</table>
<p>and in the encoded form:</p>
<p><tt class="docutils literal"><span class="pre">d1:md11:LT_metadatai1e6:µT_PEXi2ee1:pi6881e1:v13:\xc2\xb5Torrent</span> <span class="pre">1.2e</span></tt></p>
<p>To make sure the extension names do not collide by mistake, they should be
prefixed with the two (or one) character code that is used to identify the
client that introduced the extension. This applies for both the names of
extension messages, and for any additional information put inside the
top-level dictionary. All one and two byte identifiers are invalid to use
unless defined by this specification.</p>
<p>This message should be sent immediately after the standard bittorrent handshake
to any peer that supports this extension protocol. It is valid to send the
handshake message more than once during the lifetime of a connection,
the sending client should not be disconnected. An implementation may choose
to ignore the subsequent handshake messages (or parts of them).</p>
<p>Subsequent handshake messages can be used to enable/disable extensions
without restarting the connection. If a peer supports changing extensions
at run time, it should note that the <tt class="docutils literal"><span class="pre">m</span></tt> dictionary is additive.
It's enough that it contains the actual <em>CHANGES</em> to the extension list.
To disable the support for <tt class="docutils literal"><span class="pre">LT_metadata</span></tt> at run-time, without affecting
any other extensions, this message should be sent:
<tt class="docutils literal"><span class="pre">d11:LT_metadatai0ee</span></tt>.
As specified above, the value 0 is used to turn off an extension.</p>
<p>The extension IDs must be stored for every peer, becuase every peer may have
different IDs for the same extension.</p>
<p>This specification, deliberately, does not specify any extensions such as
peer-exchange or metadata exchange. This protocol is merely a transport
for the actual extensions to the bittorrent protocol and the extensions
named in the example above (such as <tt class="docutils literal"><span class="pre">p</span></tt>) are just examples of possible
extensions.</p>
</div>
added build notes for vs.net 2005, removed old code from ip_filter.cpp, fixed problem where the stats could become incorrect in case of very high cpu load, added asserts in storage::read() to make sure one is not trying to read out of bounds.
2006-07-26 12:21:25 +02:00
<div class="section" id="rationale">
<h2><a name="rationale">rationale</a></h2>
merged back the asio development branch
2006-04-25 23:04:48 +02:00
<p>The reason why the extension messages' IDs would be defined in the handshake
doc updates and started adding documentation for new plugin interface
2006-11-27 01:04:20 +01:00
is to avoid having a global registry of message IDs. Instead the names of the
extension messages requires unique names, which is much easier to do without
a global registry. The convention is to use a two letter prefix on the
extension message names, the prefix would identify the client first
implementing the extension message. e.g. <tt class="docutils literal"><span class="pre">LT_metadata</span></tt> is implemented by
libtorrent, and hence it has the <tt class="docutils literal"><span class="pre">LT</span></tt> prefix.</p>
merged back the asio development branch
2006-04-25 23:04:48 +02:00
<p>If the client supporting the extensions can decide which numbers the messages
it receives will have, it means they are constants within that client. i.e.
they can be used in <tt class="docutils literal"><span class="pre">switch</span></tt> statements. It's easy for the other end to
store an array with the ID's we expect for each message and use that for
lookups each time it sends an extension message.</p>
<p>The reason for having a dictionary instead of having an array (using
implicitly assigned index numbers to the extensions) is that if a client
want to disable some extensions, the ID numbers would change, and it wouldn't
be able to use constants (and hence, not use them in a <tt class="docutils literal"><span class="pre">switch</span></tt>). If the
messages IDs would map directly to bittorrent message IDs, It would also make
it possible to map extensions in the handshake to existing extensions with
fixed message IDs.</p>
<p>The reasoning behind having a single byte as extended message identifier is
to follow the the bittorrent spec. with its single byte message identifiers.
It is also considered to be enough. It won't limit the total number of
extensions, only the number of extensions used simultaneously.</p>
<p>The reason for using single byte identifiers for the standardized handshake
identifiers is 1) The mainline DHT uses single byte identifiers. 2) Saves
bandwidth. The only advantage of longer messages is that it makes the
protocol more readable for a human, but the BT protocol wasn't designed to
be a human readable protocol, so why bother.</p>
</div>
</div>
</div>
</body>
</html>