jiigen666/libtorrent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

change the add_torrent_params API to use flags instead of a bunch of bools (but leave it backwards compatible)

Browse Source
This commit is contained in:
Arvid Norberg
2011-11-08 05:36:22 +00:00
parent 5627fa2e2e
commit 2330520c51
8 changed files with 215 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files

165
docs/manual.rst
View File

@@ -382,6 +382,19 @@ add_torrent()
{
add_torrent_params(storage_constructor_type s);
enum flags_t
{
flag_seed_mode = 0x001,
flag_override_resume_data = 0x002,
flag_upload_mode = 0x004,
flag_share_mode = 0x008,
flag_apply_ip_filter = 0x010,
flag_paused = 0x020,
flag_auto_managed = 0x040.
flag_duplicate_is_error = 0x080,
flag_merge_resume_trackers = 0x100
};
int version;
boost::intrusive_ptr<torrent_info> ti;
char const* tracker_url;
@@ -390,22 +403,14 @@ add_torrent()
fs::path save_path;
std::vector<char>* resume_data;
storage_mode_t storage_mode;
bool paused;
bool auto_managed;
bool duplicate_is_error;
storage_constructor_type storage;
void* userdata;
bool seed_mode;
bool override_resume_data;
bool upload_mode;
std::vector<boost::uint8_t> const* file_priorities;
bool share_mode;
std::string trackerid;
std::string url;
std::string uuid;
std::string source_feed_url;
bool apply_ip_filter;
bool merge_resume_trackers;
boost::uint64_t flags;
};
torrent_handle add_torrent(add_torrent_params const& params);
@@ -469,24 +474,6 @@ storage_mode_compact
For more information, see `storage allocation`_.
``paused`` is a boolean that 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.
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 ``override_resume_data``.
If ``auto_managed`` is true, this 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``.
``storage`` 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
@@ -496,49 +483,9 @@ that needs to be implemented for a custom storage, see `storage_interface`_.
The ``userdata`` parameter is optional and will be passed on to the extension
constructor functions, if any (see `add_extension()`_).
If ``seed_mode`` is set to true, 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 ``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.
The torrent_handle_ returned by ``add_torrent()`` can be used to retrieve information
about the torrent's progress, its peers etc. It is also used to abort a torrent.
If ``override_resume_data`` is set to true, the ``paused`` and ``auto_managed``
state of the torrent are not loaded from the resume data, but the states requested
by this ``add_torrent_params`` will override it.
If ``upload_mode`` is set to true, 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.
``share_mode`` 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
merlely 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.
``file_priorities`` can be set to control the initial file priorities when adding
a torrent. The semantics are the same as for ``torrent_handle::prioritize_files()``.
@@ -556,13 +503,89 @@ is mainly useful for RSS feed items which has UUIDs specified.
``source_feed_url`` should point to the URL of the RSS feed this torrent comes from,
if it comes from an RSS feed.
``apply_ip_filter`` determines if the IP filter should apply to this torrent or not. By
default all torrents are subject to filtering by the IP filter. This is useful if certain
torrents needs to be excempt for some reason, being an auto-update torrent for instance.
``flags`` is a 64 bit integer used for flags controlling aspects of this torrent
and how it's added. These are the flags::
``merge_resume_trackers`` defaults to false and specifies whether tracker URLs loaded from
enum flags_t
{
flag_seed_mode = 0x001,
flag_override_resume_data = 0x002,
flag_upload_mode = 0x004,
flag_share_mode = 0x008,
flag_apply_ip_filter = 0x010,
flag_paused = 0x020,
flag_auto_managed = 0x040.
flag_duplicate_is_error = 0x080,
flag_merge_resume_trackers = 0x100
}
``flag_apply_ip_filter`` 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_merge_resume_trackers`` 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_paused`` 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.
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``.
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``.
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.
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 ``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.
``flag_share_mode`` 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
merlely 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.
remove_torrent()
----------------