You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

807 lines
25 KiB

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