2016-02-20 23:28:41 +01:00
|
|
|
=================
|
|
|
|
libtorrent manual
|
|
|
|
=================
|
|
|
|
|
|
|
|
:Author: Arvid Norberg, arvid@libtorrent.org
|
|
|
|
:Version: 1.1.0
|
|
|
|
|
|
|
|
.. contents:: Table of contents
|
|
|
|
:depth: 2
|
|
|
|
:backlinks: none
|
|
|
|
|
|
|
|
tutorial
|
|
|
|
========
|
|
|
|
|
|
|
|
The fundamental feature of starting and downloading torrents in libtorrent is
|
|
|
|
achieved by creating a *session*, which provides the context and a container for
|
|
|
|
torrents. This is done with via the session_ class, most of its interface is
|
|
|
|
documented under session_handle_ though.
|
|
|
|
|
|
|
|
To add a torrent to the session, you fill in an add_torrent_params_ object and
|
|
|
|
pass it either to `add_torrent()`_ or `async_add_torrent()`_.
|
|
|
|
|
|
|
|
``add_torrent()`` is a blocking call which returns a torrent_handle_.
|
|
|
|
|
|
|
|
For example:
|
|
|
|
|
|
|
|
.. code:: c++
|
|
|
|
|
|
|
|
#include <libtorrent/session.hpp>
|
|
|
|
#include <libtorrent/add_torrent_params.hpp>
|
|
|
|
#include <libtorrent/torrent_handle.hpp>
|
|
|
|
|
|
|
|
namespace lt = libtorrent;
|
|
|
|
int main(int argc, char const* argv[])
|
|
|
|
{
|
|
|
|
if (argc != 2) {
|
|
|
|
fprintf(stderr, "usage: %s <magnet-url>\n");
|
|
|
|
return 1;
|
|
|
|
}
|
|
|
|
lt::session ses;
|
|
|
|
|
|
|
|
lt::add_torrent_params atp;
|
|
|
|
atp.url = argv[1];
|
|
|
|
atp.save_path = "."; // save in current dir
|
|
|
|
lt::torrent_handle h = ses.add_torrent(atp);
|
|
|
|
|
|
|
|
// ...
|
|
|
|
}
|
|
|
|
|
|
|
|
Once you have a torrent_handle_, you can affect it as well as querying status.
|
|
|
|
First, let's extend the example to print out messages from the bittorrent engine
|
|
|
|
about progress and events happening under the hood. libtorrent has a mechanism
|
|
|
|
referred to as *alerts* to communicate back information to the client application.
|
|
|
|
|
|
|
|
Clients can poll libtorrents for new alerts via the `pop_alerts()`_ call on the
|
|
|
|
session object. This call fills in a vector of alert pointers with all new
|
|
|
|
alerts since the last call to this function. The pointers are owned by the
|
|
|
|
session object at will become invalidated by the next call to `pop_alerts()`_.
|
|
|
|
|
|
|
|
The alerts form a class hierarchy with alert_ as the root class. Each specific
|
|
|
|
kind of alert may include additional state, specific to the kind of message. All
|
|
|
|
alerts implement a message() function that prints out pertinent information
|
|
|
|
of the alert message. This can be convenient for simply logging events.
|
|
|
|
|
|
|
|
For programatically react to certain events, use `alert_cast<>`_ to attempt
|
|
|
|
a down cast of an alert object to a more specific type.
|
|
|
|
|
|
|
|
In order to print out events from libtorrent as well as exiting when the torrent
|
|
|
|
completes downloading, we can poll the session for alerts periodically and print
|
|
|
|
them out, as well as listening for the torrent_finished_alert_, which is posted
|
|
|
|
when a torrent completes.
|
|
|
|
|
|
|
|
.. code:: c++
|
|
|
|
|
|
|
|
#include <iostream>
|
|
|
|
|
|
|
|
#include <libtorrent/session.hpp>
|
|
|
|
#include <libtorrent/add_torrent_params.hpp>
|
|
|
|
#include <libtorrent/torrent_handle.hpp>
|
|
|
|
#include <libtorrent/alert_types.hpp>
|
|
|
|
|
|
|
|
namespace lt = libtorrent;
|
|
|
|
int main(int argc, char const* argv[])
|
|
|
|
{
|
|
|
|
if (argc != 2) {
|
|
|
|
std::cerr << "usage: " << argv[0] << " <magnet-url>" << std::endl;
|
|
|
|
return 1;
|
|
|
|
}
|
|
|
|
lt::session ses;
|
|
|
|
|
|
|
|
lt::add_torrent_params atp;
|
|
|
|
atp.url = argv[1];
|
|
|
|
atp.save_path = "."; // save in current dir
|
|
|
|
lt::torrent_handle h = ses.add_torrent(atp);
|
|
|
|
|
|
|
|
bool done = false;
|
|
|
|
while (!done) {
|
|
|
|
std::vector<lt::alert*> alerts;
|
|
|
|
ses.pop_alerts(&alerts);
|
|
|
|
|
|
|
|
for (lt::alert const* a : alerts) {
|
|
|
|
std::cout << a->message() << std::endl;
|
|
|
|
if (lt::alert_cast<lt::torrent_finished_alert>(a)) {
|
|
|
|
done = true;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
*TODO* cover async_add_torrent()
|
|
|
|
*TODO* cover post_torrent_updates()
|
|
|
|
*TODO* cover save_resume_data()
|
|
|
|
|
|
|
|
.. _session: reference-Core.html#session
|
|
|
|
.. _session_handle: reference-Core.html#session_handle
|
|
|
|
.. _add_torrent_params: reference-Core.html#add_torrent_params
|
|
|
|
.. _`add_torrent()`: reference-Core.html#add_torrent()
|
|
|
|
.. _`async_add_torrent()`: reference-Core.html#add_torrent()
|
|
|
|
.. _torrent_handle: reference-Core.html#torrent_handle
|
|
|
|
.. _`pop_alerts()`: reference-Core.html#pop_alerts()
|
2016-02-21 01:31:17 +01:00
|
|
|
.. _`alert`: reference-Alerts.html#alert
|
2016-02-20 23:28:41 +01:00
|
|
|
.. _`alert_cast<>`: reference-Alerts.html#alert_cast()
|
|
|
|
.. _torrent_finished_alert: reference-Alerts.html#torrent-finished-alert
|
|
|
|
|
|
|
|
|