91 lines
4.2 KiB
ReStructuredText
91 lines
4.2 KiB
ReStructuredText
|
===========================
|
||
|
|
Upgrading to libtorrent 1.2
|
||
|
|
===========================
|
||
|
|
|
||
|
|
:Author: Arvid Norberg, arvid@libtorrent.org
|
||
|
|
:Version: 1.2.0
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
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``.`
|
||
|
|
|
||
|
|
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 callback has to register which callbacks it's interested in receiving by returning a bitmask from ``std::uint32_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.
|
||
|
|
|
||
|
|
|