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