premiere-libtorrent/include/libtorrent/add_torrent_params.hpp

/*

Copyright (c) 2009-2012, Arvid Norberg
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in
      the documentation and/or other materials provided with the distribution.
    * Neither the name of the author nor the names of its
      contributors may be used to endorse or promote products derived
      from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

*/

#ifndef TORRENT_ADD_TORRENT_PARAMS_HPP_INCLUDED
#define TORRENT_ADD_TORRENT_PARAMS_HPP_INCLUDED

#include <string>
#include <vector>
#include <boost/intrusive_ptr.hpp>

#include "libtorrent/storage_defs.hpp"
#include "libtorrent/peer_id.hpp" // sha1_hash
#include "libtorrent/version.hpp"

#ifndef TORRENT_DISABLE_EXTENSIONS
#include "libtorrent/extensions.hpp"
#endif

namespace libtorrent
{
	class torrent_info;

	// The add_torrent_params is a parameter pack for adding torrents to a session.
	// The key fields when adding a torrent are:
	//
	// * ti - when you have a .torrent file
	// * url - when you have a magnet link or http URL to the .torrent file
	// * info_hash - when all you have is an info-hash (this is similar to a magnet link)
	//
	// one of those fields need to be set. Another mandatory field is ``save_path``.
	// The add_torrent_params object is passed into one of the ``session::add_torrent()``
	// overloads or ``session::async_add_torrent()``.
	//
	// If you only specify the info-hash, the torrent file will be downloaded from peers,
	// which requires them to support the metadata extension. For the metadata extension
	// to work, libtorrent must be built with extensions enabled (``TORRENT_DISABLE_EXTENSIONS`` must not be
	// defined). It also takes an optional ``name`` argument. This may be left empty in case no
	// name should be assigned to the torrent. In case it's not, the name is used for
	// the torrent as long as it doesn't have metadata. See ``torrent_handle::name``.
	//
	struct TORRENT_EXPORT add_torrent_params
	{
		// The constructor can be used to initialize the storage constructor, which determines
		// the storage mechanism for the downloaded or seeding data for the torrent. For more
		// information, see the ``storage`` field.
		add_torrent_params(storage_constructor_type sc = default_storage_constructor)
			: version(LIBTORRENT_VERSION_NUM)
#ifndef TORRENT_NO_DEPRECATE
			, tracker_url(0)
#endif
			, storage_mode(storage_mode_sparse)
			, storage(sc)
			, userdata(0)
#ifndef TORRENT_NO_DEPRECATE
			, flags(flag_ignore_flags | default_flags)
			, seed_mode(false)
			, override_resume_data(false)
			, upload_mode(false)
			, share_mode(false)
			, apply_ip_filter(true)
			, paused(true)
			, auto_managed(true)
			, duplicate_is_error(false)
			, merge_resume_trackers(false)
#else
			, flags(default_flags)
#endif
			, max_uploads(-1)
			, max_connections(-1)
			, upload_limit(-1)
			, download_limit(-1)
		{
		}

#ifndef TORRENT_NO_DEPRECATE
		void update_flags() const
		{
			if (flags != (flag_ignore_flags | default_flags)) return;

			boost::uint64_t& f = const_cast<boost::uint64_t&>(flags);
			f = flag_update_subscribe;
			if (seed_mode) f |= flag_seed_mode;
			if (override_resume_data) f |= flag_override_resume_data;
			if (upload_mode) f |= flag_upload_mode;
			if (share_mode) f |= flag_share_mode;
			if (apply_ip_filter) f |= flag_apply_ip_filter;
			if (paused) f |= flag_paused;
			if (auto_managed) f |= flag_auto_managed;
			if (duplicate_is_error) f |= flag_duplicate_is_error;
			if (merge_resume_trackers) f |= flag_merge_resume_trackers;
		}
#endif

		// values for the ``flags`` field
		enum flags_t
		{
			// If ``flag_seed_mode`` is set, libtorrent will assume that all files are present
			// for this torrent and that they all match the hashes in the torrent file. Each time
			// a peer requests to download a block, the piece is verified against the hash, unless
			// it has been verified already. If a hash fails, the torrent will automatically leave
			// the seed mode and recheck all the files. The use case for this mode is if a torrent
			// is created and seeded, or if the user already know that the files are complete, this
			// is a way to avoid the initial file checks, and significantly reduce the startup time.
			// 
			// Setting ``flag_seed_mode`` on a torrent without metadata (a .torrent file) is a no-op
			// and will be ignored.
			// 
			// If resume data is passed in with this torrent, the seed mode saved in there will
			// override the seed mode you set here.
			flag_seed_mode = 0x001,

			// If ``flag_override_resume_data`` is set, the ``paused`` and ``auto_managed``
			// state of the torrent are not loaded from the resume data, but the states requested
			// by the flags in ``add_torrent_params`` will override them.
			//
			// If you pass in resume data, the paused state of the torrent when the resume data
			// was saved will override the paused state you pass in here. You can override this
			// by setting ``flag_override_resume_data``.
			flag_override_resume_data = 0x002,

			// If ``flag_upload_mode`` is set, the torrent will be initialized in upload-mode,
			// which means it will not make any piece requests. This state is typically entered
			// on disk I/O errors, and if the torrent is also auto managed, it will be taken out
			// of this state periodically. This mode can be used to avoid race conditions when
			// adjusting priorities of pieces before allowing the torrent to start downloading.
			// 
			// If the torrent is auto-managed (``flag_auto_managed``), the torrent will eventually
			// be taken out of upload-mode, regardless of how it got there. If it's important to
			// manually control when the torrent leaves upload mode, don't make it auto managed.
			flag_upload_mode = 0x004,

			// determines if the torrent should be added in *share mode* or not.
			// Share mode indicates that we are not interested in downloading the torrent, but
			// merley want to improve our share ratio (i.e. increase it). A torrent started in
			// share mode will do its best to never download more than it uploads to the swarm.
			// If the swarm does not have enough demand for upload capacity, the torrent will
			// not download anything. This mode is intended to be safe to add any number of torrents
			// to, without manual screening, without the risk of downloading more than is uploaded.
			// 
			// A torrent in share mode sets the priority to all pieces to 0, except for the pieces
			// that are downloaded, when pieces are decided to be downloaded. This affects the progress
			// bar, which might be set to "100% finished" most of the time. Do not change file or piece
			// priorities for torrents in share mode, it will make it not work.
			// 
			// The share mode has one setting, the share ratio target, see ``session_settings::share_mode_target``
			// for more info.
			flag_share_mode = 0x008,

			// determines if the IP filter should apply to this torrent or not. By
			// default all torrents are subject to filtering by the IP filter (i.e. this flag is set by
			// default). This is useful if certain torrents needs to be excempt for some reason, being
			// an auto-update torrent for instance.
			flag_apply_ip_filter = 0x010,

			// specifies whether or not the torrent is to be started in a paused
			// state. I.e. it won't connect to the tracker or any of the peers until it's
			// resumed. This is typically a good way of avoiding race conditions when setting
			// configuration options on torrents before starting them.
			flag_paused = 0x020,

			// If the torrent is auto-managed (``flag_auto_managed``), the torrent may be resumed
			// at any point, regardless of how it paused. If it's important to manually control
			// when the torrent is paused and resumed, don't make it auto managed.
			// 
			// If ``flag_auto_managed`` is set, the torrent will be queued, started and seeded
			// automatically by libtorrent. When this is set, the torrent should also be started
			// as paused. The default queue order is the order the torrents were added. They
			// are all downloaded in that order. For more details, see queuing_.
			// 
			// If you pass in resume data, the auto_managed state of the torrent when the resume data
			// was saved will override the auto_managed state you pass in here. You can override this
			// by setting ``override_resume_data``.
			flag_auto_managed = 0x040,
			flag_duplicate_is_error = 0x080,

			// defaults to off and specifies whether tracker URLs loaded from
			// resume data should be added to the trackers in the torrent or replace the trackers.
			flag_merge_resume_trackers = 0x100,

			// on by default and means that this torrent will be part of state
			// updates when calling `post_torrent_updates()`_.
			flag_update_subscribe = 0x200,

			// sets the torrent into super seeding mode. If the torrent
			// is not a seed, this flag has no effect. It has the same effect as calling
			// ``torrent_handle::super_seeding(true)`` on the torrent handle immediately
			// after adding it.
			flag_super_seeding = 0x400,

			// sets the sequential download state for the torrent.
			// It has the same effect as calling ``torrent_handle::sequential_download(true)``
			// on the torrent handle immediately after adding it.
			flag_sequential_download = 0x800,

			// internal
			default_flags = flag_update_subscribe | flag_auto_managed | flag_paused | flag_apply_ip_filter
#ifndef TORRENT_NO_DEPRECATE
			, flag_ignore_flags = 0x80000000
#endif
		};
	
		// filled in by the constructor and should be left untouched. It
		// is used for forward binary compatibility.
		int version;

		// torrent_info object with the torrent to add. Unless the url or info_hash
		// is set, this is required to be initiazlied.
		boost::intrusive_ptr<torrent_info> ti;

#ifndef TORRENT_NO_DEPRECATE
		char const* tracker_url;
#endif
		// If the torrent doesn't have a tracker, but relies on the DHT to find peers, the
		// ``trackers`` can specify tracker URLs for the torrent.
		std::vector<std::string> trackers;

		// a list of hostname and port pairs, representing DHT nodes to be
		// added to the session (if DHT is enabled). The hostname may be an IP address.
		std::vector<std::pair<std::string, int> > dht_nodes;
		sha1_hash info_hash;
		std::string name;
		std::string save_path;

		// The optional parameter, ``resume_data`` can be given if up to date fast-resume data
		// is available. The fast-resume data can be acquired from a running torrent by calling
		// save_resume_data() on `torrent_handle`_. See fast-resume_. The ``vector`` that is
		// passed in will be swapped into the running torrent instance with ``std::vector::swap()``.
		std::vector<char> resume_data;

		// One of the values from storage_mode_t. For more information, see storage-allocation_.
		storage_mode_t storage_mode;

		// can be used to customize how the data is stored. The default
		// storage will simply write the data to the files it belongs to, but it could be
		// overridden to save everything to a single file at a specific location or encrypt the
		// content on disk for instance. For more information about the storage_interface
		// that needs to be implemented for a custom storage, see storage_interface.
		storage_constructor_type storage;

		// The ``userdata`` parameter is optional and will be passed on to the extension
		// constructor functions, if any (see `add_extension()`_).
		void* userdata;

		// can be set to control the initial file priorities when adding
		// a torrent. The semantics are the same as for ``torrent_handle::prioritize_files()``.
		std::vector<boost::uint8_t> file_priorities;

		// the default tracker id to be used when announcing to trackers. By default
		// this is empty, and no tracker ID is used, since this is an optional argument. If
		// a tracker returns a tracker ID, that ID is used instead of this.
		std::string trackerid;

		// If you specify a ``url``, the torrent will be set in ``downloading_metadata`` state
		// until the .torrent file has been downloaded. If there's any error while downloading,
		// the torrent will be stopped and the torrent error state (``torrent_status::error``)
		// will indicate what went wrong. The ``url`` may refer to a magnet link or a regular
		// http URL.
		// 
		// If it refers to an HTTP URL, the info-hash for the added torrent will not be the
		// true info-hash of the .torrent. Instead a placeholder, unique, info-hash is used
		// which is later updated once the .torrent file has been downloaded.
		// 
		// Once the info-hash change happens, a torrent_update_alert is posted.
		std::string 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 items which has UUIDs specified.
		std::string uuid;

		// should point to the URL of the RSS feed this torrent comes from,
		// if it comes from an RSS feed.
		std::string source_feed_url;

		// flags controlling aspects of this torrent and how it's added. See flags_t for details.
		boost::uint64_t flags;

#ifndef TORRENT_NO_DEPRECATE
		bool seed_mode;
		bool override_resume_data;
		bool upload_mode;
		bool share_mode;
		bool apply_ip_filter;
		bool paused;
		bool auto_managed;
		bool duplicate_is_error;
		bool merge_resume_trackers;
#endif

		// ``max_uploads``, ``max_connections``, ``upload_limit``, ``download_limit`` correspond
		// to the ``set_max_uploads()``, ``set_max_connections()``, ``set_upload_limit()`` and
		// ``set_download_limit()`` functions on torrent_handle_. These values let you initialize
		// these settings when the torrent is added, instead of calling these functions immediately
		// following adding it.
		// 
		// -1 means unlimited on these settings
		// just like their counterpart functions
		// on torrent_handle
		int max_uploads;
		int max_connections;
		int upload_limit;
		int download_limit;

#ifndef TORRENT_DISABLE_EXTENSIONS
		// torrent extension construction functions can be added to this
		// vector to have them be added immediately when the torrent is
		// constructed. This may be desired over the torrent_handle::add_extension()
		// in order to avoid race conditions. For instance it may be important
		// to have the plugin catch events that happen very early on after
		// the torrent is created.
		std::vector<boost::function<boost::shared_ptr<torrent_plugin>(torrent*, void*)> > extensions;
#endif
	};
}

#endif