premiere
/
premiere-libtorrent
2
2
Fork 1
Code Issues Pull Requests Releases Wiki Activity

added per file progress, added patch suggested by Tianhao Qui regarding unchoking when a peer becomes uninterested. Updated documentation and removed block quotes around bullet lists.

This commit is contained in:
Arvid Norberg 2006-06-11 13:48:39 +00:00
parent 3d06c0636a
commit 25dae899f0
5 changed files with 187 additions and 147 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

179
docs/manual.html
View File

@ -189,101 +189,102 @@ div.warning, div.note, div.important {
</ul> </ul>
</li> </li>
<li><a class="reference" href="#torrent-handle" id="id63" name="id63">torrent_handle</a><ul> <li><a class="reference" href="#torrent-handle" id="id63" name="id63">torrent_handle</a><ul>
<li><a class="reference" href="#save-path" id="id64" name="id64">save_path()</a></li> <li><a class="reference" href="#file-progress" id="id64" name="id64">file_progress()</a></li>
<li><a class="reference" href="#move-storage" id="id65" name="id65">move_storage()</a></li> <li><a class="reference" href="#save-path" id="id65" name="id65">save_path()</a></li>
<li><a class="reference" href="#force-reannounce" id="id66" name="id66">force_reannounce()</a></li> <li><a class="reference" href="#move-storage" id="id66" name="id66">move_storage()</a></li>
<li><a class="reference" href="#connect-peer" id="id67" name="id67">connect_peer()</a></li> <li><a class="reference" href="#force-reannounce" id="id67" name="id67">force_reannounce()</a></li>
<li><a class="reference" href="#set-ratio" id="id68" name="id68">set_ratio()</a></li> <li><a class="reference" href="#connect-peer" id="id68" name="id68">connect_peer()</a></li>
<li><a class="reference" href="#set-upload-limit-set-download-limit" id="id69" name="id69">set_upload_limit() set_download_limit()</a></li> <li><a class="reference" href="#set-ratio" id="id69" name="id69">set_ratio()</a></li>
<li><a class="reference" href="#set-peer-upload-limit-set-peer-download-limit" id="id70" name="id70">set_peer_upload_limit() set_peer_download_limit()</a></li> <li><a class="reference" href="#set-upload-limit-set-download-limit" id="id70" name="id70">set_upload_limit() set_download_limit()</a></li>
<li><a class="reference" href="#pause-resume-is-paused" id="id71" name="id71">pause() resume() is_paused()</a></li> <li><a class="reference" href="#set-peer-upload-limit-set-peer-download-limit" id="id71" name="id71">set_peer_upload_limit() set_peer_download_limit()</a></li>
<li><a class="reference" href="#is-seed" id="id72" name="id72">is_seed()</a></li> <li><a class="reference" href="#pause-resume-is-paused" id="id72" name="id72">pause() resume() is_paused()</a></li>
<li><a class="reference" href="#has-metadata" id="id73" name="id73">has_metadata()</a></li> <li><a class="reference" href="#is-seed" id="id73" name="id73">is_seed()</a></li>
<li><a class="reference" href="#set-tracker-login" id="id74" name="id74">set_tracker_login()</a></li> <li><a class="reference" href="#has-metadata" id="id74" name="id74">has_metadata()</a></li>
<li><a class="reference" href="#trackers-replace-trackers" id="id75" name="id75">trackers() replace_trackers()</a></li> <li><a class="reference" href="#set-tracker-login" id="id75" name="id75">set_tracker_login()</a></li>
<li><a class="reference" href="#add-url-seed" id="id76" name="id76">add_url_seed()</a></li> <li><a class="reference" href="#trackers-replace-trackers" id="id76" name="id76">trackers() replace_trackers()</a></li>
<li><a class="reference" href="#use-interface" id="id77" name="id77">use_interface()</a></li> <li><a class="reference" href="#add-url-seed" id="id77" name="id77">add_url_seed()</a></li>
<li><a class="reference" href="#info-hash" id="id78" name="id78">info_hash()</a></li> <li><a class="reference" href="#use-interface" id="id78" name="id78">use_interface()</a></li>
<li><a class="reference" href="#id13" id="id79" name="id79">set_max_uploads() set_max_connections()</a></li> <li><a class="reference" href="#info-hash" id="id79" name="id79">info_hash()</a></li>
<li><a class="reference" href="#write-resume-data" id="id80" name="id80">write_resume_data()</a></li> <li><a class="reference" href="#id13" id="id80" name="id80">set_max_uploads() set_max_connections()</a></li>
<li><a class="reference" href="#metadata" id="id81" name="id81">metadata()</a></li> <li><a class="reference" href="#write-resume-data" id="id81" name="id81">write_resume_data()</a></li>
<li><a class="reference" href="#id14" id="id82" name="id82">status()</a></li> <li><a class="reference" href="#metadata" id="id82" name="id82">metadata()</a></li>
<li><a class="reference" href="#get-download-queue" id="id83" name="id83">get_download_queue()</a></li> <li><a class="reference" href="#id14" id="id83" name="id83">status()</a></li>
<li><a class="reference" href="#get-peer-info" id="id84" name="id84">get_peer_info()</a></li> <li><a class="reference" href="#get-download-queue" id="id84" name="id84">get_download_queue()</a></li>
<li><a class="reference" href="#get-torrent-info" id="id85" name="id85">get_torrent_info()</a></li> <li><a class="reference" href="#get-peer-info" id="id85" name="id85">get_peer_info()</a></li>
<li><a class="reference" href="#is-valid" id="id86" name="id86">is_valid()</a></li> <li><a class="reference" href="#get-torrent-info" id="id86" name="id86">get_torrent_info()</a></li>
<li><a class="reference" href="#is-valid" id="id87" name="id87">is_valid()</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#torrent-status" id="id87" name="id87">torrent_status</a></li> <li><a class="reference" href="#torrent-status" id="id88" name="id88">torrent_status</a></li>
<li><a class="reference" href="#peer-info" id="id88" name="id88">peer_info</a></li> <li><a class="reference" href="#peer-info" id="id89" name="id89">peer_info</a></li>
<li><a class="reference" href="#session-settings" id="id89" name="id89">session_settings</a></li> <li><a class="reference" href="#session-settings" id="id90" name="id90">session_settings</a></li>
<li><a class="reference" href="#ip-filter" id="id90" name="id90">ip_filter</a><ul> <li><a class="reference" href="#ip-filter" id="id91" name="id91">ip_filter</a><ul>
<li><a class="reference" href="#id17" id="id91" name="id91">ip_filter()</a></li> <li><a class="reference" href="#id17" id="id92" name="id92">ip_filter()</a></li>
<li><a class="reference" href="#add-rule" id="id92" name="id92">add_rule()</a></li> <li><a class="reference" href="#add-rule" id="id93" name="id93">add_rule()</a></li>
<li><a class="reference" href="#access" id="id93" name="id93">access()</a></li> <li><a class="reference" href="#access" id="id94" name="id94">access()</a></li>
<li><a class="reference" href="#export-filter" id="id94" name="id94">export_filter()</a></li> <li><a class="reference" href="#export-filter" id="id95" name="id95">export_filter()</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#big-number" id="id95" name="id95">big_number</a></li> <li><a class="reference" href="#big-number" id="id96" name="id96">big_number</a></li>
<li><a class="reference" href="#hasher" id="id96" name="id96">hasher</a></li> <li><a class="reference" href="#hasher" id="id97" name="id97">hasher</a></li>
<li><a class="reference" href="#fingerprint" id="id97" name="id97">fingerprint</a></li> <li><a class="reference" href="#fingerprint" id="id98" name="id98">fingerprint</a></li>
<li><a class="reference" href="#free-functions" id="id98" name="id98">free functions</a><ul> <li><a class="reference" href="#free-functions" id="id99" name="id99">free functions</a><ul>
<li><a class="reference" href="#identify-client" id="id99" name="id99">identify_client()</a></li> <li><a class="reference" href="#identify-client" id="id100" name="id100">identify_client()</a></li>
<li><a class="reference" href="#client-fingerprint" id="id100" name="id100">client_fingerprint()</a></li> <li><a class="reference" href="#client-fingerprint" id="id101" name="id101">client_fingerprint()</a></li>
<li><a class="reference" href="#bdecode-bencode" id="id101" name="id101">bdecode() bencode()</a></li> <li><a class="reference" href="#bdecode-bencode" id="id102" name="id102">bdecode() bencode()</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#alerts" id="id102" name="id102">alerts</a><ul> <li><a class="reference" href="#alerts" id="id103" name="id103">alerts</a><ul>
<li><a class="reference" href="#listen-failed-alert" id="id103" name="id103">listen_failed_alert</a></li> <li><a class="reference" href="#listen-failed-alert" id="id104" name="id104">listen_failed_alert</a></li>
<li><a class="reference" href="#file-error-alert" id="id104" name="id104">file_error_alert</a></li> <li><a class="reference" href="#file-error-alert" id="id105" name="id105">file_error_alert</a></li>
<li><a class="reference" href="#tracker-announce-alert" id="id105" name="id105">tracker_announce_alert</a></li> <li><a class="reference" href="#tracker-announce-alert" id="id106" name="id106">tracker_announce_alert</a></li>
<li><a class="reference" href="#tracker-alert" id="id106" name="id106">tracker_alert</a></li> <li><a class="reference" href="#tracker-alert" id="id107" name="id107">tracker_alert</a></li>
<li><a class="reference" href="#tracker-reply-alert" id="id107" name="id107">tracker_reply_alert</a></li> <li><a class="reference" href="#tracker-reply-alert" id="id108" name="id108">tracker_reply_alert</a></li>
<li><a class="reference" href="#tracker-warning-alert" id="id108" name="id108">tracker_warning_alert</a></li> <li><a class="reference" href="#tracker-warning-alert" id="id109" name="id109">tracker_warning_alert</a></li>
<li><a class="reference" href="#url-seed-alert" id="id109" name="id109">url_seed_alert</a></li> <li><a class="reference" href="#url-seed-alert" id="id110" name="id110">url_seed_alert</a></li>
<li><a class="reference" href="#hash-failed-alert" id="id110" name="id110">hash_failed_alert</a></li> <li><a class="reference" href="#hash-failed-alert" id="id111" name="id111">hash_failed_alert</a></li>
<li><a class="reference" href="#peer-ban-alert" id="id111" name="id111">peer_ban_alert</a></li> <li><a class="reference" href="#peer-ban-alert" id="id112" name="id112">peer_ban_alert</a></li>
<li><a class="reference" href="#peer-error-alert" id="id112" name="id112">peer_error_alert</a></li> <li><a class="reference" href="#peer-error-alert" id="id113" name="id113">peer_error_alert</a></li>
<li><a class="reference" href="#invalid-request-alert" id="id113" name="id113">invalid_request_alert</a></li> <li><a class="reference" href="#invalid-request-alert" id="id114" name="id114">invalid_request_alert</a></li>
<li><a class="reference" href="#torrent-finished-alert" id="id114" name="id114">torrent_finished_alert</a></li> <li><a class="reference" href="#torrent-finished-alert" id="id115" name="id115">torrent_finished_alert</a></li>
<li><a class="reference" href="#metadata-failed-alert" id="id115" name="id115">metadata_failed_alert</a></li> <li><a class="reference" href="#metadata-failed-alert" id="id116" name="id116">metadata_failed_alert</a></li>
<li><a class="reference" href="#metadata-received-alert" id="id116" name="id116">metadata_received_alert</a></li> <li><a class="reference" href="#metadata-received-alert" id="id117" name="id117">metadata_received_alert</a></li>
<li><a class="reference" href="#fastresume-rejected-alert" id="id117" name="id117">fastresume_rejected_alert</a></li> <li><a class="reference" href="#fastresume-rejected-alert" id="id118" name="id118">fastresume_rejected_alert</a></li>
<li><a class="reference" href="#dispatcher" id="id118" name="id118">dispatcher</a></li> <li><a class="reference" href="#dispatcher" id="id119" name="id119">dispatcher</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#exceptions" id="id119" name="id119">exceptions</a><ul> <li><a class="reference" href="#exceptions" id="id120" name="id120">exceptions</a><ul>
<li><a class="reference" href="#invalid-handle" id="id120" name="id120">invalid_handle</a></li> <li><a class="reference" href="#invalid-handle" id="id121" name="id121">invalid_handle</a></li>
<li><a class="reference" href="#duplicate-torrent" id="id121" name="id121">duplicate_torrent</a></li> <li><a class="reference" href="#duplicate-torrent" id="id122" name="id122">duplicate_torrent</a></li>
<li><a class="reference" href="#invalid-encoding" id="id122" name="id122">invalid_encoding</a></li> <li><a class="reference" href="#invalid-encoding" id="id123" name="id123">invalid_encoding</a></li>
<li><a class="reference" href="#type-error" id="id123" name="id123">type_error</a></li> <li><a class="reference" href="#type-error" id="id124" name="id124">type_error</a></li>
<li><a class="reference" href="#invalid-torrent-file" id="id124" name="id124">invalid_torrent_file</a></li> <li><a class="reference" href="#invalid-torrent-file" id="id125" name="id125">invalid_torrent_file</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#examples" id="id125" name="id125">examples</a><ul> <li><a class="reference" href="#examples" id="id126" name="id126">examples</a><ul>
<li><a class="reference" href="#dump-torrent" id="id126" name="id126">dump_torrent</a></li> <li><a class="reference" href="#dump-torrent" id="id127" name="id127">dump_torrent</a></li>
<li><a class="reference" href="#simple-client" id="id127" name="id127">simple client</a></li> <li><a class="reference" href="#simple-client" id="id128" name="id128">simple client</a></li>
<li><a class="reference" href="#make-torrent" id="id128" name="id128">make_torrent</a></li> <li><a class="reference" href="#make-torrent" id="id129" name="id129">make_torrent</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#fast-resume" id="id129" name="id129">fast resume</a><ul> <li><a class="reference" href="#fast-resume" id="id130" name="id130">fast resume</a><ul>
<li><a class="reference" href="#file-format" id="id130" name="id130">file format</a></li> <li><a class="reference" href="#file-format" id="id131" name="id131">file format</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#threads" id="id131" name="id131">threads</a></li> <li><a class="reference" href="#threads" id="id132" name="id132">threads</a></li>
<li><a class="reference" href="#storage-allocation" id="id132" name="id132">storage allocation</a><ul> <li><a class="reference" href="#storage-allocation" id="id133" name="id133">storage allocation</a><ul>
<li><a class="reference" href="#full-allocation" id="id133" name="id133">full allocation</a></li> <li><a class="reference" href="#full-allocation" id="id134" name="id134">full allocation</a></li>
<li><a class="reference" href="#compact-allocation" id="id134" name="id134">compact allocation</a></li> <li><a class="reference" href="#compact-allocation" id="id135" name="id135">compact allocation</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#extensions" id="id135" name="id135">extensions</a><ul> <li><a class="reference" href="#extensions" id="id136" name="id136">extensions</a><ul>
<li><a class="reference" href="#chat-messages" id="id136" name="id136">chat messages</a></li> <li><a class="reference" href="#chat-messages" id="id137" name="id137">chat messages</a></li>
<li><a class="reference" href="#metadata-from-peers" id="id137" name="id137">metadata from peers</a></li> <li><a class="reference" href="#metadata-from-peers" id="id138" name="id138">metadata from peers</a></li>
<li><a class="reference" href="#http-seeding" id="id138" name="id138">HTTP seeding</a></li> <li><a class="reference" href="#http-seeding" id="id139" name="id139">HTTP seeding</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#filename-checks" id="id139" name="id139">filename checks</a></li> <li><a class="reference" href="#filename-checks" id="id140" name="id140">filename checks</a></li>
<li><a class="reference" href="#acknowledgments" id="id140" name="id140">acknowledgments</a></li> <li><a class="reference" href="#acknowledgments" id="id141" name="id141">acknowledgments</a></li>
</ul> </ul>
</div> </div>
<div class="section"> <div class="section">
@ -293,17 +294,14 @@ other bittorrent implementations around. It is a
library and not a full featured client, although it comes with a working library and not a full featured client, although it comes with a working
example client.</p> example client.</p>
<p>The main goals of libtorrent are:</p> <p>The main goals of libtorrent are:</p>
<blockquote>
<ul class="simple"> <ul class="simple">
<li>to be cpu efficient</li> <li>to be cpu efficient</li>
<li>to be memory efficient</li> <li>to be memory efficient</li>
<li>to be very easy to use</li> <li>to be very easy to use</li>
</ul> </ul>
</blockquote>
<p>libtorrent is still being developed, however it is stable. It is an ongoing <p>libtorrent is still being developed, however it is stable. It is an ongoing
project (including this documentation). The current state includes the project (including this documentation). The current state includes the
following features:</p> following features:</p>
<blockquote>
<ul class="simple"> <ul class="simple">
<li>multitracker extension support (as <a class="reference" href="http://home.elp.rr.com/tur/multitracker-spec.txt">specified by John Hoffman</a>)</li> <li>multitracker extension support (as <a class="reference" href="http://home.elp.rr.com/tur/multitracker-spec.txt">specified by John Hoffman</a>)</li>
<li>serves multiple torrents on a single port and a single thread</li> <li>serves multiple torrents on a single port and a single thread</li>
@ -343,7 +341,6 @@ resumes. This means it can resume a torrent downloaded by any client.</li>
want to download.</li> want to download.</li>
<li>ip filter</li> <li>ip filter</li>
</ul> </ul>
</blockquote>
<p>libtorrent is portable at least among Windows, MacOS X and other UNIX-systems. <p>libtorrent is portable at least among Windows, MacOS X and other UNIX-systems.
It uses Boost.Thread, Boost.Filesystem, Boost.Date_time and various other It uses Boost.Thread, Boost.Filesystem, Boost.Date_time and various other
boost libraries as well as <a class="reference" href="http://www.zlib.org">zlib</a> (shipped) and <a class="reference" href="http://asio.sf.net">asio</a> (shipped). At least version boost libraries as well as <a class="reference" href="http://www.zlib.org">zlib</a> (shipped) and <a class="reference" href="http://asio.sf.net">asio</a> (shipped). At least version
@ -352,7 +349,6 @@ boost libraries as well as <a class="reference" href="http://www.zlib.org">zlib<
network APIs on the most popular platforms. I/O completion ports on windows, network APIs on the most popular platforms. I/O completion ports on windows,
epoll on linux and kqueue on MacOS X and BSD.</p> epoll on linux and kqueue on MacOS X and BSD.</p>
<p>libtorrent has been successfully compiled and tested on:</p> <p>libtorrent has been successfully compiled and tested on:</p>
<blockquote>
<ul class="simple"> <ul class="simple">
<li>Windows 2000 vc7.1</li> <li>Windows 2000 vc7.1</li>
<li>Linux x86 GCC 3.3, GCC 3.4.2</li> <li>Linux x86 GCC 3.3, GCC 3.4.2</li>
@ -360,14 +356,11 @@ epoll on linux and kqueue on MacOS X and BSD.</p>
<li>SunOS 5.8 GCC 3.1</li> <li>SunOS 5.8 GCC 3.1</li>
<li>Cygwin GCC 3.3.3</li> <li>Cygwin GCC 3.3.3</li>
</ul> </ul>
</blockquote>
<p>Fails on:</p> <p>Fails on:</p>
<blockquote>
<ul class="simple"> <ul class="simple">
<li>GCC 2.95.4</li> <li>GCC 2.95.4</li>
<li>msvc6</li> <li>msvc6</li>
</ul> </ul>
</blockquote>
<p>libtorrent is released under the <a class="reference" href="http://www.opensource.org/licenses/bsd-license.php">BSD-license</a>.</p> <p>libtorrent is released under the <a class="reference" href="http://www.opensource.org/licenses/bsd-license.php">BSD-license</a>.</p>
<p>This means that you can use the library in your project without having to <p>This means that you can use the library in your project without having to
release its source code. The only requirement is that you give credit release its source code. The only requirement is that you give credit
@ -500,7 +493,6 @@ and release_log, these two variants inherits from the debug and release
variants respectively, but adds extra logging (<tt class="docutils literal"><span class="pre">TORRENT_VERBOSE_LOGGING</span></tt>). variants respectively, but adds extra logging (<tt class="docutils literal"><span class="pre">TORRENT_VERBOSE_LOGGING</span></tt>).
For more build configuration flags see <a class="reference" href="#build-configurations">Build configurations</a>.</p> For more build configuration flags see <a class="reference" href="#build-configurations">Build configurations</a>.</p>
<p>The <tt class="docutils literal"><span class="pre">Jamfile</span></tt> has the following build variants:</p> <p>The <tt class="docutils literal"><span class="pre">Jamfile</span></tt> has the following build variants:</p>
<blockquote>
<ul class="simple"> <ul class="simple">
<li><tt class="docutils literal"><span class="pre">release</span></tt> - release version without any logging</li> <li><tt class="docutils literal"><span class="pre">release</span></tt> - release version without any logging</li>
<li><tt class="docutils literal"><span class="pre">release_log</span></tt> - release version with standard logging</li> <li><tt class="docutils literal"><span class="pre">release_log</span></tt> - release version with standard logging</li>
@ -509,7 +501,6 @@ For more build configuration flags see <a class="reference" href="#build-configu
<li><tt class="docutils literal"><span class="pre">debug_log</span></tt> - debug version with standard logging</li> <li><tt class="docutils literal"><span class="pre">debug_log</span></tt> - debug version with standard logging</li>
<li><tt class="docutils literal"><span class="pre">debug_vlog</span></tt> - debug version with verbose logging</li> <li><tt class="docutils literal"><span class="pre">debug_vlog</span></tt> - debug version with verbose logging</li>
</ul> </ul>
</blockquote>
<p>When building the example client on windows, you need to build with <p>When building the example client on windows, you need to build with
<tt class="docutils literal"><span class="pre">link=static</span></tt> otherwise you may get unresolved external symbols for some <tt class="docutils literal"><span class="pre">link=static</span></tt> otherwise you may get unresolved external symbols for some
boost.program-options symbols.</p> boost.program-options symbols.</p>
@ -1244,7 +1235,6 @@ public:
boost::optional&lt;boost::posix_time::ptime&gt; boost::optional&lt;boost::posix_time::ptime&gt;
creation_date() const; creation_date() const;
void print(std::ostream&amp; os) const; void print(std::ostream&amp; os) const;
size_type piece_size(unsigned int index) const; size_type piece_size(unsigned int index) const;
@ -1517,6 +1507,7 @@ struct torrent_handle
torrent_handle(); torrent_handle();
torrent_status status(); torrent_status status();
void file_progress(std::vector&lt;float&gt;&amp; fp);
void get_download_queue(std::vector&lt;partial_piece_info&gt;&amp; queue) const; void get_download_queue(std::vector&lt;partial_piece_info&gt;&amp; queue) const;
void get_peer_info(std::vector&lt;peer_info&gt;&amp; v) const; void get_peer_info(std::vector&lt;peer_info&gt;&amp; v) const;
torrent_info const&amp; get_torrent_info() const; torrent_info const&amp; get_torrent_info() const;
@ -1575,6 +1566,18 @@ perform any operation on it, unless you first assign it a valid handle. If you t
any operation on an uninitialized handle, it will throw <tt class="docutils literal"><span class="pre">invalid_handle</span></tt>.</p> any operation on an uninitialized handle, it will throw <tt class="docutils literal"><span class="pre">invalid_handle</span></tt>.</p>
<p><em>TODO: document filter_piece(), filter_pieces(), is_piece_filtered(), filtered_pieces() and filter_files()</em></p> <p><em>TODO: document filter_piece(), filter_pieces(), is_piece_filtered(), filtered_pieces() and filter_files()</em></p>
<div class="section"> <div class="section">
<h2><a id="file-progress" name="file-progress">file_progress()</a></h2>
<blockquote>
<pre class="literal-block">
void file_progress(std::vector&lt;float&gt;&amp; fp);
</pre>
</blockquote>
<p>This function fills in the supplied vector with the progress (a value in the
range [0, 1]) describing the download progress of each file in this torrent.
The progress values are ordered the same as the files in the <a class="reference" href="#torrent-info">torrent_info</a>.
This operation is not very cheap.</p>
</div>
<div class="section">
<h2><a id="save-path" name="save-path">save_path()</a></h2> <h2><a id="save-path" name="save-path">save_path()</a></h2>
<blockquote> <blockquote>
<pre class="literal-block"> <pre class="literal-block">

123
docs/manual.rst
View File

@ -18,51 +18,51 @@ example client.
The main goals of libtorrent are: The main goals of libtorrent are:
* to be cpu efficient * to be cpu efficient
* to be memory efficient * to be memory efficient
* to be very easy to use * to be very easy to use
libtorrent is still being developed, however it is stable. It is an ongoing libtorrent is still being developed, however it is stable. It is an ongoing
project (including this documentation). The current state includes the project (including this documentation). The current state includes the
following features: following features:
* multitracker extension support (as `specified by John Hoffman`__) * multitracker extension support (as `specified by John Hoffman`__)
* serves multiple torrents on a single port and a single thread * serves multiple torrents on a single port and a single thread
* supports http proxies and proxy authentication * supports http proxies and proxy authentication
* gzipped tracker-responses * gzipped tracker-responses
* `HTTP seeding`_, as `specified by Michael Burford of GetRight`__. * `HTTP seeding`_, as `specified by Michael Burford of GetRight`__.
* piece picking on block-level like in Azureus_ (as opposed to piece-level). * piece picking on block-level like in Azureus_ (as opposed to piece-level).
This means it can download parts of the same piece from different peers. This means it can download parts of the same piece from different peers.
It will also prefer to download whole pieces from single peers if the It will also prefer to download whole pieces from single peers if the
download speed is high enough from that particular peer. download speed is high enough from that particular peer.
* queues torrents for file check, instead of checking all of them in parallel. * queues torrents for file check, instead of checking all of them in parallel.
* uses separate threads for checking files and for main downloader, with a * uses separate threads for checking files and for main downloader, with a
fool-proof thread-safe library interface. (i.e. There's no way for the fool-proof thread-safe library interface. (i.e. There's no way for the
user to cause a deadlock). (see threads_) user to cause a deadlock). (see threads_)
* can limit the upload and download bandwidth usage and the maximum number of * can limit the upload and download bandwidth usage and the maximum number of
unchoked peers unchoked peers
* piece-wise, unordered, incremental file allocation * piece-wise, unordered, incremental file allocation
* implements fair trade. User settable trade-ratio, must at least be 1:1, * implements fair trade. User settable trade-ratio, must at least be 1:1,
but one can choose to trade 1 for 2 or any other ratio that isn't unfair but one can choose to trade 1 for 2 or any other ratio that isn't unfair
to the other party. to the other party.
* fast resume support, a way to get rid of the costly piece check at the * fast resume support, a way to get rid of the costly piece check at the
start of a resumed torrent. Saves the storage state, piece_picker state start of a resumed torrent. Saves the storage state, piece_picker state
as well as all local peers in a separate fast-resume file. as well as all local peers in a separate fast-resume file.
* supports an `extension protocol`__. See extensions_. * supports an `extension protocol`__. See extensions_.
* supports files > 2 gigabytes. * supports files > 2 gigabytes.
* supports the ``no_peer_id=1`` extension that will ease the load off trackers. * supports the ``no_peer_id=1`` extension that will ease the load off trackers.
* supports the `udp-tracker protocol`__ by Olaf van der Spek. * supports the `udp-tracker protocol`__ by Olaf van der Spek.
* possibility to limit the number of connections. * possibility to limit the number of connections.
* delays have messages if there's no other outgoing traffic to the peer, and * delays have messages if there's no other outgoing traffic to the peer, and
doesn't send have messages to peers that already has the piece. This saves doesn't send have messages to peers that already has the piece. This saves
bandwidth. bandwidth.
* does not have any requirements on the piece order in a torrent that it * does not have any requirements on the piece order in a torrent that it
resumes. This means it can resume a torrent downloaded by any client. resumes. This means it can resume a torrent downloaded by any client.
* adjusts the length of the request queue depending on download rate. * adjusts the length of the request queue depending on download rate.
* supports the ``compact=1`` tracker parameter. * supports the ``compact=1`` tracker parameter.
* selective downloading. The ability to select which parts of a torrent you * selective downloading. The ability to select which parts of a torrent you
want to download. want to download.
* ip filter * ip filter
__ http://home.elp.rr.com/tur/multitracker-spec.txt __ http://home.elp.rr.com/tur/multitracker-spec.txt
__ http://www.getright.com/seedtorrent.html __ http://www.getright.com/seedtorrent.html
@ -84,16 +84,16 @@ epoll on linux and kqueue on MacOS X and BSD.
libtorrent has been successfully compiled and tested on: libtorrent has been successfully compiled and tested on:
* Windows 2000 vc7.1 * Windows 2000 vc7.1
* Linux x86 GCC 3.3, GCC 3.4.2 * Linux x86 GCC 3.3, GCC 3.4.2
* MacOS X (darwin), (Apple's) GCC 3.3, (Apple's) GCC 4.0 * MacOS X (darwin), (Apple's) GCC 3.3, (Apple's) GCC 4.0
* SunOS 5.8 GCC 3.1 * SunOS 5.8 GCC 3.1
* Cygwin GCC 3.3.3 * Cygwin GCC 3.3.3
Fails on: Fails on:
* GCC 2.95.4 * GCC 2.95.4
* msvc6 * msvc6
libtorrent is released under the BSD-license_. libtorrent is released under the BSD-license_.
@ -263,12 +263,12 @@ For more build configuration flags see `Build configurations`_.
The ``Jamfile`` has the following build variants: The ``Jamfile`` has the following build variants:
* ``release`` - release version without any logging * ``release`` - release version without any logging
* ``release_log`` - release version with standard logging * ``release_log`` - release version with standard logging
* ``release_vlog`` - release version with verbose logging (all peer connections are logged) * ``release_vlog`` - release version with verbose logging (all peer connections are logged)
* ``debug`` - debug version without any logging * ``debug`` - debug version without any logging
* ``debug_log`` - debug version with standard logging * ``debug_log`` - debug version with standard logging
* ``debug_vlog`` - debug version with verbose logging * ``debug_vlog`` - debug version with verbose logging
When building the example client on windows, you need to build with When building the example client on windows, you need to build with
``link=static`` otherwise you may get unresolved external symbols for some ``link=static`` otherwise you may get unresolved external symbols for some
@ -1039,7 +1039,6 @@ The ``torrent_info`` has the following synopsis::
boost::optional<boost::posix_time::ptime> boost::optional<boost::posix_time::ptime>
creation_date() const; creation_date() const;
void print(std::ostream& os) const; void print(std::ostream& os) const;
size_type piece_size(unsigned int index) const; size_type piece_size(unsigned int index) const;
@ -1335,8 +1334,6 @@ it will return an empty string.
__ http://www.boost.org/libs/date_time/doc/class_ptime.html __ http://www.boost.org/libs/date_time/doc/class_ptime.html
torrent_handle torrent_handle
============== ==============
@ -1349,6 +1346,7 @@ Its declaration looks like this::
torrent_handle(); torrent_handle();
torrent_status status(); torrent_status status();
void file_progress(std::vector<float>& fp);
void get_download_queue(std::vector<partial_piece_info>& queue) const; void get_download_queue(std::vector<partial_piece_info>& queue) const;
void get_peer_info(std::vector<peer_info>& v) const; void get_peer_info(std::vector<peer_info>& v) const;
torrent_info const& get_torrent_info() const; torrent_info const& get_torrent_info() const;
@ -1408,6 +1406,19 @@ any operation on an uninitialized handle, it will throw ``invalid_handle``.
*TODO: document filter_piece(), filter_pieces(), is_piece_filtered(), filtered_pieces() and filter_files()* *TODO: document filter_piece(), filter_pieces(), is_piece_filtered(), filtered_pieces() and filter_files()*
file_progress()
---------------
::
void file_progress(std::vector<float>& fp);
This function fills in the supplied vector with the progress (a value in the
range [0, 1]) describing the download progress of each file in this torrent.
The progress values are ordered the same as the files in the `torrent_info`_.
This operation is not very cheap.
save_path() save_path()
----------- -----------

23
examples/client_test.cpp
View File

@ -625,6 +625,7 @@ int main(int ac, char* av[])
bool print_peers = false; bool print_peers = false;
bool print_log = false; bool print_log = false;
bool print_downloads = false; bool print_downloads = false;
bool print_file_progress = false;
for (;;) for (;;)
{ {
@ -679,6 +680,7 @@ int main(int ac, char* av[])
if (c == 'i') print_peers = !print_peers; if (c == 'i') print_peers = !print_peers;
if (c == 'l') print_log = !print_log; if (c == 'l') print_log = !print_log;
if (c == 'd') print_downloads = !print_downloads; if (c == 'd') print_downloads = !print_downloads;
if (c == 'f') print_file_progress = !print_file_progress;
} }
// loop through the alert queue to see if anything has happened. // loop through the alert queue to see if anything has happened.
@ -827,6 +829,27 @@ int main(int ac, char* av[])
out << "___________________________________\n"; out << "___________________________________\n";
} }
if (print_file_progress
&& s.state != torrent_status::seeding
&& h.has_metadata())
{
std::vector<float> file_progress;
h.file_progress(file_progress);
torrent_info const& info = h.get_torrent_info();
for (int i = 0; i < info.num_files(); ++i)
{
if (file_progress[i] == 1.f)
out << progress_bar(file_progress[i], 10, "32") << " "
<< info.file_at(i).path.leaf() << "\n";
else
out << progress_bar(file_progress[i], 10, "33") << " "
<< info.file_at(i).path.leaf() << "\n";
}
out << "___________________________________\n";
}
} }
if (print_log) if (print_log)

1
include/libtorrent/torrent.hpp
View File

@ -169,6 +169,7 @@ namespace libtorrent
void filter_files(std::vector<bool> const& files); void filter_files(std::vector<bool> const& files);
torrent_status status() const; torrent_status status() const;
void file_progress(std::vector<float>& fp) const;
void use_interface(const char* net_interface); void use_interface(const char* net_interface);
tcp::endpoint const& get_interface() const { return m_net_interface; } tcp::endpoint const& get_interface() const { return m_net_interface; }

8
include/libtorrent/torrent_handle.hpp
View File

@ -224,6 +224,11 @@ namespace libtorrent
bool send_chat_message(tcp::endpoint ip, std::string message) const; bool send_chat_message(tcp::endpoint ip, std::string message) const;
torrent_status status() const; torrent_status status() const;
void get_download_queue(std::vector<partial_piece_info>& queue) const; void get_download_queue(std::vector<partial_piece_info>& queue) const;
// fills the specified vector with the download progress [0, 1]
// of each file in the torrent. The files are ordered as in
// the torrent_info.
void file_progress(std::vector<float>& progress);
std::vector<announce_entry> const& trackers() const; std::vector<announce_entry> const& trackers() const;
void replace_trackers(std::vector<announce_entry> const&) const; void replace_trackers(std::vector<announce_entry> const&) const;
@ -291,9 +296,6 @@ namespace libtorrent
// the ratio is uploaded / downloaded. less than 1 is not allowed // the ratio is uploaded / downloaded. less than 1 is not allowed
void set_ratio(float up_down_ratio) const; void set_ratio(float up_down_ratio) const;
// TODO: add finish_file_allocation, which will force the
// torrent to allocate storage for all pieces.
boost::filesystem::path save_path() const; boost::filesystem::path save_path() const;
// -1 means unlimited unchokes // -1 means unlimited unchokes