include/libtorrent/torrent_handle.hpp

   1 /*
   2
   3 Copyright (c) 2003, 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_HANDLE_HPP_INCLUDED
  34 #define TORRENT_TORRENT_HANDLE_HPP_INCLUDED
  35
  36 #include <vector>
  37 #include <set>
  38
  39 #ifdef _MSC_VER
  40 #pragma warning(push, 1)
  41 #endif
  42
  43 #include <boost/date_time/posix_time/posix_time_types.hpp>
  44
  45 #ifdef _MSC_VER
  46 #pragma warning(pop)
  47 #endif
  48
  49 #include "libtorrent/peer_id.hpp"
  50 #include "libtorrent/peer_info.hpp"
  51 #include "libtorrent/piece_picker.hpp"
  52 #include "libtorrent/torrent_info.hpp"
  53 #include "libtorrent/time.hpp"
  54 #include "libtorrent/config.hpp"
  55 #include "libtorrent/storage.hpp"
  56
  57 namespace libtorrent
  58 {
  59         namespace fs = boost::filesystem;
  60
  61         namespace aux
  62         {
  63                 struct session_impl;
  64                 struct checker_impl;
  65         }
  66
  67         struct torrent_plugin;
  68
  69         struct TORRENT_EXPORT duplicate_torrent: std::exception
  70         {
  71                 virtual const char* what() const throw()
  72                 { return "torrent already exists in session"; }
  73         };
  74
  75         struct TORRENT_EXPORT invalid_handle: std::exception
  76         {
  77                 virtual const char* what() const throw()
  78                 { return "invalid torrent handle used"; }
  79         };
  80
  81         struct TORRENT_EXPORT torrent_status
  82         {
  83                 torrent_status()
  84                         : state(queued_for_checking)
  85                         , paused(false)
  86                         , progress(0.f)
  87                         , total_download(0)
  88                         , total_upload(0)
  89                         , total_payload_download(0)
  90                         , total_payload_upload(0)
  91                         , total_failed_bytes(0)
  92                         , total_redundant_bytes(0)
  93                         , download_rate(0)
  94                         , upload_rate(0)
  95                         , download_payload_rate(0)
  96                         , upload_payload_rate(0)
  97                         , num_seeds(0)
  98                         , num_peers(0)
  99                         , num_complete(-1)
 100                         , num_incomplete(-1)
 101                         , list_seeds(0)
 102                         , list_peers(0)
 103                         , num_pieces(0)
 104                         , total_done(0)
 105                         , total_wanted_done(0)
 106                         , total_wanted(0)
 107                         , distributed_copies(0.f)
 108                         , block_size(0)
 109                         , num_uploads(0)
 110                         , num_connections(0)
 111                         , uploads_limit(0)
 112                         , connections_limit(0)
 113                         , storage_mode(storage_mode_sparse)
 114                         , up_bandwidth_queue(0)
 115                         , down_bandwidth_queue(0)
 116                         , all_time_upload(0)
 117                         , all_time_download(0)
 118                         , active_time(0)
 119                         , seeding_time(0)
 120                         , seed_rank(0)
 121                         , last_scrape(0)
 122                         , has_incoming(false)
 123                 {}
 124
 125                 enum state_t
 126                 {
 127                         queued_for_checking,
 128                         checking_files,
 129                         connecting_to_tracker,
 130                         downloading_metadata,
 131                         downloading,
 132                         finished,
 133                         seeding,
 134                         allocating
 135                 };
 136
 137                 state_t state;
 138                 bool paused;
 139                 float progress;
 140                 std::string error;
 141
 142                 boost::posix_time::time_duration next_announce;
 143                 boost::posix_time::time_duration announce_interval;
 144
 145                 std::string current_tracker;
 146
 147                 // transferred this session!
 148                 // total, payload plus protocol
 149                 size_type total_download;
 150                 size_type total_upload;
 151
 152                 // payload only
 153                 size_type total_payload_download;
 154                 size_type total_payload_upload;
 155
 156                 // the amount of payload bytes that
 157                 // has failed their hash test
 158                 size_type total_failed_bytes;
 159
 160                 // the number of payload bytes that
 161                 // has been received redundantly.
 162                 size_type total_redundant_bytes;
 163
 164                 // current transfer rate
 165                 // payload plus protocol
 166                 float download_rate;
 167                 float upload_rate;
 168
 169                 // the rate of payload that is
 170                 // sent and received
 171                 float download_payload_rate;
 172                 float upload_payload_rate;
 173
 174                 // the number of peers this torrent is connected to
 175                 // that are seeding.
 176                 int num_seeds;
 177
 178                 // the number of peers this torrent
 179                 // is connected to (including seeds).
 180                 int num_peers;
 181
 182                 // if the tracker sends scrape info in its
 183                 // announce reply, these fields will be
 184                 // set to the total number of peers that
 185                 // have the whole file and the total number
 186                 // of peers that are still downloading
 187                 int num_complete;
 188                 int num_incomplete;
 189
 190                 // this is the number of seeds whose IP we know
 191                 // but are not necessarily connected to
 192                 int list_seeds;
 193
 194                 // this is the number of peers whose IP we know
 195                 // (including seeds), but are not necessarily
 196                 // connected to
 197                 int list_peers;
 198
 199                 // the number of peers in our peerlist that
 200                 // we potentially could connect to
 201                 int connect_candidates;
 202
 203                 bitfield pieces;
 204
 205                 // this is the number of pieces the client has
 206                 // downloaded. it is equal to:
 207                 // std::accumulate(pieces->begin(), pieces->end());
 208                 int num_pieces;
 209
 210                 // the number of bytes of the file we have
 211                 // including pieces that may have been filtered
 212                 // after we downloaded them
 213                 size_type total_done;
 214
 215                 // the number of bytes we have of those that we
 216                 // want. i.e. not counting bytes from pieces that
 217                 // are filtered as not wanted.
 218                 size_type total_wanted_done;
 219
 220                 // the total number of bytes we want to download
 221                 // this may be smaller than the total torrent size
 222                 // in case any pieces are filtered as not wanted
 223                 size_type total_wanted;
 224
 225                 // the number of distributed copies of the file.
 226                 // note that one copy may be spread out among many peers.
 227                 //
 228                 // the integer part tells how many copies
 229                 //   there are of the rarest piece(s)
 230                 //
 231                 // the fractional part tells the fraction of pieces that
 232                 //   have more copies than the rarest piece(s).
 233                 float distributed_copies;
 234
 235                 // the block size that is used in this torrent. i.e.
 236                 // the number of bytes each piece request asks for
 237                 // and each bit in the download queue bitfield represents
 238                 int block_size;
 239
 240                 int num_uploads;
 241                 int num_connections;
 242                 int uploads_limit;
 243                 int connections_limit;
 244
 245                 // true if the torrent is saved in compact mode
 246                 // false if it is saved in full allocation mode
 247                 storage_mode_t storage_mode;
 248
 249                 int up_bandwidth_queue;
 250                 int down_bandwidth_queue;
 251
 252                 // number of bytes downloaded since torrent was started
 253                 // saved and restored from resume data
 254                 size_type all_time_upload;
 255                 size_type all_time_download;
 256
 257                 // the number of seconds of being active
 258                 // and as being a seed, saved and restored
 259                 // from resume data
 260                 int active_time;
 261                 int seeding_time;
 262
 263                 // higher value means more important to seed
 264                 int seed_rank;
 265
 266                 // number of seconds since last scrape, or -1 if
 267                 // there hasn't been a scrape
 268                 int last_scrape;
 269
 270                 // true if there are incoming connections to this
 271                 // torrent
 272                 bool has_incoming;
 273         };
 274
 275         struct TORRENT_EXPORT block_info
 276         {
 277                 enum block_state_t
 278                 { none, requested, writing, finished };
 279
 280                 tcp::endpoint peer;
 281                 // number of bytes downloaded in this block
 282                 unsigned bytes_progress:16;
 283                 // the total number of bytes in this block
 284                 unsigned block_size:16;
 285                 // the state this block is in (see block_state_t)
 286                 unsigned state:2;
 287                 // the number of peers that has requested this block
 288                 // typically 0 or 1. If > 1, this block is in
 289                 // end game mode
 290                 unsigned num_peers:14;
 291         };
 292
 293         struct TORRENT_EXPORT partial_piece_info
 294         {
 295                 enum { max_blocks_per_piece = 256 };
 296                 int piece_index;
 297                 int blocks_in_piece;
 298                 // the number of blocks in the finished state
 299                 int finished;
 300                 // the number of blocks in the writing state
 301                 int writing;
 302                 // the number of blocks in the requested state
 303                 int requested;
 304                 block_info blocks[max_blocks_per_piece];
 305                 enum state_t { none, slow, medium, fast };
 306                 state_t piece_state;
 307         };
 308
 309         struct TORRENT_EXPORT torrent_handle
 310         {
 311                 friend class invariant_access;
 312                 friend struct aux::session_impl;
 313                 friend class torrent;
 314
 315                 torrent_handle() {}
 316
 317                 void get_full_peer_list(std::vector<peer_list_entry>& v) const;
 318                 void get_peer_info(std::vector<peer_info>& v) const;
 319                 torrent_status status() const;
 320                 void get_download_queue(std::vector<partial_piece_info>& queue) const;
 321
 322                 // fills the specified vector with the download progress [0, 1]
 323                 // of each file in the torrent. The files are ordered as in
 324                 // the torrent_info.
 325                 void file_progress(std::vector<float>& progress) const TORRENT_DEPRECATED;
 326                 void file_progress(std::vector<size_type>& progress) const;
 327
 328                 void clear_error() const;
 329
 330                 std::vector<announce_entry> const& trackers() const;
 331                 void replace_trackers(std::vector<announce_entry> const&) const;
 332
 333                 void add_url_seed(std::string const& url) const;
 334                 void remove_url_seed(std::string const& url) const;
 335                 std::set<std::string> url_seeds() const;
 336
 337 #ifndef TORRENT_DISABLE_EXTENSIONS
 338                 void add_extension(boost::function<boost::shared_ptr<torrent_plugin>(torrent*, void*)> const& ext
 339                         , void* userdata = 0);
 340 #endif
 341
 342                 bool has_metadata() const;
 343                 const torrent_info& get_torrent_info() const;
 344                 bool is_valid() const;
 345
 346                 bool is_seed() const;
 347                 bool is_finished() const;
 348                 bool is_paused() const;
 349                 void pause() const;
 350                 void resume() const;
 351                 void force_recheck() const;
 352                 void save_resume_data() const;
 353
 354                 bool is_auto_managed() const;
 355                 void auto_managed(bool m) const;
 356
 357                 int queue_position() const;
 358                 void queue_position_up() const;
 359                 void queue_position_down() const;
 360                 void queue_position_top() const;
 361                 void queue_position_bottom() const;
 362
 363 #ifndef TORRENT_DISABLE_RESOLVE_COUNTRIES
 364                 void resolve_countries(bool r);
 365                 bool resolve_countries() const;
 366 #endif
 367
 368                 // all these are deprecated, use piece
 369                 // priority functions instead
 370
 371                 // ================ start deprecation ============
 372
 373                 // deprecated in 0.13
 374                 // marks the piece with the given index as filtered
 375                 // it will not be downloaded
 376                 void filter_piece(int index, bool filter) const TORRENT_DEPRECATED;
 377                 void filter_pieces(std::vector<bool> const& pieces) const TORRENT_DEPRECATED;
 378                 bool is_piece_filtered(int index) const TORRENT_DEPRECATED;
 379                 std::vector<bool> filtered_pieces() const TORRENT_DEPRECATED;
 380                 // marks the file with the given index as filtered
 381                 // it will not be downloaded
 382                 void filter_files(std::vector<bool> const& files) const TORRENT_DEPRECATED;
 383
 384                 // ================ end deprecation ============
 385
 386                 void piece_availability(std::vector<int>& avail) const;
 387
 388                 // priority must be within the range [0, 7]
 389                 void piece_priority(int index, int priority) const;
 390                 int piece_priority(int index) const;
 391
 392                 void prioritize_pieces(std::vector<int> const& pieces) const;
 393                 std::vector<int> piece_priorities() const;
 394
 395                 // priority must be within the range [0, 7]
 396                 void file_priority(int index, int priority) const;
 397                 int file_priority(int index) const;
 398
 399                 void prioritize_files(std::vector<int> const& files) const;
 400                 std::vector<int> file_priorities() const;
 401
 402                 // set the interface to bind outgoing connections
 403                 // to.
 404                 void use_interface(const char* net_interface) const;
 405
 406                 // deprecated in 0.14
 407                 // use save_resume_data() instead. It is async. and
 408                 // will return the resume data in an alert
 409                 entry write_resume_data() const TORRENT_DEPRECATED;
 410
 411                 // forces this torrent to reannounce
 412                 // (make a rerequest from the tracker)
 413                 void force_reannounce() const;
 414
 415                 // forces a reannounce in the specified amount of time.
 416                 // This overrides the default announce interval, and no
 417                 // announce will take place until the given time has
 418                 // timed out.
 419                 void force_reannounce(boost::posix_time::time_duration) const;
 420
 421                 // performs a scrape request
 422                 void scrape_tracker() const;
 423
 424                 // returns the name of this torrent, in case it doesn't
 425                 // have metadata it returns the name assigned to it
 426                 // when it was added.
 427                 std::string name() const;
 428
 429                 // TODO: add a feature where the user can tell the torrent
 430                 // to finish all pieces currently in the pipeline, and then
 431                 // abort the torrent.
 432
 433                 void set_upload_limit(int limit) const;
 434                 int upload_limit() const;
 435                 void set_download_limit(int limit) const;
 436                 int download_limit() const;
 437
 438                 void set_sequential_download(bool sd) const;
 439                 bool is_sequential_download() const;
 440
 441                 void set_peer_upload_limit(tcp::endpoint ip, int limit) const;
 442                 void set_peer_download_limit(tcp::endpoint ip, int limit) const;
 443
 444                 // manually connect a peer
 445                 void connect_peer(tcp::endpoint const& adr, int source = 0) const;
 446
 447                 // valid ratios are 0 (infinite ratio) or [ 1.0 , inf )
 448                 // the ratio is uploaded / downloaded. less than 1 is not allowed
 449                 void set_ratio(float up_down_ratio) const;
 450
 451                 fs::path save_path() const;
 452
 453                 // -1 means unlimited unchokes
 454                 void set_max_uploads(int max_uploads) const;
 455
 456                 // -1 means unlimited connections
 457                 void set_max_connections(int max_connections) const;
 458
 459                 void set_tracker_login(std::string const& name
 460                         , std::string const& password) const;
 461
 462                 // post condition: save_path() == save_path if true is returned
 463                 void move_storage(fs::path const& save_path) const;
 464                 void rename_file(int index, fs::path const& new_name) const;
 465
 466                 sha1_hash info_hash() const;
 467
 468                 bool operator==(const torrent_handle& h) const
 469                 { return m_torrent.lock() == h.m_torrent.lock(); }
 470
 471                 bool operator!=(const torrent_handle& h) const
 472                 { return m_torrent.lock() != h.m_torrent.lock(); }
 473
 474                 bool operator<(const torrent_handle& h) const
 475                 { return m_torrent.lock() < h.m_torrent.lock(); }
 476
 477         private:
 478
 479                 torrent_handle(boost::weak_ptr<torrent> const& t)
 480                         : m_torrent(t)
 481                 {}
 482
 483 #ifndef NDEBUG
 484                 void check_invariant() const;
 485 #endif
 486
 487                 boost::weak_ptr<torrent> m_torrent;
 488
 489         };
 490
 491
 492 }
 493
 494 #endif // TORRENT_TORRENT_HANDLE_HPP_INCLUDED
 495