Upgrading to libtorrent 1.2

Author: Arvid Norberg, arvid@libtorrent.org

libtorrent version 1.2 comes with some significant updates in the API. This document summarizes the changes affecting library users.

C++98 no longer supported

With libtorrent 1.2, C++98 is no longer supported, you need a compiler capable of at least C++11 to build libtorrent.

This also means libtorrent types now support move.

forward declaring libtorrent types deprecated

Clients are discouraged from forward declaring types from libtorrent. Instead, include the <libtorrent/fwd.hpp> header.

A future release will intrduce ABI versioning using an inline namespace, which will break any forward declarations by clients.

There is a new namespace alias, lt which is shorthand for libtorrent. In the future, libtorrent will be the alias and lt the namespace name. With no forward declarations inside libtorrent's namespace though, there should not be any reason for clients to re-open the namespace.

resume data handling

To significantly simplify handling of resume data, the previous way of handling it is deprecated. resume data is no longer passed in as a flat buffer in the add_torrent_params. The add_torrent_params structure itself is the resume data now.

In order to parse the bencoded fast resume file (which is still the same format, and backwards compatible) use the read_resume_data() function.

Similarly, when saving resume data, the save_resume_data_alert now has a params field of type add_torrent_params which contains the resume data. This object can be serialized into the bencoded form using write_resume_data().

This give the client full control over which properties should be loaded from the resume data and which should be controlled by the client directly. The flags flag_override_resume_data, flag_merge_resume_trackers, flag_use_resume_save_path and flag_merge_resume_http_seeds have all been deprecated, since they are no longer needed.

The old API is still supported as long as libtorrent is built with deprecated functions enabled (which is the default). It will be performing slightly better without deprecated functions present.

rate_limit_utp changed defaults

The setting rate_limit_utp was deprecated in libtorrent 1.1. When building without deprecated features (deprecated-functions=off) the default behavior also changed to have rate limits apply to utp sockets too. In order to be more consistent between the two build configurations, the default value has changed to true. The new mechanism provided to apply special rate limiting rules is peer classes. In order to implement the old behavior of not rate limiting uTP peers, one can set up a peer class for all uTP peers, to make the normal peer classes not apply to them (which is where the rate limits are set).

announce entry multi-home support

The announce_entry type now captures status on individual endpoints, as opposed to treating every tracker behind the same name as a single tracker. This means some properties has moved into the announce_endpoint structure, and an announce entry has 0 or more endpoints.

alerts no longer cloneable

As part of the transition to a more efficient handling of alerts, 1.1 allocated them in a contiguous, heterogeneous, vector. This means they are no longer heap allocated nor held by a smart pointer. The clone() member on alerts was deprecated in 1.1 and removed in 1.2. To pass alerts across threads, instead pull out the relevant information from the alerts and pass that across.

progress alert category

The alert::progress_notification category has been deprecated. Alerts posted in this category are now also posted in one of these new categories:

  • alert::block_progress_notification
  • alert::piece_progress_notification
  • alert::file_progress_notification
  • alert::upload_notification

boost replaced by std

boost::shared_ptr has been replaced by std::shared_ptr in the libtorrent API. The same goes for <cstdint> types, instead of boost::int64_t, libtorrent now uses std::int64_t. Instead of boost::array, std::array is used, and boost::function has been replaced by std::fuction.

strong typedefs

In order to strengthen type-safety, libtorrent now uses special types to represent certain indexes and ID types. Any integer referring to a piece index, now has the type piece_index_t, and indices to files in a torrent, use file_index_t. Similarly, time points and duration now use time_point and duration from the <chrono> standard library.

The specific types have typedefs at lt::time_point and lt::duration, and the clock used by libtorrent is lt::clock_type.`

strongly typed flags

Enum flags have been replaced by strongly typed flags. This means their implicit conversion to and from int is deprecated. For example, the following expressions are deprecated:

if ((atp.flags & add_torrent_params::flag_paused) == 0)

atp.flags = 0;

Insted say:

if (!(atp.flags & torrent_flags::paused))

atp.flags = {};

(Also note that in this specific example, the flags moved out of the add_torrent_params structure, but this is unrelated to them also having stronger types).

span<> and string_view

The interface has adopted string_view (from boost for now) and span<> (custom implementation for now). This means some function calls that previously took char const* or std::string may now take an lt::string_view. Similarly, functions that previously would take a pointer and length pair will now take a span<>.

periphery utility functions no longer exported

Historically, libtorrent has exported functions not essential to its core bittorrent functionality. Such as filesystem functions like directory, file classes and remove, create_directory functions. Path manipulation functions like combine_path, extension, split_path etc. String manipulation functions like from_hex and to_hex. Time functions like time_now. These functions are no longer available to clients, and some have been removed from the library. Instead, it is recommended to use boost.filesystem or the experimental filesystem TS.

plugins

libtorrent session plugins no longer have all callbacks called unconditionally. The plugin has to register which callbacks it's interested in receiving by returning a bitmask from feature_flags_t implemented_features(). The return value is documented in the plugin class.

RSS functions removed

The deprecated RSS functions have been removed from the library interface.