add start of a tutorial

This commit is contained in:
arvidn 2016-02-20 17:28:41 -05:00
parent 5e4d6d139f
commit 3ff4c0e348
6 changed files with 135 additions and 5 deletions

View File

@ -93,6 +93,8 @@ DOCS_PAGES = \
docs/udp_tracker_protocol.rst \
docs/utp.rst \
docs/streaming.rst \
docs/tutorial.rst \
docs/tutorial.html \
docs/reference-Alerts.html \
docs/reference-Bdecoding.html \
docs/reference-Bencoding.html \

View File

@ -7,6 +7,7 @@
* download_
* features_
* tutorial_
* examples_
* overview_
* `reference documentation`_
@ -58,6 +59,7 @@ libtorrent
.. _download: https://github.com/arvidn/libtorrent/releases
.. _features: features.html
.. _tutorial: tutorial.html
.. _contributing: contributing.html
.. _building: building.html
.. _examples: examples.html

View File

@ -44,6 +44,7 @@ TARGETS = index \
tuning \
hacking \
streaming \
tutorial \
$(REFERENCE_TARGETS)
FIGURES = \

View File

@ -37,7 +37,10 @@ The basic usage is as follows:
* save session state (see save_state())
* destruct session object
Each class and function is described in this manual.
Each class and function is described in this manual, you may want to have a
look at the tutorial_ as well.
.. _tutorial: tutorial.html
For a description on how to create torrent files, see create_torrent.

124
docs/tutorial.rst Normal file
View File

@ -0,0 +1,124 @@
=================
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()
.. _`alert_cast<>`: reference-Alerts.html#alert_cast()
.. _torrent_finished_alert: reference-Alerts.html#torrent-finished-alert

View File

@ -310,15 +310,13 @@ namespace libtorrent {
// When you get an alert, you can use ``alert_cast<>`` to attempt to cast the pointer to a
// more specific alert type, in order to query it for more information.
template <class T>
T* alert_cast(alert* a)
template <class T> T* alert_cast(alert* a)
{
if (a == 0) return 0;
if (a->type() == T::alert_type) return static_cast<T*>(a);
return 0;
}
template <class T>
T const* alert_cast(alert const* a)
template <class T> T const* alert_cast(alert const* a)
{
if (a == 0) return 0;
if (a->type() == T::alert_type) return static_cast<T const*>(a);