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