1 /* 2 3 Copyright (c) 2017, Arvid Norberg 4 All rights reserved. 5 6 Redistribution and use in source and binary forms, with or without 7 modification, are permitted provided that the following conditions 8 are met: 9 10 * Redistributions of source code must retain the above copyright 11 notice, this list of conditions and the following disclaimer. 12 * Redistributions in binary form must reproduce the above copyright 13 notice, this list of conditions and the following disclaimer in 14 the documentation and/or other materials provided with the distribution. 15 * Neither the name of the author nor the names of its 16 contributors may be used to endorse or promote products derived 17 from this software without specific prior written permission. 18 19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 20 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 23 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29 POSSIBILITY OF SUCH DAMAGE. 30 31 */ 32 33 #ifndef TORRENT_TORRENT_FLAGS_HPP 34 #define TORRENT_TORRENT_FLAGS_HPP 35 36 #include <cstdint> 37 38 #include "libtorrent/config.hpp" 39 #include "libtorrent/flags.hpp" 40 41 namespace libtorrent { 42 43 using torrent_flags_t = flags::bitfield_flag<std::uint64_t, struct torrent_flags_tag>; 44 45 namespace torrent_flags { 46 47 #if TORRENT_ABI_VERSION == 1 48 #include "libtorrent/aux_/disable_warnings_push.hpp" 49 #endif 50 51 // If ``seed_mode`` is set, libtorrent will assume that all files 52 // are present for this torrent and that they all match the hashes in 53 // the torrent file. Each time a peer requests to download a block, 54 // the piece is verified against the hash, unless it has been verified 55 // already. If a hash fails, the torrent will automatically leave the 56 // seed mode and recheck all the files. The use case for this mode is 57 // if a torrent is created and seeded, or if the user already know 58 // that the files are complete, this is a way to avoid the initial 59 // file checks, and significantly reduce the startup time. 60 // 61 // Setting ``seed_mode`` on a torrent without metadata (a 62 // .torrent file) is a no-op and will be ignored. 63 // 64 // It is not possible to *set* the ``seed_mode`` flag on a torrent after it has 65 // been added to a session. It is possible to *clear* it though. 66 constexpr torrent_flags_t seed_mode = 0_bit; 67 68 // If ``upload_mode`` is set, the torrent will be initialized in 69 // upload-mode, which means it will not make any piece requests. This 70 // state is typically entered on disk I/O errors, and if the torrent 71 // is also auto managed, it will be taken out of this state 72 // periodically (see ``settings_pack::optimistic_disk_retry``). 73 // 74 // This mode can be used to avoid race conditions when 75 // adjusting priorities of pieces before allowing the torrent to start 76 // downloading. 77 // 78 // If the torrent is auto-managed (``auto_managed``), the torrent 79 // will eventually be taken out of upload-mode, regardless of how it 80 // got there. If it's important to manually control when the torrent 81 // leaves upload mode, don't make it auto managed. 82 constexpr torrent_flags_t upload_mode = 1_bit; 83 84 // determines if the torrent should be added in *share mode* or not. 85 // Share mode indicates that we are not interested in downloading the 86 // torrent, but merely want to improve our share ratio (i.e. increase 87 // it). A torrent started in share mode will do its best to never 88 // download more than it uploads to the swarm. If the swarm does not 89 // have enough demand for upload capacity, the torrent will not 90 // download anything. This mode is intended to be safe to add any 91 // number of torrents to, without manual screening, without the risk 92 // of downloading more than is uploaded. 93 // 94 // A torrent in share mode sets the priority to all pieces to 0, 95 // except for the pieces that are downloaded, when pieces are decided 96 // to be downloaded. This affects the progress bar, which might be set 97 // to "100% finished" most of the time. Do not change file or piece 98 // priorities for torrents in share mode, it will make it not work. 99 // 100 // The share mode has one setting, the share ratio target, see 101 // ``settings_pack::share_mode_target`` for more info. 102 constexpr torrent_flags_t share_mode = 2_bit; 103 104 // determines if the IP filter should apply to this torrent or not. By 105 // default all torrents are subject to filtering by the IP filter 106 // (i.e. this flag is set by default). This is useful if certain 107 // torrents needs to be exempt for some reason, being an auto-update 108 // torrent for instance. 109 constexpr torrent_flags_t apply_ip_filter = 3_bit; 110 111 // specifies whether or not the torrent is paused. i.e. it won't connect to the tracker or any of the peers 112 // until it's resumed. Note that a paused torrent that also has the 113 // auto_managed flag set can be started at any time by libtorrent's queuing 114 // logic. See queuing_. 115 constexpr torrent_flags_t paused = 4_bit; 116 117 // If the torrent is auto-managed (``auto_managed``), the torrent 118 // may be resumed at any point, regardless of how it paused. If it's 119 // important to manually control when the torrent is paused and 120 // resumed, don't make it auto managed. 121 // 122 // If ``auto_managed`` is set, the torrent will be queued, 123 // started and seeded automatically by libtorrent. When this is set, 124 // the torrent should also be started as paused. The default queue 125 // order is the order the torrents were added. They are all downloaded 126 // in that order. For more details, see queuing_. 127 constexpr torrent_flags_t auto_managed = 5_bit; 128 129 // used in add_torrent_params to indicate that it's an error to attempt 130 // to add a torrent that's already in the session. If it's not considered an 131 // error, a handle to the existing torrent is returned. 132 // This flag is not saved by write_resume_data(), since it is only meant for 133 // adding torrents. 134 constexpr torrent_flags_t duplicate_is_error = 6_bit; 135 136 // on by default and means that this torrent will be part of state 137 // updates when calling post_torrent_updates(). 138 // This flag is not saved by write_resume_data(). 139 constexpr torrent_flags_t update_subscribe = 7_bit; 140 141 // sets the torrent into super seeding/initial seeding mode. If the torrent 142 // is not a seed, this flag has no effect. 143 constexpr torrent_flags_t super_seeding = 8_bit; 144 145 // sets the sequential download state for the torrent. In this mode the 146 // piece picker will pick pieces with low index numbers before pieces with 147 // high indices. The actual pieces that are picked depend on other factors 148 // still, such as which pieces a peer has and whether it is in parole mode 149 // or "prefer whole pieces"-mode. Sequential mode is not ideal for streaming 150 // media. For that, see set_piece_deadline() instead. 151 constexpr torrent_flags_t sequential_download = 9_bit; 152 153 // When this flag is set, the torrent will *force stop* whenever it 154 // transitions from a non-data-transferring state into a data-transferring 155 // state (referred to as being ready to download or seed). This is useful 156 // for torrents that should not start downloading or seeding yet, but want 157 // to be made ready to do so. A torrent may need to have its files checked 158 // for instance, so it needs to be started and possibly queued for checking 159 // (auto-managed and started) but as soon as it's done, it should be 160 // stopped. 161 // 162 // *Force stopped* means auto-managed is set to false and it's paused. As 163 // if the auto_manages flag is cleared and the paused flag is set on the torrent. 164 // 165 // Note that the torrent may transition into a downloading state while 166 // setting this flag, and since the logic is edge triggered you may 167 // miss the edge. To avoid this race, if the torrent already is in a 168 // downloading state when this call is made, it will trigger the 169 // stop-when-ready immediately. 170 // 171 // When the stop-when-ready logic fires, the flag is cleared. Any 172 // subsequent transitions between downloading and non-downloading states 173 // will not be affected, until this flag is set again. 174 // 175 // The behavior is more robust when setting this flag as part of adding 176 // the torrent. See add_torrent_params. 177 // 178 // The stop-when-ready flag fixes the inherent race condition of waiting 179 // for the state_changed_alert and then call pause(). The download/seeding 180 // will most likely start in between posting the alert and receiving the 181 // call to pause. 182 // 183 // A downloading state is one where peers are being connected. Which means 184 // just downloading the metadata via the ``ut_metadata`` extension counts 185 // as a downloading state. In order to stop a torrent once the metadata 186 // has been downloaded, instead set all file priorities to dont_download 187 constexpr torrent_flags_t stop_when_ready = 10_bit; 188 189 // when this flag is set, the tracker list in the add_torrent_params 190 // object override any trackers from the torrent file. If the flag is 191 // not set, the trackers from the add_torrent_params object will be 192 // added to the list of trackers used by the torrent. 193 // This flag is set by read_resume_data() if there are trackers present in 194 // the resume data file. This effectively makes the trackers saved in the 195 // resume data take precedence over the original trackers. This includes if 196 // there's an empty list of trackers, to support the case where they were 197 // explicitly removed in the previous session. 198 // This flag is not saved by write_resume_data() 199 constexpr torrent_flags_t override_trackers = 11_bit; 200 201 // If this flag is set, the web seeds from the add_torrent_params 202 // object will override any web seeds in the torrent file. If it's not 203 // set, web seeds in the add_torrent_params object will be added to the 204 // list of web seeds used by the torrent. 205 // This flag is set by read_resume_data() if there are web seeds present in 206 // the resume data file. This effectively makes the web seeds saved in the 207 // resume data take precedence over the original ones. This includes if 208 // there's an empty list of web seeds, to support the case where they were 209 // explicitly removed in the previous session. 210 // This flag is not saved by write_resume_data() 211 constexpr torrent_flags_t override_web_seeds = 12_bit; 212 213 // if this flag is set (which it is by default) the torrent will be 214 // considered needing to save its resume data immediately as it's 215 // added. New torrents that don't have any resume data should do that. 216 // This flag is cleared by a successful call to save_resume_data() 217 // This flag is not saved by write_resume_data(), since it represents an 218 // ephemeral state of a running torrent. 219 constexpr torrent_flags_t need_save_resume = 13_bit; 220 221 #if TORRENT_ABI_VERSION == 1 222 // indicates that this torrent should never be unloaded from RAM, even 223 // if unloading torrents are allowed in general. Setting this makes 224 // the torrent exempt from loading/unloading management. 225 constexpr torrent_flags_t TORRENT_DEPRECATED_MEMBER pinned = 14_bit; 226 227 // If ``override_resume_data`` is set, flags set for this torrent 228 // in this ``add_torrent_params`` object will take precedence over 229 // whatever states are saved in the resume data. For instance, the 230 // ``paused``, ``auto_managed``, ``sequential_download``, ``seed_mode``, 231 // ``super_seeding``, ``max_uploads``, ``max_connections``, 232 // ``upload_limit`` and ``download_limit`` are all affected by this 233 // flag. The intention of this flag is to have any field in 234 // add_torrent_params configuring the torrent override the corresponding 235 // configuration from the resume file, with the one exception of save 236 // resume data, which has its own flag (for historic reasons). 237 // "file_priorities" and "save_path" are not affected by this flag. 238 constexpr torrent_flags_t TORRENT_DEPRECATED_MEMBER override_resume_data = 15_bit; 239 240 // defaults to on and specifies whether tracker URLs loaded from 241 // resume data should be added to the trackers in the torrent or 242 // replace the trackers. When replacing trackers (i.e. this flag is not 243 // set), any trackers passed in via add_torrent_params are also 244 // replaced by any trackers in the resume data. The default behavior is 245 // to have the resume data override the .torrent file _and_ the 246 // trackers added in add_torrent_params. 247 constexpr torrent_flags_t TORRENT_DEPRECATED_MEMBER merge_resume_trackers = 16_bit; 248 249 // if this flag is set, the save path from the resume data file, if 250 // present, is honored. This defaults to not being set, in which 251 // case the save_path specified in add_torrent_params is always used. 252 constexpr torrent_flags_t TORRENT_DEPRECATED_MEMBER use_resume_save_path = 17_bit; 253 254 // defaults to on and specifies whether web seed URLs loaded from 255 // resume data should be added to the ones in the torrent file or 256 // replace them. No distinction is made between the two different kinds 257 // of web seeds (`BEP 17`_ and `BEP 19`_). When replacing web seeds 258 // (i.e. when this flag is not set), any web seeds passed in via 259 // add_torrent_params are also replaced. The default behavior is to 260 // have any web seeds in the resume data take precedence over whatever 261 // is passed in here as well as the .torrent file. 262 constexpr torrent_flags_t TORRENT_DEPRECATED_MEMBER merge_resume_http_seeds = 18_bit; 263 #endif 264 265 // set this flag to disable DHT for this torrent. This lets you have the DHT 266 // enabled for the whole client, and still have specific torrents not 267 // participating in it. i.e. not announcing to the DHT nor picking up peers 268 // from it. 269 constexpr torrent_flags_t disable_dht = 19_bit; 270 271 // set this flag to disable local service discovery for this torrent. 272 constexpr torrent_flags_t disable_lsd = 20_bit; 273 274 // set this flag to disable peer exchange for this torrent. 275 constexpr torrent_flags_t disable_pex = 21_bit; 276 277 // if this flag is set, the resume data will be assumed to be correct 278 // without validating it against any files on disk. This may be used when 279 // restoring a session by loading resume data from disk. It will save time 280 // and also delay any hard disk errors until files are actually needed. If 281 // the resume data cannot be trusted, or if a torrent is added for the first 282 // time to some save path that may already have some of the files, this flag 283 // should not be set. 284 constexpr torrent_flags_t no_verify_files = 22_bit; 285 286 // all torrent flags combined. Can conveniently be used when creating masks 287 // for flags 288 constexpr torrent_flags_t all = torrent_flags_t::all(); 289 290 // internal 291 constexpr torrent_flags_t default_flags = 292 torrent_flags::update_subscribe 293 | torrent_flags::auto_managed 294 | torrent_flags::paused 295 | torrent_flags::apply_ip_filter 296 | torrent_flags::need_save_resume 297 #if TORRENT_ABI_VERSION == 1 298 | torrent_flags::pinned 299 | torrent_flags::merge_resume_http_seeds 300 | torrent_flags::merge_resume_trackers 301 #endif 302 ; 303 304 #if TORRENT_ABI_VERSION == 1 305 #include "libtorrent/aux_/disable_warnings_pop.hpp" 306 #endif 307 308 } // torrent_flags 309 } // libtorrent 310 311 #endif 312 313