apt-pkg/acquire.h

   1 // -*- mode: cpp; mode: fold -*-
   2 // Description                                                          /*{{{*/
   3 // $Id: acquire.h,v 1.29.2.1 2003/12/24 23:09:17 mdz Exp $
   4 /* ######################################################################
   5
   6    Acquire - File Acquiration
   7
   8    This module contians the Acquire system. It is responsible for bringing
   9    files into the local pathname space. It deals with URIs for files and
  10    URI handlers responsible for downloading or finding the URIs.
  11
  12    Each file to download is represented by an Acquire::Item class subclassed
  13    into a specialization. The Item class can add itself to several URI
  14    acquire queues each prioritized by the download scheduler. When the
  15    system is run the proper URI handlers are spawned and the the acquire
  16    queues are fed into the handlers by the schedular until the queues are
  17    empty. This allows for an Item to be downloaded from an alternate source
  18    if the first try turns out to fail. It also alows concurrent downloading
  19    of multiple items from multiple sources as well as dynamic balancing
  20    of load between the sources.
  21
  22    Schedualing of downloads is done on a first ask first get basis. This
  23    preserves the order of the download as much as possible. And means the
  24    fastest source will tend to process the largest number of files.
  25
  26    Internal methods and queues for performing gzip decompression,
  27    md5sum hashing and file copying are provided to allow items to apply
  28    a number of transformations to the data files they are working with.
  29
  30    ##################################################################### */
  31                                                                         /*}}}*/
  32
  33 /** \defgroup acquire Acquire system                                    {{{
  34  *
  35  *  \brief The Acquire system is responsible for retrieving files from
  36  *  local or remote URIs and postprocessing them (for instance,
  37  *  verifying their authenticity).  The core class in this system is
  38  *  pkgAcquire, which is responsible for managing the download queues
  39  *  during the download.  There is at least one download queue for
  40  *  each supported protocol; protocols such as http may provide one
  41  *  queue per host.
  42  *
  43  *  Each file to download is represented by a subclass of
  44  *  pkgAcquire::Item.  The files add themselves to the download
  45  *  queue(s) by providing their URI information to
  46  *  pkgAcquire::Item::QueueURI, which calls pkgAcquire::Enqueue.
  47  *
  48  *  Once the system is set up, the Run method will spawn subprocesses
  49  *  to handle the enqueued URIs; the scheduler will then take items
  50  *  from the queues and feed them into the handlers until the queues
  51  *  are empty.
  52  *
  53  *  \todo Acquire supports inserting an object into several queues at
  54  *  once, but it is not clear what its behavior in this case is, and
  55  *  no subclass of pkgAcquire::Item seems to actually use this
  56  *  capability.
  57  */                                                                     /*}}}*/
  58
  59 /** \addtogroup acquire
  60  *
  61  *  @{
  62  *
  63  *  \file acquire.h
  64  */
  65
  66 #ifndef PKGLIB_ACQUIRE_H
  67 #define PKGLIB_ACQUIRE_H
  68
  69 #include <apt-pkg/macros.h>
  70 #include <apt-pkg/weakptr.h>
  71
  72 #include <vector>
  73 #include <string>
  74
  75 #include <sys/time.h>
  76 #include <unistd.h>
  77
  78 #ifndef APT_8_CLEANER_HEADERS
  79 using std::vector;
  80 using std::string;
  81 #endif
  82
  83 class pkgAcquireStatus;
  84
  85 /** \brief The core download scheduler.                                 {{{
  86  *
  87  *  This class represents an ongoing download.  It manages the lists
  88  *  of active and pending downloads and handles setting up and tearing
  89  *  down download-related structures.
  90  *
  91  *  \todo Why all the protected data items and methods?
  92  */
  93 class pkgAcquire
  94 {
  95    private:
  96    /** \brief FD of the Lock file we acquire in Setup (if any) */
  97    int LockFD;
  98    /** \brief dpointer placeholder (for later in case we need it) */
  99    void *d;
 100
 101    public:
 102
 103    class Item;
 104    class Queue;
 105    class Worker;
 106    struct MethodConfig;
 107    struct ItemDesc;
 108    friend class Item;
 109    friend class Queue;
 110
 111    typedef std::vector<Item *>::iterator ItemIterator;
 112    typedef std::vector<Item *>::const_iterator ItemCIterator;
 113
 114    protected:
 115
 116    /** \brief A list of items to download.
 117     *
 118     *  This is built monotonically as items are created and only
 119     *  emptied when the download shuts down.
 120     */
 121    std::vector<Item *> Items;
 122
 123    /** \brief The head of the list of active queues.
 124     *
 125     *  \todo why a hand-managed list of queues instead of std::list or
 126     *  std::set?
 127     */
 128    Queue *Queues;
 129
 130    /** \brief The head of the list of active workers.
 131     *
 132     *  \todo why a hand-managed list of workers instead of std::list
 133     *  or std::set?
 134     */
 135    Worker *Workers;
 136
 137    /** \brief The head of the list of acquire method configurations.
 138     *
 139     *  Each protocol (http, ftp, gzip, etc) via which files can be
 140     *  fetched can have a representation in this list.  The
 141     *  configuration data is filled in by parsing the 100 Capabilities
 142     *  string output by a method on startup (see
 143     *  pkgAcqMethod::pkgAcqMethod and pkgAcquire::GetConfig).
 144     *
 145     *  \todo why a hand-managed config dictionary instead of std::map?
 146     */
 147    MethodConfig *Configs;
 148
 149    /** \brief The progress indicator for this download. */
 150    pkgAcquireStatus *Log;
 151
 152    /** \brief The number of files which are to be fetched. */
 153    unsigned long ToFetch;
 154
 155    // Configurable parameters for the scheduler
 156
 157    /** \brief Represents the queuing strategy for remote URIs. */
 158    enum QueueStrategy {
 159      /** \brief Generate one queue for each protocol/host combination; downloads from
 160       *  multiple hosts can proceed in parallel.
 161       */
 162      QueueHost,
 163      /** \brief Generate a single queue for each protocol; serialize
 164       *  downloads from multiple hosts.
 165       */
 166      QueueAccess} QueueMode;
 167
 168    /** \brief If \b true, debugging information will be dumped to std::clog. */
 169    bool const Debug;
 170    /** \brief If \b true, a download is currently in progress. */
 171    bool Running;
 172
 173    /** \brief Add the given item to the list of items. */
 174    void Add(Item *Item);
 175
 176    /** \brief Remove the given item from the list of items. */
 177    void Remove(Item *Item);
 178
 179    /** \brief Add the given worker to the list of workers. */
 180    void Add(Worker *Work);
 181
 182    /** \brief Remove the given worker from the list of workers. */
 183    void Remove(Worker *Work);
 184
 185    /** \brief Insert the given fetch request into the appropriate queue.
 186     *
 187     *  \param Item The URI to download and the item to download it
 188     *  for.  Copied by value into the queue; no reference to Item is
 189     *  retained.
 190     */
 191    void Enqueue(ItemDesc &Item);
 192
 193    /** \brief Remove all fetch requests for this item from all queues. */
 194    void Dequeue(Item *Item);
 195
 196    /** \brief Determine the fetch method and queue of a URI.
 197     *
 198     *  \param URI The URI to fetch.
 199     *
 200     *  \param[out] Config A location in which to place the method via
 201     *  which the URI is to be fetched.
 202     *
 203     *  \return the string-name of the queue in which a fetch request
 204     *  for the given URI should be placed.
 205     */
 206    std::string QueueName(std::string URI,MethodConfig const *&Config);
 207
 208    /** \brief Build up the set of file descriptors upon which select() should
 209     *  block.
 210     *
 211     *  The default implementation inserts the file descriptors
 212     *  corresponding to active downloads.
 213     *
 214     *  \param[out] Fd The largest file descriptor in the generated sets.
 215     *
 216     *  \param[out] RSet The set of file descriptors that should be
 217     *  watched for input.
 218     *
 219     *  \param[out] WSet The set of file descriptors that should be
 220     *  watched for output.
 221     */
 222    virtual void SetFds(int &Fd,fd_set *RSet,fd_set *WSet);
 223
 224    /** Handle input from and output to file descriptors which select()
 225     *  has determined are ready.  The default implementation
 226     *  dispatches to all active downloads.
 227     *
 228     *  \param RSet The set of file descriptors that are ready for
 229     *  input.
 230     *
 231     *  \param WSet The set of file descriptors that are ready for
 232     *  output.
 233     */
 234    virtual void RunFds(fd_set *RSet,fd_set *WSet);
 235
 236    /** \brief Check for idle queues with ready-to-fetch items.
 237     *
 238     *  Called by pkgAcquire::Queue::Done each time an item is dequeued
 239     *  but remains on some queues; i.e., another queue should start
 240     *  fetching it.
 241     */
 242    void Bump();
 243
 244    public:
 245
 246    /** \brief Retrieve information about a fetch method by name.
 247     *
 248     *  \param Access The name of the method to look up.
 249     *
 250     *  \return the method whose name is Access, or \b NULL if no such method exists.
 251     */
 252    MethodConfig *GetConfig(std::string Access);
 253
 254    /** \brief Provides information on how a download terminated. */
 255    enum RunResult {
 256      /** \brief All files were fetched successfully. */
 257      Continue,
 258
 259      /** \brief Some files failed to download. */
 260      Failed,
 261
 262      /** \brief The download was cancelled by the user (i.e., #Log's
 263       *  pkgAcquireStatus::Pulse() method returned \b false).
 264       */
 265      Cancelled};
 266
 267    /** \brief Download all the items that have been Add()ed to this
 268     *  download process.
 269     *
 270     *  This method will block until the download completes, invoking
 271     *  methods on #Log to report on the progress of the download.
 272     *
 273     *  \param PulseInterval The method pkgAcquireStatus::Pulse will be
 274     *  invoked on #Log at intervals of PulseInterval milliseconds.
 275     *
 276     *  \return the result of the download.
 277     */
 278    RunResult Run(int PulseInterval=500000);
 279
 280    /** \brief Remove all items from this download process, terminate
 281     *  all download workers, and empty all queues.
 282     */
 283    void Shutdown();
 284
 285    /** \brief Get the first #Worker object.
 286     *
 287     *  \return the first active worker in this download process.
 288     */
 289    inline Worker *WorkersBegin() {return Workers;};
 290
 291    /** \brief Advance to the next #Worker object.
 292     *
 293     *  \return the worker immediately following I, or \b NULL if none
 294     *  exists.
 295     */
 296    Worker *WorkerStep(Worker *I);
 297
 298    /** \brief Get the head of the list of items. */
 299    inline ItemIterator ItemsBegin() {return Items.begin();};
 300
 301    /** \brief Get the end iterator of the list of items. */
 302    inline ItemIterator ItemsEnd() {return Items.end();};
 303
 304    // Iterate over queued Item URIs
 305    class UriIterator;
 306    /** \brief Get the head of the list of enqueued item URIs.
 307     *
 308     *  This iterator will step over every element of every active
 309     *  queue.
 310     */
 311    UriIterator UriBegin();
 312    /** \brief Get the end iterator of the list of enqueued item URIs. */
 313    UriIterator UriEnd();
 314
 315    /** Deletes each entry in the given directory that is not being
 316     *  downloaded by this object.  For instance, when downloading new
 317     *  list files, calling Clean() will delete the old ones.
 318     *
 319     *  \param Dir The directory to be cleaned out.
 320     *
 321     *  \return \b true if the directory exists and is readable.
 322     */
 323    bool Clean(std::string Dir);
 324
 325    /** \return the total size in bytes of all the items included in
 326     *  this download.
 327     */
 328    unsigned long long TotalNeeded();
 329
 330    /** \return the size in bytes of all non-local items included in
 331     *  this download.
 332     */
 333    unsigned long long FetchNeeded();
 334
 335    /** \return the amount of data to be fetched that is already
 336     *  present on the filesystem.
 337     */
 338    unsigned long long PartialPresent();
 339
 340    /** \brief Delayed constructor
 341     *
 342     *  \param Progress indicator associated with this download or
 343     *  \b NULL for none.  This object is not owned by the
 344     *  download process and will not be deleted when the pkgAcquire
 345     *  object is destroyed.  Naturally, it should live for at least as
 346     *  long as the pkgAcquire object does.
 347     *  \param Lock defines a lock file that should be acquired to ensure
 348     *  only one Acquire class is in action at the time or an empty string
 349     *  if no lock file should be used.
 350     */
 351    bool Setup(pkgAcquireStatus *Progress = NULL, std::string const &Lock = "");
 352
 353    void SetLog(pkgAcquireStatus *Progress) { Log = Progress; }
 354
 355    /** \brief Construct a new pkgAcquire. */
 356    pkgAcquire(pkgAcquireStatus *Log) __deprecated;
 357    pkgAcquire();
 358
 359    /** \brief Destroy this pkgAcquire object.
 360     *
 361     *  Destroys all queue, method, and item objects associated with
 362     *  this download.
 363     */
 364    virtual ~pkgAcquire();
 365
 366 };
 367
 368 /** \brief Represents a single download source from which an item
 369  *  should be downloaded.
 370  *
 371  *  An item may have several assocated ItemDescs over its lifetime.
 372  */
 373 struct pkgAcquire::ItemDesc : public WeakPointable
 374 {
 375    /** \brief The URI from which to download this item. */
 376    std::string URI;
 377    /** brief A description of this item. */
 378    std::string Description;
 379    /** brief A shorter description of this item. */
 380    std::string ShortDesc;
 381    /** brief The underlying item which is to be downloaded. */
 382    Item *Owner;
 383 };
 384                                                                         /*}}}*/
 385 /** \brief A single download queue in a pkgAcquire object.              {{{
 386  *
 387  *  \todo Why so many protected values?
 388  */
 389 class pkgAcquire::Queue
 390 {
 391    friend class pkgAcquire;
 392    friend class pkgAcquire::UriIterator;
 393    friend class pkgAcquire::Worker;
 394
 395    /** \brief dpointer placeholder (for later in case we need it) */
 396    void *d;
 397
 398    /** \brief The next queue in the pkgAcquire object's list of queues. */
 399    Queue *Next;
 400
 401    protected:
 402
 403    /** \brief A single item placed in this queue. */
 404    struct QItem : pkgAcquire::ItemDesc
 405    {
 406       /** \brief The next item in the queue. */
 407       QItem *Next;
 408       /** \brief The worker associated with this item, if any. */
 409       pkgAcquire::Worker *Worker;
 410
 411       /** \brief Assign the ItemDesc portion of this QItem from
 412        *  another ItemDesc
 413        */
 414       void operator =(pkgAcquire::ItemDesc const &I)
 415       {
 416          URI = I.URI;
 417          Description = I.Description;
 418          ShortDesc = I.ShortDesc;
 419          Owner = I.Owner;
 420       };
 421    };
 422
 423    /** \brief The name of this queue. */
 424    std::string Name;
 425
 426    /** \brief The head of the list of items contained in this queue.
 427     *
 428     *  \todo why a by-hand list instead of an STL structure?
 429     */
 430    QItem *Items;
 431
 432    /** \brief The head of the list of workers associated with this queue.
 433     *
 434     *  \todo This is plural because support exists in Queue for
 435     *  multiple workers.  However, it does not appear that there is
 436     *  any way to actually associate more than one worker with a
 437     *  queue.
 438     *
 439     *  \todo Why not just use a std::set?
 440     */
 441    pkgAcquire::Worker *Workers;
 442
 443    /** \brief the download scheduler with which this queue is associated. */
 444    pkgAcquire *Owner;
 445
 446    /** \brief The number of entries in this queue that are currently
 447     *  being downloaded.
 448     */
 449    signed long PipeDepth;
 450
 451    /** \brief The maximum number of entries that this queue will
 452     *  attempt to download at once.
 453     */
 454    unsigned long MaxPipeDepth;
 455
 456    public:
 457
 458    /** \brief Insert the given fetch request into this queue.
 459     *
 460     *  \return \b true if the queuing was successful. May return
 461     *  \b false if the Item is already in the queue
 462     */
 463    bool Enqueue(ItemDesc &Item);
 464
 465    /** \brief Remove all fetch requests for the given item from this queue.
 466     *
 467     *  \return \b true if at least one request was removed from the queue.
 468     */
 469    bool Dequeue(Item *Owner);
 470
 471    /** \brief Locate an item in this queue.
 472     *
 473     *  \param URI A URI to match against.
 474     *  \param Owner A pkgAcquire::Worker to match against.
 475     *
 476     *  \return the first item in the queue whose URI is #URI and that
 477     *  is being downloaded by #Owner.
 478     */
 479    QItem *FindItem(std::string URI,pkgAcquire::Worker *Owner);
 480
 481    /** Presumably this should start downloading an item?
 482     *
 483     *  \todo Unimplemented.  Implement it or remove?
 484     */
 485    bool ItemStart(QItem *Itm,unsigned long long Size);
 486
 487    /** \brief Remove the given item from this queue and set its state
 488     *  to pkgAcquire::Item::StatDone.
 489     *
 490     *  If this is the only queue containing the item, the item is also
 491     *  removed from the main queue by calling pkgAcquire::Dequeue.
 492     *
 493     *  \param Itm The item to remove.
 494     *
 495     *  \return \b true if no errors are encountered.
 496     */
 497    bool ItemDone(QItem *Itm);
 498
 499    /** \brief Start the worker process associated with this queue.
 500     *
 501     *  If a worker process is already associated with this queue,
 502     *  this is equivalent to calling Cycle().
 503     *
 504     *  \return \b true if the startup was successful.
 505     */
 506    bool Startup();
 507
 508    /** \brief Shut down the worker process associated with this queue.
 509     *
 510     *  \param Final If \b true, then the process is stopped unconditionally.
 511     *               Otherwise, it is only stopped if it does not need cleanup
 512     *               as indicated by the pkgAcqMethod::NeedsCleanup member of
 513     *               its configuration.
 514     *
 515     *  \return \b true.
 516     */
 517    bool Shutdown(bool Final);
 518
 519    /** \brief Send idle items to the worker process.
 520     *
 521     *  Fills up the pipeline by inserting idle items into the worker's queue.
 522     */
 523    bool Cycle();
 524
 525    /** \brief Check for items that could be enqueued.
 526     *
 527     *  Call this after an item placed in multiple queues has gone from
 528     *  the pkgAcquire::Item::StatFetching state to the
 529     *  pkgAcquire::Item::StatIdle state, to possibly refill an empty queue.
 530     *  This is an alias for Cycle().
 531     *
 532     *  \todo Why both this and Cycle()?  Are they expected to be
 533     *  different someday?
 534     */
 535    void Bump();
 536
 537    /** \brief Create a new Queue.
 538     *
 539     *  \param Name The name of the new queue.
 540     *  \param Owner The download process that owns the new queue.
 541     */
 542    Queue(std::string Name,pkgAcquire *Owner);
 543
 544    /** Shut down all the worker processes associated with this queue
 545     *  and empty the queue.
 546     */
 547    virtual ~Queue();
 548 };
 549                                                                         /*}}}*/
 550 /** \brief Iterates over all the URIs being fetched by a pkgAcquire object.     {{{*/
 551 class pkgAcquire::UriIterator
 552 {
 553    /** \brief dpointer placeholder (for later in case we need it) */
 554    void *d;
 555
 556    /** The next queue to iterate over. */
 557    pkgAcquire::Queue *CurQ;
 558    /** The item that we currently point at. */
 559    pkgAcquire::Queue::QItem *CurItem;
 560
 561    public:
 562
 563    inline void operator ++() {operator ++(0);};
 564
 565    void operator ++(int)
 566    {
 567       CurItem = CurItem->Next;
 568       while (CurItem == 0 && CurQ != 0)
 569       {
 570          CurItem = CurQ->Items;
 571          CurQ = CurQ->Next;
 572       }
 573    };
 574
 575    inline pkgAcquire::ItemDesc const *operator ->() const {return CurItem;};
 576    inline bool operator !=(UriIterator const &rhs) const {return rhs.CurQ != CurQ || rhs.CurItem != CurItem;};
 577    inline bool operator ==(UriIterator const &rhs) const {return rhs.CurQ == CurQ && rhs.CurItem == CurItem;};
 578
 579    /** \brief Create a new UriIterator.
 580     *
 581     *  \param Q The queue over which this UriIterator should iterate.
 582     */
 583    UriIterator(pkgAcquire::Queue *Q) : CurQ(Q), CurItem(0)
 584    {
 585       while (CurItem == 0 && CurQ != 0)
 586       {
 587          CurItem = CurQ->Items;
 588          CurQ = CurQ->Next;
 589       }
 590    }
 591    virtual ~UriIterator() {};
 592 };
 593                                                                         /*}}}*/
 594 /** \brief Information about the properties of a single acquire method. {{{*/
 595 struct pkgAcquire::MethodConfig
 596 {
 597    /** \brief dpointer placeholder (for later in case we need it) */
 598    void *d;
 599
 600    /** \brief The next link on the acquire method list.
 601     *
 602     *  \todo Why not an STL container?
 603     */
 604    MethodConfig *Next;
 605
 606    /** \brief The name of this acquire method (e.g., http). */
 607    std::string Access;
 608
 609    /** \brief The implementation version of this acquire method. */
 610    std::string Version;
 611
 612    /** \brief If \b true, only one download queue should be created for this
 613     *  method.
 614     */
 615    bool SingleInstance;
 616
 617    /** \brief If \b true, this method supports pipelined downloading. */
 618    bool Pipeline;
 619
 620    /** \brief If \b true, the worker process should send the entire
 621     *  APT configuration tree to the fetch subprocess when it starts
 622     *  up.
 623     */
 624    bool SendConfig;
 625
 626    /** \brief If \b true, this fetch method does not require network access;
 627     *  all files are to be acquired from the local disk.
 628     */
 629    bool LocalOnly;
 630
 631    /** \brief If \b true, the subprocess has to carry out some cleanup
 632     *  actions before shutting down.
 633     *
 634     *  For instance, the cdrom method needs to unmount the CD after it
 635     *  finishes.
 636     */
 637    bool NeedsCleanup;
 638
 639    /** \brief If \b true, this fetch method acquires files from removable media. */
 640    bool Removable;
 641
 642    /** \brief Set up the default method parameters.
 643     *
 644     *  All fields are initialized to NULL, "", or \b false as
 645     *  appropriate.
 646     */
 647    MethodConfig();
 648
 649    /* \brief Destructor, empty currently */
 650    virtual ~MethodConfig() {};
 651 };
 652                                                                         /*}}}*/
 653 /** \brief A monitor object for downloads controlled by the pkgAcquire class.   {{{
 654  *
 655  *  \todo Why protected members?
 656  */
 657 class pkgAcquireStatus
 658 {
 659    /** \brief dpointer placeholder (for later in case we need it) */
 660    void *d;
 661
 662    protected:
 663
 664    /** \brief The last time at which this monitor object was updated. */
 665    struct timeval Time;
 666
 667    /** \brief The time at which the download started. */
 668    struct timeval StartTime;
 669
 670    /** \brief The number of bytes fetched as of the previous call to
 671     *  pkgAcquireStatus::Pulse, including local items.
 672     */
 673    unsigned long long LastBytes;
 674
 675    /** \brief The current rate of download as of the most recent call
 676     *  to pkgAcquireStatus::Pulse, in bytes per second.
 677     */
 678    unsigned long long CurrentCPS;
 679
 680    /** \brief The number of bytes fetched as of the most recent call
 681     *  to pkgAcquireStatus::Pulse, including local items.
 682     */
 683    unsigned long long CurrentBytes;
 684
 685    /** \brief The total number of bytes that need to be fetched.
 686     *
 687     *  \warning This member is inaccurate, as new items might be
 688     *  enqueued while the download is in progress!
 689     */
 690    unsigned long long TotalBytes;
 691
 692    /** \brief The total number of bytes accounted for by items that
 693     *  were successfully fetched.
 694     */
 695    unsigned long long FetchedBytes;
 696
 697    /** \brief The amount of time that has elapsed since the download
 698     *   started.
 699     */
 700    unsigned long long ElapsedTime;
 701
 702    /** \brief The total number of items that need to be fetched.
 703     *
 704     *  \warning This member is inaccurate, as new items might be
 705     *  enqueued while the download is in progress!
 706     */
 707    unsigned long TotalItems;
 708
 709    /** \brief The number of items that have been successfully downloaded. */
 710    unsigned long CurrentItems;
 711
 712    public:
 713
 714    /** \brief If \b true, the download scheduler should call Pulse()
 715     *  at the next available opportunity.
 716     */
 717    bool Update;
 718
 719    /** \brief If \b true, extra Pulse() invocations will be performed.
 720     *
 721     *  With this option set, Pulse() will be called every time that a
 722     *  download item starts downloading, finishes downloading, or
 723     *  terminates with an error.
 724     */
 725    bool MorePulses;
 726
 727    /** \brief Invoked when a local or remote file has been completely fetched.
 728     *
 729     *  \param Size The size of the file fetched.
 730     *
 731     *  \param ResumePoint How much of the file was already fetched.
 732     */
 733    virtual void Fetched(unsigned long long Size,unsigned long long ResumePoint);
 734
 735    /** \brief Invoked when the user should be prompted to change the
 736     *         inserted removable media.
 737     *
 738     *  This method should not return until the user has confirmed to
 739     *  the user interface that the media change is complete.
 740     *
 741     *  \param Media The name of the media type that should be changed.
 742     *
 743     *  \param Drive The identifying name of the drive whose media
 744     *               should be changed.
 745     *
 746     *  \return \b true if the user confirms the media change, \b
 747     *  false if it is cancelled.
 748     *
 749     *  \todo This is a horrible blocking monster; it should be CPSed
 750     *  with prejudice.
 751     */
 752    virtual bool MediaChange(std::string Media,std::string Drive) = 0;
 753
 754    /** \brief Invoked when an item is confirmed to be up-to-date.
 755
 756     * For instance, when an HTTP download is informed that the file on
 757     * the server was not modified.
 758     */
 759    virtual void IMSHit(pkgAcquire::ItemDesc &/*Itm*/) {};
 760
 761    /** \brief Invoked when some of an item's data is fetched. */
 762    virtual void Fetch(pkgAcquire::ItemDesc &/*Itm*/) {};
 763
 764    /** \brief Invoked when an item is successfully and completely fetched. */
 765    virtual void Done(pkgAcquire::ItemDesc &/*Itm*/) {};
 766
 767    /** \brief Invoked when the process of fetching an item encounters
 768     *  a fatal error.
 769     */
 770    virtual void Fail(pkgAcquire::ItemDesc &/*Itm*/) {};
 771
 772    /** \brief Periodically invoked while the Acquire process is underway.
 773     *
 774     *  Subclasses should first call pkgAcquireStatus::Pulse(), then
 775     *  update their status output.  The download process is blocked
 776     *  while Pulse() is being called.
 777     *
 778     *  \return \b false if the user asked to cancel the whole Acquire process.
 779     *
 780     *  \see pkgAcquire::Run
 781     */
 782    virtual bool Pulse(pkgAcquire *Owner);
 783
 784    /** \brief Invoked when the Acquire process starts running. */
 785    virtual void Start();
 786
 787    /** \brief Invoked when the Acquire process stops running. */
 788    virtual void Stop();
 789
 790    /** \brief Initialize all counters to 0 and the time to the current time. */
 791    pkgAcquireStatus();
 792    virtual ~pkgAcquireStatus() {};
 793 };
 794                                                                         /*}}}*/
 795 /** @} */
 796
 797 #endif