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