docs/features.rst

   1 =================
   2 libtorrent manual
   3 =================
   4
   5 :Author: Arvid Norberg, arvid@rasterbar.com
   6
   7 .. contents:: Table of contents
   8   :depth: 2
   9   :backlinks: none
  10
  11 introduction
  12 ============
  13
  14 libtorrent is a C++ library that aims to be a good alternative to all the
  15 other bittorrent implementations around. It is a
  16 library and not a full featured client, although it comes with a working
  17 example client.
  18
  19 The main goals of libtorrent are:
  20
  21 * to be cpu efficient
  22 * to be memory efficient
  23 * to be very easy to use
  24
  25 features
  26 ========
  27
  28 libtorrent is still being developed, however it is stable. It is an ongoing
  29 project (including this documentation). The current state includes the
  30 following features:
  31
  32 * trackerless torrents (using the Mainline kademlia DHT protocol) with
  33   some `DHT extensions`_.
  34 * support for IPv6
  35 * NAT-PMP and UPnP support (automatic port mapping on routers that supports it)
  36 * piece-wise, unordered, incremental file allocation
  37 * uses separate threads for checking files and for main downloader, with a
  38   fool-proof thread-safe library interface. (i.e. There's no way for the
  39   user to cause a deadlock). (see threads_)
  40 * adjusts the length of the request queue depending on download rate.
  41 * multitracker extension support (as `specified by John Hoffman`__)
  42 * supports files > 2 gigabytes.
  43 * serves multiple torrents on a single port and in a single thread
  44 * fast resume support, a way to get rid of the costly piece check at the
  45   start of a resumed torrent. Saves the storage state, piece_picker state
  46   as well as all local peers in a separate fast-resume file.
  47 * `HTTP seeding`_, as `specified by Michael Burford of GetRight`__.
  48 * piece picking on block-level (as opposed to piece-level).
  49   This means it can download parts of the same piece from different peers.
  50   It will also prefer to download whole pieces from single peers if the
  51   download speed is high enough from that particular peer.
  52 * supports the `udp-tracker protocol`_ by Olaf van der Spek.
  53 * queues torrents for file check, instead of checking all of them in parallel.
  54 * supports http proxies and basic proxy authentication
  55 * gzipped tracker-responses
  56 * can limit the upload and download bandwidth usage and the maximum number of
  57   unchoked peers
  58 * implements fair trade. User settable trade-ratio, must at least be 1:1,
  59   but one can choose to trade 1 for 2 or any other ratio that isn't unfair
  60   to the other party.
  61 * supports an `extension protocol`_. See extensions_.
  62 * supports the ``no_peer_id=1`` extension that will ease the load off trackers.
  63 * possibility to limit the number of connections.
  64 * delays have messages if there's no other outgoing traffic to the peer, and
  65   doesn't send have messages to peers that already has the piece. This saves
  66   bandwidth.
  67 * does not have any requirements on the piece order in a torrent that it
  68   resumes. This means it can resume a torrent downloaded by any client.
  69 * supports the ``compact=1`` tracker parameter.
  70 * selective downloading. The ability to select which parts of a torrent you
  71   want to download.
  72 * ip filter to disallow ip addresses and ip ranges from connecting and
  73   being connected
  74
  75 .. _`DHT extensions`: dht_extensions.html
  76 __ http://home.elp.rr.com/tur/multitracker-spec.txt
  77 __ http://www.getright.com/seedtorrent.html
  78 .. _`extension protocol`: extension_protocol.html
  79 .. _`udp-tracker protocol`: udp_tracker_protocol.html
  80
  81 portability
  82 ===========
  83
  84 libtorrent is portable at least among Windows, MacOS X and other UNIX-systems.
  85 It uses Boost.Thread, Boost.Filesystem, Boost.Date_time and various other
  86 boost libraries as well as zlib_ (shipped) and asio_ (shipped). At least version
  87 1.33.1 of boost is required.
  88
  89 .. _zlib: http://www.zlib.org
  90 .. _asio: http://asio.sf.net
  91
  92 Since libtorrent uses asio, it will take full advantage of high performance
  93 network APIs on the most popular platforms. I/O completion ports on windows,
  94 epoll on linux and kqueue on MacOS X and BSD.
  95
  96 libtorrent has been successfully compiled and tested on:
  97
  98 * Windows 2000 vc7.1, vc8
  99 * Linux x86 GCC 3.3, GCC 3.4.2
 100 * MacOS X (darwin), (Apple's) GCC 3.3, (Apple's) GCC 4.0
 101 * SunOS 5.8 GCC 3.1
 102 * Cygwin GCC 3.3.3
 103
 104 Fails on:
 105
 106 * GCC 2.95.4
 107 * msvc6
 108
 109 license
 110 =======
 111
 112 libtorrent is released under the BSD-license_.
 113
 114 .. _BSD-license: http://www.opensource.org/licenses/bsd-license.php
 115
 116 This means that you can use the library in your project without having to
 117 release its source code. The only requirement is that you give credit
 118 to the author of the library by including the libtorrent license in your
 119 software or documentation.
 120
 121 `Here's`__ a list of some projects that uses libtorrent.
 122
 123 __ projects.html
 124
 125 .. _`http seeding`: manual.html#http-seeding
 126 .. _threads: manual.html#threads
 127 .. _extensions: manual.html#extensions
 128