deprecate add_torrent_params::url field. use parse_magnet_uri instead (#1864)

deprecate add_torrent_params::url field. use parse_magnet_uri instead

ChangeLog

@@ -1,3 +1,4 @@
+	* deprecate add_torrent_params::url field. use parse_magnet_uri instead
 	* optimize download queue management
 	* deprecated (undocumented) file:// urls
 	* add limit for number of web seed connections

bindings/python/src/magnet_uri.cpp

@@ -62,8 +62,8 @@ namespace {
 		ret["name"] = p.name;
 		ret["save_path"] = p.save_path;
 		ret["storage_mode"] = p.storage_mode;
-		ret["url"] = p.url;
 #ifndef TORRENT_NO_DEPRECATE
+		ret["url"] = p.url;
 		ret["uuid"] = p.uuid;
 #endif
 		ret["flags"] = p.flags;

bindings/python/src/session.cpp

@@ -324,11 +324,13 @@ namespace
                 p.trackerid = extract<std::string>(value);
                 continue;
             }
+#ifndef TORRENT_NO_DEPRECATE
             else if(key == "url")
             {
                 p.url = extract<std::string>(value);
                 continue;
             }
+#endif
             else if(key == "renamed_files")
             {
                 p.renamed_files =
@@ -662,7 +664,6 @@ void bind_session()
 //        .def_readwrite("storage", &add_torrent_params::storage)
         .add_property("file_priorities", PROP(&add_torrent_params::file_priorities))
         .def_readwrite("trackerid", &add_torrent_params::trackerid)
-        .def_readwrite("url", &add_torrent_params::url)
         .def_readwrite("flags", &add_torrent_params::flags)
         .def_readwrite("info_hash", &add_torrent_params::info_hash)
         .def_readwrite("max_uploads", &add_torrent_params::max_uploads)
@@ -692,6 +693,7 @@ void bind_session()
         .add_property("renamed_files", PROP(&add_torrent_params::renamed_files))
 
 #ifndef TORRENT_NO_DEPRECATE
+        .def_readwrite("url", &add_torrent_params::url)
         .def_readwrite("uuid", &add_torrent_params::uuid)
         .def_readwrite("resume_data", &add_torrent_params::resume_data)
 #endif

examples/bt-get.cpp

@@ -38,6 +38,7 @@ POSSIBILITY OF SUCH DAMAGE.
 #include <libtorrent/add_torrent_params.hpp>
 #include <libtorrent/torrent_handle.hpp>
 #include <libtorrent/alert_types.hpp>
+#include <libtorrent/magnet_uri.hpp>
 
 namespace lt = libtorrent;
 int main(int argc, char const* argv[])
@@ -49,7 +50,12 @@ int main(int argc, char const* argv[])
 	lt::session ses;
 
 	lt::add_torrent_params atp;
-	atp.url = argv[1];
+	lt::error_code ec;
+	lt::parse_magnet_uri(argv[1], atp, ec);
+	if (ec) {
+		std::cerr << "invalid magnet URI: " << ec.message() << std::endl;
+		return 1;
+	}
 	atp.save_path = "."; // save in current dir
 	lt::torrent_handle h = ses.add_torrent(std::move(atp));
 

examples/bt-get2.cpp

@@ -44,6 +44,7 @@ POSSIBILITY OF SUCH DAMAGE.
 #include <libtorrent/read_resume_data.hpp>
 #include <libtorrent/write_resume_data.hpp>
 #include <libtorrent/error_code.hpp>
+#include <libtorrent/magnet_uri.hpp>
 
 namespace lt = libtorrent;
 using clk = std::chrono::steady_clock;
@@ -87,7 +88,15 @@ int main(int argc, char const* argv[])
 
 	lt::error_code ec;
 	lt::add_torrent_params atp = lt::read_resume_data(&buf[0], int(buf.size()), ec);
-	atp.url = argv[1];
+	if (ec) {
+		std::cerr << "failed to read resume data: " << ec.message() << std::endl;
+		return 1;
+	}
+	lt::parse_magnet_uri(argv[1], atp, ec);
+	if (ec) {
+		std::cerr << "invalid magnet URI: " << ec.message() << std::endl;
+		return 1;
+	}
 	atp.save_path = "."; // save in current dir
 	ses.async_add_torrent(std::move(atp));
 

include/libtorrent/add_torrent_params.hpp

@@ -57,9 +57,8 @@ namespace libtorrent
 	// session. The key fields when adding a torrent are:
 	//
 	// * ti - when you have loaded a .torrent file into a torrent_info object
-	// * url - when you have a magnet link
+	// * info_hash - when you don't have the metadata (.torrent file) but. This
-	// * info_hash - when all you have is an info-hash (this is similar to a
+	//   is set when adding a magnet link.
-	//   magnet link)
 	//
 	// one of those fields must be set. Another mandatory field is
 	// ``save_path``. The add_torrent_params object is passed into one of the
@@ -280,7 +279,7 @@ namespace libtorrent
 		// for forward binary compatibility.
 		int version = LIBTORRENT_VERSION_NUM;
 
-		// torrent_info object with the torrent to add. Unless the url or
+		// torrent_info object with the torrent to add. Unless the
 		// info_hash is set, this is required to be initialized.
 		std::shared_ptr<torrent_info> ti;
 
@@ -349,19 +348,6 @@ namespace libtorrent
 		// instead of this.
 		std::string trackerid;
 
-		// ``url`` can be set to a magnet link, in order to download the .torrent
-		// file (also known as the metadata), specifically the info-dictionary,
-		// from the bittorrent swarm. This may require access to the DHT, in case
-		// the magnet link does not come with trackers.
-		//
-		// In earlier versions of libtorrent, the URL could be an HTTP or file://
-		// url. These uses are deprecated and discouraged. When adding a torrent
-		// by magnet link, it will be set to the ``downloading_metadata`` state
-		// until the .torrent file has been downloaded. If there is any error
-		// while downloading, the torrent will be stopped and the torrent error
-		// state (``torrent_status::error``) will indicate what went wrong.
-		std::string url;
-
 		// flags controlling aspects of this torrent and how it's added. See
 		// flags_t for details.
 		//
@@ -375,6 +361,8 @@ namespace libtorrent
 		// set this to the info hash of the torrent to add in case the info-hash
 		// is the only known property of the torrent. i.e. you don't have a
 		// .torrent file nor a magnet link.
+		// To add a magnet link, use parse_magnet_uri() to populatefields in the
+		// add_torrent_params object.
 		sha1_hash info_hash;
 
 		// ``max_uploads``, ``max_connections``, ``upload_limit``,
@@ -484,6 +472,20 @@ namespace libtorrent
 
 #ifndef TORRENT_NO_DEPRECATE
 		// deprecated in 1.2
+
+		// ``url`` can be set to a magnet link, in order to download the .torrent
+		// file (also known as the metadata), specifically the info-dictionary,
+		// from the bittorrent swarm. This may require access to the DHT, in case
+		// the magnet link does not come with trackers.
+		//
+		// In earlier versions of libtorrent, the URL could be an HTTP or file://
+		// url. These uses are deprecated and discouraged. When adding a torrent
+		// by magnet link, it will be set to the ``downloading_metadata`` state
+		// until the .torrent file has been downloaded. If there is any error
+		// while downloading, the torrent will be stopped and the torrent error
+		// state (``torrent_status::error``) will indicate what went wrong.
+		std::string TORRENT_DEPRECATED_MEMBER url;
+
 		// if ``uuid`` is specified, it is used to find duplicates. If another
 		// torrent is already running with the same UUID as the one being added,
 		// it will be considered a duplicate. This is mainly useful for RSS feed
@@ -506,6 +508,7 @@ namespace libtorrent
 #else
 		// hidden
 		// to maintain ABI compatibility
+		std::string deprecated5;
 		std::string deprecated1;
 		std::string deprecated2;
 		std::vector<char> deprecated3;

simulation/test_metadata_extension.cpp

@@ -100,7 +100,9 @@ void run_metadata_test(int flags)
 		// add torrent
 		, [](lt::add_torrent_params& params) {
 			// we want to add the torrent via magnet link
-			params.url = lt::make_magnet_uri(*params.ti);
+			error_code ec;
+			parse_magnet_uri(lt::make_magnet_uri(*params.ti), params, ec);
+			TEST_CHECK(!ec);
 			params.ti.reset();
 			params.flags &= ~add_torrent_params::flag_upload_mode;
 		}

src/alert.cpp

@@ -1351,7 +1351,9 @@ namespace libtorrent
 		char const* torrent_name = info_hash;
 		if (params.ti) torrent_name = params.ti->name().c_str();
 		else if (!params.name.empty()) torrent_name = params.name.c_str();
+#ifndef TORRENT_NO_DEPRECATE
 		else if (!params.url.empty()) torrent_name = params.url.c_str();
+#endif
 		else aux::to_hex(params.info_hash, info_hash);
 
 		if (error)

src/read_resume_data.cpp

@@ -141,9 +141,9 @@ namespace libtorrent
 
 		ret.save_path = rd.dict_find_string_value("save_path").to_string();
 
-		ret.url = rd.dict_find_string_value("url").to_string();
 #ifndef TORRENT_NO_DEPRECATE
 		// deprecated in 1.2
+		ret.url = rd.dict_find_string_value("url").to_string();
 		ret.uuid = rd.dict_find_string_value("uuid").to_string();
 #endif
 

src/session_impl.cpp

@@ -4789,6 +4789,7 @@ namespace aux {
 
 		using ptr_t = std::shared_ptr<torrent>;
 
+#ifndef TORRENT_NO_DEPRECATE
 		if (string_begins_no_case("magnet:", params.url.c_str()))
 		{
 			parse_magnet_uri(params.url, params, ec);
@@ -4796,7 +4797,6 @@ namespace aux {
 			params.url.clear();
 		}
 
-#ifndef TORRENT_NO_DEPRECATE
 		if (!params.ti && string_begins_no_case("file://", params.url.c_str()))
 		{
 			std::string const torrent_file_path = resolve_file_url(params.url);
@@ -4808,7 +4808,6 @@ namespace aux {
 		}
 #endif
 
-
 		if (params.ti && !params.ti->is_valid())
 		{
 			ec = errors::no_metadata;

test/test_magnet.cpp

@@ -44,6 +44,7 @@ POSSIBILITY OF SUCH DAMAGE.
 using namespace libtorrent;
 namespace lt = libtorrent;
 
+#ifndef TORRENT_NO_DEPRECATE
 void test_remove_url(std::string url)
 {
 	lt::session s(settings());
@@ -67,7 +68,6 @@ TORRENT_TEST(remove_url)
 	test_remove_url("magnet:?xt=urn:btih:0123456789abcdef0123456789abcdef01234567");
 }
 
-#ifndef TORRENT_NO_DEPRECATE
 TORRENT_TEST(remove_url2)
 {
 	test_remove_url("http://non-existent.com/test.torrent");
@@ -111,18 +111,20 @@ TORRENT_TEST(magnet)
 	s->save_state(session_state);
 
 	// test magnet link parsing
-	add_torrent_params p;
+	add_torrent_params model;
-	p.flags &= ~add_torrent_params::flag_paused;
+	model.flags &= ~add_torrent_params::flag_paused;
-	p.flags &= ~add_torrent_params::flag_auto_managed;
+	model.flags &= ~add_torrent_params::flag_auto_managed;
-	p.save_path = ".";
+	model.save_path = ".";
 	error_code ec;
-	p.url = "magnet:?xt=urn:btih:cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd"
+	add_torrent_params p = model;
+	parse_magnet_uri("magnet:?xt=urn:btih:cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd"
 		"&tr=http://1"
 		"&tr=http://2"
 		"&tr=http://3"
 		"&tr=http://3"
 		"&dn=foo"
-		"&dht=127.0.0.1:43";
+		"&dht=127.0.0.1:43", p, ec);
+	TEST_CHECK(!ec);
 	torrent_handle t = s->add_torrent(p, ec);
 	TEST_CHECK(!ec);
 	if (ec) std::printf("%s\n", ec.message().c_str());
@@ -138,12 +140,14 @@ TORRENT_TEST(magnet)
 	TEST_CHECK(trackers_set.count("http://2") == 1);
 	TEST_CHECK(trackers_set.count("http://3") == 1);
 
-	p.url = "magnet:"
+	p = model;
+	parse_magnet_uri("magnet:"
 		"?tr=http://1"
 		"&tr=http://2"
 		"&dn=foo"
 		"&dht=127.0.0.1:43"
-		"&xt=urn:btih:c352cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd";
+		"&xt=urn:btih:c352cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd", p, ec);
+	TEST_CHECK(!ec);
 	torrent_handle t2 = s->add_torrent(p, ec);
 	TEST_CHECK(!ec);
 	if (ec) std::printf("%s\n", ec.message().c_str());
@@ -153,12 +157,14 @@ TORRENT_TEST(magnet)
 	TEST_EQUAL(trackers[0].tier, 0);
 	TEST_EQUAL(trackers[1].tier, 1);
 
-	p.url = "magnet:"
+	p = model;
+	parse_magnet_uri("magnet:"
 		"?tr=udp%3A%2F%2Ftracker.openbittorrent.com%3A80"
 		"&tr=udp%3A%2F%2Ftracker.publicbt.com%3A80"
 		"&tr=udp%3A%2F%2Ftracker.ccc.de%3A80"
 		"&xt=urn:btih:a38d02c287893842a32825aa866e00828a318f07"
-		"&dn=Ubuntu+11.04+%28Final%29";
+		"&dn=Ubuntu+11.04+%28Final%29", p, ec);
+	TEST_CHECK(!ec);
 	torrent_handle t3 = s->add_torrent(p, ec);
 	TEST_CHECK(!ec);
 	if (ec) std::printf("%s\n", ec.message().c_str());
@@ -415,11 +421,15 @@ TORRENT_TEST(trailing_whitespace)
 	session ses(settings());
 	add_torrent_params p;
 	p.save_path = ".";
-	p.url = "magnet:?xt=urn:btih:abaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\n";
+	error_code ec;
+	parse_magnet_uri("magnet:?xt=urn:btih:abaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\n", p, ec);
 	// invalid hash
+	TEST_CHECK(ec);
 	TEST_THROW(ses.add_torrent(p));
 
-	p.url = "magnet:?xt=urn:btih:abaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+	ec.clear();
+	parse_magnet_uri("magnet:?xt=urn:btih:abaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", p, ec);
+	TEST_CHECK(!ec);
 	// now it's valid, because there's no trailing whitespace
 	torrent_handle h = ses.add_torrent(p);
 	TEST_CHECK(h.is_valid());

test/test_torrent.cpp

@@ -40,6 +40,7 @@ POSSIBILITY OF SUCH DAMAGE.
 #include "libtorrent/peer_info.hpp"
 #include "libtorrent/extensions.hpp"
 #include "libtorrent/file.hpp" // for combine_path, current_working_directory
+#include "libtorrent/magnet_uri.hpp"
 #include "settings.hpp"
 #include <tuple>
 #include <iostream>
@@ -238,7 +239,9 @@ TORRENT_TEST(added_peers)
 	add_torrent_params p;
 	p.ti = info;
 	p.save_path = ".";
-	p.url = "magnet:?xt=urn:btih:abababababababababababababababababababab&x.pe=127.0.0.1:48081&x.pe=127.0.0.2:48082";
+	parse_magnet_uri("magnet:?xt=urn:btih:abababababababababababababababababababab&x.pe=127.0.0.1:48081&x.pe=127.0.0.2:48082"
+		, p, ec);
+	TEST_CHECK(!ec);
 
 	torrent_handle h = ses.add_torrent(std::move(p));