apt  2.2.4
About: Apt (Advanced Package Tool) is a management system for software packages (Debian/Ubuntu). Release series 2.2.
  Fossies Dox: apt-2.2.4.tar.gz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

acquire.h
Go to the documentation of this file.
1 // -*- mode: cpp; mode: fold -*-
2 // Description /*{{{*/
3 /* ######################################################################
4 
5  Acquire - File Acquiration
6 
7  This module contains the Acquire system. It is responsible for bringing
8  files into the local pathname space. It deals with URIs for files and
9  URI handlers responsible for downloading or finding the URIs.
10 
11  Each file to download is represented by an Acquire::Item class subclassed
12  into a specialization. The Item class can add itself to several URI
13  acquire queues each prioritized by the download scheduler. When the
14  system is run the proper URI handlers are spawned and the acquire
15  queues are fed into the handlers by the schedular until the queues are
16  empty. This allows for an Item to be downloaded from an alternate source
17  if the first try turns out to fail. It also allows concurrent downloading
18  of multiple items from multiple sources as well as dynamic balancing
19  of load between the sources.
20 
21  Schedualing of downloads is done on a first ask first get basis. This
22  preserves the order of the download as much as possible. And means the
23  fastest source will tend to process the largest number of files.
24 
25  Internal methods and queues for performing gzip decompression,
26  md5sum hashing and file copying are provided to allow items to apply
27  a number of transformations to the data files they are working with.
28 
29  ##################################################################### */
30  /*}}}*/
31 
32 /** \defgroup acquire Acquire system {{{
33  *
34  * \brief The Acquire system is responsible for retrieving files from
35  * local or remote URIs and postprocessing them (for instance,
36  * verifying their authenticity). The core class in this system is
37  * pkgAcquire, which is responsible for managing the download queues
38  * during the download. There is at least one download queue for
39  * each supported protocol; protocols such as http may provide one
40  * queue per host.
41  *
42  * Each file to download is represented by a subclass of
43  * pkgAcquire::Item. The files add themselves to the download
44  * queue(s) by providing their URI information to
45  * pkgAcquire::Item::QueueURI, which calls pkgAcquire::Enqueue.
46  *
47  * Once the system is set up, the Run method will spawn subprocesses
48  * to handle the enqueued URIs; the scheduler will then take items
49  * from the queues and feed them into the handlers until the queues
50  * are empty.
51  *
52  * \todo Acquire supports inserting an object into several queues at
53  * once, but it is not clear what its behavior in this case is, and
54  * no subclass of pkgAcquire::Item seems to actually use this
55  * capability.
56  */ /*}}}*/
57 
58 /** \addtogroup acquire
59  *
60  * @{
61  *
62  * \file acquire.h
63  */
64 
65 #ifndef PKGLIB_ACQUIRE_H
66 #define PKGLIB_ACQUIRE_H
67 
68 #include <apt-pkg/hashes.h>
69 #include <apt-pkg/macros.h>
70 #include <apt-pkg/weakptr.h>
71 
72 #include <string>
73 #include <vector>
74 
75 #include <stddef.h>
76 #include <sys/select.h>
77 #include <sys/time.h>
78 
79 
80 
81 class pkgAcquireStatus;
82 class metaIndex;
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  */
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 * const 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 pkgAcqMetaBase;
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. */
159  /** \brief Generate one queue for each protocol/host combination; downloads from
160  * multiple hosts can proceed in parallel.
161  */
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  * \return false if there is an error condition on one of the fds
235  */
236  virtual bool RunFds(fd_set *RSet,fd_set *WSet);
237 
238  /** \brief Check for idle queues with ready-to-fetch items.
239  *
240  * Called by pkgAcquire::Queue::Done each time an item is dequeued
241  * but remains on some queues; i.e., another queue should start
242  * fetching it.
243  */
244  void Bump();
245 
246  public:
247 
248  /** \brief Retrieve information about a fetch method by name.
249  *
250  * \param Access The name of the method to look up.
251  *
252  * \return the method whose name is Access, or \b NULL if no such method exists.
253  */
254  MethodConfig *GetConfig(std::string Access);
255 
256  /** \brief Provides information on how a download terminated. */
257  enum RunResult {
258  /** \brief All files were fetched successfully. */
260 
261  /** \brief Some files failed to download. */
263 
264  /** \brief The download was cancelled by the user (i.e., #Log's
265  * pkgAcquireStatus::Pulse() method returned \b false).
266  */
267  Cancelled};
268 
269  /** \brief Download all the items that have been Add()ed to this
270  * download process.
271  *
272  * This method will block until the download completes, invoking
273  * methods on #Log to report on the progress of the download.
274  *
275  * \param PulseInterval The method pkgAcquireStatus::Pulse will be
276  * invoked on #Log at intervals of PulseInterval milliseconds.
277  *
278  * \return the result of the download.
279  */
280  RunResult Run(int PulseInterval=500000);
281 
282  /** \brief Remove all items from this download process, terminate
283  * all download workers, and empty all queues.
284  */
285  void Shutdown();
286 
287  /** \brief Get the first Worker object.
288  *
289  * \return the first active worker in this download process.
290  */
291  inline Worker *WorkersBegin() {return Workers;};
292 
293  /** \brief Advance to the next Worker object.
294  *
295  * \return the worker immediately following I, or \b NULL if none
296  * exists.
297  */
298  Worker *WorkerStep(Worker *I) APT_PURE;
299 
300  /** \brief Get the head of the list of items. */
301  inline ItemIterator ItemsBegin() {return Items.begin();};
302  inline ItemCIterator ItemsBegin() const {return Items.begin();};
303 
304  /** \brief Get the end iterator of the list of items. */
305  inline ItemIterator ItemsEnd() {return Items.end();};
306  inline ItemCIterator ItemsEnd() const {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(std::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  void SetLog(pkgAcquireStatus *Progress) { Log = Progress; }
345 
346  /** \brief acquire lock and perform directory setup
347  *
348  * \param Lock defines a lock file that should be acquired to ensure
349  * only one Acquire class is in action at the time or an empty string
350  * if no lock file should be used. If set also all needed directories
351  * will be created and setup.
352  */
353  bool GetLock(std::string const &Lock);
354 
355  /** \brief Construct a new pkgAcquire. */
356  explicit pkgAcquire(pkgAcquireStatus *Log);
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  APT_HIDDEN static std::string URIEncode(std::string const &part);
367 
368  private:
369  APT_HIDDEN void Initialize();
370 };
371 
372 /** \brief Represents a single download source from which an item
373  * should be downloaded.
374  *
375  * An item may have several associated ItemDescs over its lifetime.
376  */
377 struct APT_PUBLIC pkgAcquire::ItemDesc : public WeakPointable
378 {
379  /** \brief URI from which to download this item. */
380  std::string URI;
381  /** \brief description of this item. */
382  std::string Description;
383  /** \brief shorter description of this item. */
384  std::string ShortDesc;
385  /** \brief underlying item which is to be downloaded. */
386  Item *Owner;
387 };
388  /*}}}*/
389 /** \brief A single download queue in a pkgAcquire object. {{{
390  *
391  * \todo Why so many protected values?
392  */
393 class APT_PUBLIC pkgAcquire::Queue
394 {
395  friend class pkgAcquire;
397  friend class pkgAcquire::Worker;
398 
399  /** \brief dpointer placeholder (for later in case we need it) */
400  void * const d;
401 
402  /** \brief The next queue in the pkgAcquire object's list of queues. */
404 
405  protected:
406 
407  /** \brief A single item placed in this queue. */
408  struct QItem : public ItemDesc
409  {
410  /** \brief The next item in the queue. */
412  /** \brief The worker associated with this item, if any. */
414 
415  /** \brief The underlying items interested in the download */
416  std::vector<Item*> Owners;
417 
418  /** \brief How many bytes of the file have been downloaded. Zero
419  * if the current progress of the file cannot be determined.
420  */
421  unsigned long long CurrentSize = 0;
422 
423  /** \brief The total number of bytes to be downloaded. Zero if the
424  * total size of the final is unknown.
425  */
426  unsigned long long TotalSize = 0;
427 
428  /** \brief How much of the file was already downloaded prior to
429  * starting this worker.
430  */
431  unsigned long long ResumePoint = 0;
432 
433  typedef std::vector<Item*>::const_iterator owner_iterator;
434 
435  /** \brief Assign the ItemDesc portion of this QItem from
436  * another ItemDesc
437  */
438  void operator =(pkgAcquire::ItemDesc const &I)
439  {
440  URI = I.URI;
441  Description = I.Description;
442  ShortDesc = I.ShortDesc;
443  Owners.clear();
444  Owners.push_back(I.Owner);
445  Owner = I.Owner;
446  };
447 
448  /** @return the sum of all expected hashes by all owners */
450 
451  /** @return smallest maximum size of all owners */
452  unsigned long long GetMaximumSize() const;
453 
454  /** \brief get partial files in order */
455  void SyncDestinationFiles() const;
456 
457  /** @return the custom headers to use for this item */
458  std::string Custom600Headers() const;
459  /** @return the maximum priority of this item */
460  int APT_HIDDEN GetPriority() const;
461  };
462 
463  /** \brief The name of this queue. */
464  std::string Name;
465 
466  /** \brief The head of the list of items contained in this queue.
467  *
468  * \todo why a by-hand list instead of an STL structure?
469  */
471 
472  /** \brief The head of the list of workers associated with this queue.
473  *
474  * \todo This is plural because support exists in Queue for
475  * multiple workers. However, it does not appear that there is
476  * any way to actually associate more than one worker with a
477  * queue.
478  *
479  * \todo Why not just use a std::set?
480  */
482 
483  /** \brief the download scheduler with which this queue is associated. */
485 
486  /** \brief The number of entries in this queue that are currently
487  * being downloaded.
488  */
489  signed long PipeDepth;
490 
491  /** \brief The maximum number of entries that this queue will
492  * attempt to download at once.
493  */
494  unsigned long MaxPipeDepth;
495 
496  public:
497 
498  /** \brief Insert the given fetch request into this queue.
499  *
500  * \return \b true if the queuing was successful. May return
501  * \b false if the Item is already in the queue
502  */
503  bool Enqueue(ItemDesc &Item);
504 
505  /** \brief Remove all fetch requests for the given item from this queue.
506  *
507  * \return \b true if at least one request was removed from the queue.
508  */
509  bool Dequeue(Item *Owner);
510 
511  /** \brief Locate an item in this queue.
512  *
513  * \param URI A URI to match against.
514  * \param Owner A pkgAcquire::Worker to match against.
515  *
516  * \return the first item in the queue whose URI is #URI and that
517  * is being downloaded by #Owner.
518  */
520 
521  /** Presumably this should start downloading an item?
522  *
523  * \todo Unimplemented. Implement it or remove?
524  */
525  bool ItemStart(QItem *Itm,unsigned long long Size);
526 
527  /** \brief Remove the given item from this queue and set its state
528  * to pkgAcquire::Item::StatDone.
529  *
530  * If this is the only queue containing the item, the item is also
531  * removed from the main queue by calling pkgAcquire::Dequeue.
532  *
533  * \param Itm The item to remove.
534  *
535  * \return \b true if no errors are encountered.
536  */
537  bool ItemDone(QItem *Itm);
538 
539  /** \brief Start the worker process associated with this queue.
540  *
541  * If a worker process is already associated with this queue,
542  * this is equivalent to calling Cycle().
543  *
544  * \return \b true if the startup was successful.
545  */
546  bool Startup();
547 
548  /** \brief Shut down the worker process associated with this queue.
549  *
550  * \param Final If \b true, then the process is stopped unconditionally.
551  * Otherwise, it is only stopped if it does not need cleanup
552  * as indicated by the pkgAcqMethod::NeedsCleanup member of
553  * its configuration.
554  *
555  * \return \b true.
556  */
557  bool Shutdown(bool Final);
558 
559  /** \brief Send idle items to the worker process.
560  *
561  * Fills up the pipeline by inserting idle items into the worker's queue.
562  */
563  bool Cycle();
564 
565  /** \brief Check for items that could be enqueued.
566  *
567  * Call this after an item placed in multiple queues has gone from
568  * the pkgAcquire::Item::StatFetching state to the
569  * pkgAcquire::Item::StatIdle state, to possibly refill an empty queue.
570  * This is an alias for Cycle().
571  *
572  * \todo Why both this and Cycle()? Are they expected to be
573  * different someday?
574  */
575  void Bump();
576 
577  /** \brief Create a new Queue.
578  *
579  * \param Name The name of the new queue.
580  * \param Owner The download process that owns the new queue.
581  */
582  Queue(std::string const &Name,pkgAcquire * const Owner);
583 
584  /** Shut down all the worker processes associated with this queue
585  * and empty the queue.
586  */
587  virtual ~Queue();
588 };
589  /*}}}*/
590 /** \brief Iterates over all the URIs being fetched by a pkgAcquire object. {{{*/
591 class APT_PUBLIC pkgAcquire::UriIterator
592 {
593  /** \brief dpointer placeholder (for later in case we need it) */
594  void * const d;
595 
596  /** The next queue to iterate over. */
598  /** The item that we currently point at. */
599  pkgAcquire::Queue::QItem *CurItem;
600 
601  public:
602 
603  inline void operator ++() {operator ++(0);};
604 
605  void operator ++(int)
606  {
607  CurItem = CurItem->Next;
608  while (CurItem == 0 && CurQ != 0)
609  {
610  CurItem = CurQ->Items;
611  CurQ = CurQ->Next;
612  }
613  };
614 
615  inline pkgAcquire::Queue::QItem const *operator ->() const {return CurItem;};
616  inline bool operator !=(UriIterator const &rhs) const {return rhs.CurQ != CurQ || rhs.CurItem != CurItem;};
617  inline bool operator ==(UriIterator const &rhs) const {return rhs.CurQ == CurQ && rhs.CurItem == CurItem;};
618 
619  /** \brief Create a new UriIterator.
620  *
621  * \param Q The queue over which this UriIterator should iterate.
622  */
624  virtual ~UriIterator();
625 };
626  /*}}}*/
627 /** \brief Information about the properties of a single acquire method. {{{*/
628 struct APT_PUBLIC pkgAcquire::MethodConfig
629 {
630  class Private;
631  /** \brief dpointer placeholder (for later in case we need it) */
632  Private *const d;
633 
634  /** \brief The next link on the acquire method list.
635  *
636  * \todo Why not an STL container?
637  */
638  MethodConfig *Next;
639 
640  /** \brief The name of this acquire method (e.g., http). */
641  std::string Access;
642 
643  /** \brief The implementation version of this acquire method. */
644  std::string Version;
645 
646  /** \brief If \b true, only one download queue should be created for this
647  * method.
648  */
650 
651  /** \brief If \b true, this method supports pipelined downloading. */
652  bool Pipeline;
653 
654  /** \brief If \b true, the worker process should send the entire
655  * APT configuration tree to the fetch subprocess when it starts
656  * up.
657  */
659 
660  /** \brief If \b true, this fetch method does not require network access;
661  * all files are to be acquired from the local disk.
662  */
663  bool LocalOnly;
664 
665  /** \brief If \b true, the subprocess has to carry out some cleanup
666  * actions before shutting down.
667  *
668  * For instance, the cdrom method needs to unmount the CD after it
669  * finishes.
670  */
672 
673  /** \brief If \b true, this fetch method acquires files from removable media. */
674  bool Removable;
675 
676  /** \brief Set up the default method parameters.
677  *
678  * All fields are initialized to NULL, "", or \b false as
679  * appropriate.
680  */
682 
684  APT_HIDDEN void SetAuxRequests(bool const value);
686  APT_HIDDEN void SetSendURIEncoded(bool const value);
687 
688  virtual ~MethodConfig();
689 };
690  /*}}}*/
691 /** \brief A monitor object for downloads controlled by the pkgAcquire class. {{{
692  *
693  * \todo Why protected members?
694  */
696 {
697  /** \brief dpointer placeholder (for later in case we need it) */
698  void * const d;
699 
700  protected:
701 
702  /** \brief The last time at which this monitor object was updated. */
703  struct timeval Time;
704 
705  /** \brief The time at which the download started. */
706  struct timeval StartTime;
707 
708  /** \brief The number of bytes fetched as of the previous call to
709  * pkgAcquireStatus::Pulse, including local items.
710  */
711  unsigned long long LastBytes;
712 
713  /** \brief The current rate of download as of the most recent call
714  * to pkgAcquireStatus::Pulse, in bytes per second.
715  */
716  unsigned long long CurrentCPS;
717 
718  /** \brief The number of bytes fetched as of the most recent call
719  * to pkgAcquireStatus::Pulse, including local items.
720  */
721  unsigned long long CurrentBytes;
722 
723  /** \brief The total number of bytes that need to be fetched.
724  *
725  * \warning This member is inaccurate, as new items might be
726  * enqueued while the download is in progress!
727  */
728  unsigned long long TotalBytes;
729 
730  /** \brief The total number of bytes accounted for by items that
731  * were successfully fetched.
732  */
733  unsigned long long FetchedBytes;
734 
735  /** \brief The amount of time that has elapsed since the download
736  * started.
737  */
738  unsigned long long ElapsedTime;
739 
740  /** \brief The total number of items that need to be fetched.
741  *
742  * \warning This member is inaccurate, as new items might be
743  * enqueued while the download is in progress!
744  */
745  unsigned long TotalItems;
746 
747  /** \brief The number of items that have been successfully downloaded. */
748  unsigned long CurrentItems;
749 
750  /** \brief The estimated percentage of the download (0-100)
751  */
752  double Percent;
753 
754  public:
755 
756  /** \brief If \b true, the download scheduler should call Pulse()
757  * at the next available opportunity.
758  */
759  bool Update;
760 
761  /** \brief If \b true, extra Pulse() invocations will be performed.
762  *
763  * With this option set, Pulse() will be called every time that a
764  * download item starts downloading, finishes downloading, or
765  * terminates with an error.
766  */
768 
769  /** \brief Invoked when a local or remote file has been completely fetched.
770  *
771  * \param Size The size of the file fetched.
772  *
773  * \param ResumePoint How much of the file was already fetched.
774  */
775  virtual void Fetched(unsigned long long Size,unsigned long long ResumePoint);
776 
777  /** \brief Invoked when the user should be prompted to change the
778  * inserted removable media.
779  *
780  * This method should not return until the user has confirmed to
781  * the user interface that the media change is complete.
782  *
783  * \param Media The name of the media type that should be changed.
784  *
785  * \param Drive The identifying name of the drive whose media
786  * should be changed.
787  *
788  * \return \b true if the user confirms the media change, \b
789  * false if it is cancelled.
790  *
791  * \todo This is a horrible blocking monster; it should be CPSed
792  * with prejudice.
793  */
794  virtual bool MediaChange(std::string Media,std::string Drive) = 0;
795 
797  {
798  std::string Type; /*!< Type of the change like "Origin", "Codename", "Version", … */
799  std::string From; /*!< old value */
800  std::string To; /*!< new value */
801  std::string Message; /*!< translated message describing the change */
802  bool DefaultAction; /*!< true if the change is informational, false if it must be explicitly confirmed */
803  };
804  /** \brief ask the user for confirmation of changes to infos about a repository
805  *
806  * This method should present the user with a choice of accepting the change
807  * or not and indicate the user opinion via the return value. If DefaultAction is true
808  * it is acceptable to only notify the user about the change, but to accept the change
809  * automatically on behalf of the user.
810  *
811  * The default implementation will fail if any Change has DefaultAction == false. Regardless of
812  * success it will print for each change the message attached to it via GlobalError either as an
813  * error (if DefaultAction == false) or as a notice otherwise.
814  *
815  * @param LastRelease can be used to extract further information from the previous Release file
816  * @param CurrentRelease can be used to extract further information from the current Release file
817  * @param Changes is an array of changes alongside explanatory messages
818  * which should be presented in some way to the user.
819  * @return \b true if all changes are accepted by user, otherwise or if user can't be asked \b false
820  */
821  virtual bool ReleaseInfoChanges(metaIndex const * const LastRelease, metaIndex const * const CurrentRelease, std::vector<ReleaseInfoChange> &&Changes);
822  APT_HIDDEN static bool ReleaseInfoChangesAsGlobalErrors(std::vector<ReleaseInfoChange> &&Changes);
823 
824  /** \brief Invoked when an item is confirmed to be up-to-date.
825 
826  * For instance, when an HTTP download is informed that the file on
827  * the server was not modified.
828  */
829  virtual void IMSHit(pkgAcquire::ItemDesc &/*Itm*/) {};
830 
831  /** \brief Invoked when some of an item's data is fetched. */
832  virtual void Fetch(pkgAcquire::ItemDesc &/*Itm*/) {};
833 
834  /** \brief Invoked when an item is successfully and completely fetched. */
835  virtual void Done(pkgAcquire::ItemDesc &/*Itm*/) {};
836 
837  /** \brief Invoked when the process of fetching an item encounters
838  * a fatal error.
839  */
840  virtual void Fail(pkgAcquire::ItemDesc &/*Itm*/) {};
841 
842  /** \brief Periodically invoked while the Acquire process is underway.
843  *
844  * Subclasses should first call pkgAcquireStatus::Pulse(), then
845  * update their status output. The download process is blocked
846  * while Pulse() is being called.
847  *
848  * \return \b false if the user asked to cancel the whole Acquire process.
849  *
850  * \see pkgAcquire::Run
851  */
852  virtual bool Pulse(pkgAcquire *Owner);
853 
854  /** \brief Invoked when the Acquire process starts running. */
855  virtual void Start();
856 
857  /** \brief Invoked when the Acquire process stops running. */
858  virtual void Stop();
859 
860  /** \brief Initialize all counters to 0 and the time to the current time. */
862  virtual ~~pkgAcquireStatus();
863 };
864  /*}}}*/
865 /** @} */
866 
867 #endif
static bool std::string const metaIndex const *const pkgAcqMetaClearSig *const pkgAcquire::Item *const I
static bool Clean(CommandLine &CmdL)
static bool operator!=(LineBuffer const &buf, APT::StringView const exp) noexcept
Definition: gpgv.cc:108
static bool operator==(LineBuffer const &buf, APT::StringView const exp) noexcept
Definition: gpgv.cc:104
Definition: strutl.h:193
std::string URI
Definition: metaindex.h:39
the manager of a transaction
Definition: acquire-item.h:404
A monitor object for downloads controlled by the pkgAcquire class. {{{.
Definition: acquire.h:696
virtual void IMSHit(pkgAcquire::ItemDesc &)
Invoked when an item is confirmed to be up-to-date.
Definition: acquire.h:829
unsigned long long ElapsedTime
The amount of time that has elapsed since the download started.
Definition: acquire.h:738
double Percent
The estimated percentage of the download (0-100)
Definition: acquire.h:752
virtual void Fail(pkgAcquire::ItemDesc &)
Invoked when the process of fetching an item encounters a fatal error.
Definition: acquire.h:840
virtual void Done(pkgAcquire::ItemDesc &)
Invoked when an item is successfully and completely fetched.
Definition: acquire.h:835
virtual bool MediaChange(std::string Media, std::string Drive)=0
Invoked when the user should be prompted to change the inserted removable media.
virtual void Fetch(pkgAcquire::ItemDesc &)
Invoked when some of an item's data is fetched.
Definition: acquire.h:832
unsigned long long FetchedBytes
The total number of bytes accounted for by items that were successfully fetched.
Definition: acquire.h:733
bool Update
If true, the download scheduler should call Pulse() at the next available opportunity.
Definition: acquire.h:759
unsigned long long CurrentBytes
The number of bytes fetched as of the most recent call to pkgAcquireStatus::Pulse,...
Definition: acquire.h:721
bool MorePulses
If true, extra Pulse() invocations will be performed.
Definition: acquire.h:767
unsigned long CurrentItems
The number of items that have been successfully downloaded.
Definition: acquire.h:748
unsigned long long TotalBytes
The total number of bytes that need to be fetched.
Definition: acquire.h:728
unsigned long long CurrentCPS
The current rate of download as of the most recent call to pkgAcquireStatus::Pulse,...
Definition: acquire.h:716
unsigned long long LastBytes
The number of bytes fetched as of the previous call to pkgAcquireStatus::Pulse, including local items...
Definition: acquire.h:711
void *const d
dpointer placeholder (for later in case we need it)
Definition: acquire.h:698
unsigned long TotalItems
The total number of items that need to be fetched.
Definition: acquire.h:745
Represents the process by which a pkgAcquire object should retrieve a file or a collection of files.
Definition: acquire-item.h:59
bool Shutdown(bool Final)
Shut down the worker process associated with this queue.
ItemIterator ItemsEnd()
Get the end iterator of the list of items.
Definition: acquire.h:305
friend class Queue
Worker * WorkersBegin()
Get the first Worker object.
Definition: acquire.h:291
bool Pipeline
If true, this method supports pipelined downloading.
Definition: acquire.h:652
bool NeedsCleanup
If true, the subprocess has to carry out some cleanup actions before shutting down.
Definition: acquire.h:671
Queue * Next
The next queue in the pkgAcquire object's list of queues.
Definition: acquire.h:403
bool const Debug
If true, debugging information will be dumped to std::clog.
Definition: acquire.h:169
MethodConfig()
Set up the default method parameters.
pkgAcquire::Queue::QItem * CurItem
Definition: acquire.h:599
bool Enqueue(ItemDesc &Item)
Insert the given fetch request into this queue.
QItem * Items
The head of the list of items contained in this queue.
Definition: acquire.h:470
APT_HIDDEN bool GetAuxRequests() const
pkgAcquire::Queue * CurQ
Definition: acquire.h:597
bool Cycle()
Send idle items to the worker process.
virtual ~UriIterator()
bool ItemDone(QItem *Itm)
Remove the given item from this queue and set its state to pkgAcquire::Item::StatDone.
std::string Description
description of this item.
Definition: acquire.h:382
bool SingleInstance
If true, only one download queue should be created for this method.
Definition: acquire.h:649
bool ItemStart(QItem *Itm, unsigned long long Size)
pkgAcquire * Owner
the download scheduler with which this queue is associated.
Definition: acquire.h:484
std::vector< Item * > Items
A list of items to download.
Definition: acquire.h:121
std::vector< Item * >::const_iterator ItemCIterator
Definition: acquire.h:112
bool Removable
If true, this fetch method acquires files from removable media.
Definition: acquire.h:674
bool Dequeue(Item *Owner)
Remove all fetch requests for the given item from this queue.
ItemCIterator ItemsBegin() const
Definition: acquire.h:302
bool LocalOnly
If true, this fetch method does not require network access; all files are to be acquired from the loc...
Definition: acquire.h:663
QItem * FindItem(std::string URI, pkgAcquire::Worker *Owner) APT_PURE
Locate an item in this queue.
std::string Version
The implementation version of this acquire method.
Definition: acquire.h:644
signed long PipeDepth
The number of entries in this queue that are currently being downloaded.
Definition: acquire.h:489
std::string ShortDesc
shorter description of this item.
Definition: acquire.h:384
Private *const d
dpointer placeholder (for later in case we need it)
Definition: acquire-item.h:357
int LockFD
FD of the Lock file we acquire in Setup (if any)
Definition: acquire.h:96
Queue(std::string const &Name, pkgAcquire *const Owner)
Create a new Queue.
Item * Owner
underlying item which is to be downloaded.
Definition: acquire.h:386
Queue * Queues
The head of the list of active queues.
Definition: acquire.h:128
void SetLog(pkgAcquireStatus *Progress)
Definition: acquire.h:344
ItemCIterator ItemsEnd() const
Definition: acquire.h:306
std::string URI
URI from which to download this item.
Definition: acquire.h:380
MethodConfig * Configs
The head of the list of acquire method configurations.
Definition: acquire.h:147
bool Startup()
Start the worker process associated with this queue.
virtual ~Queue()
virtual ~MethodConfig()
unsigned long ToFetch
The number of files which are to be fetched.
Definition: acquire.h:153
void Bump()
Check for items that could be enqueued.
Worker(Queue *OwnerQ, MethodConfig *Config, pkgAcquireStatus *Log)
Create a new Worker to download files.
APT_HIDDEN void SetAuxRequests(bool const value)
APT_HIDDEN void SetSendURIEncoded(bool const value)
RunResult
Provides information on how a download terminated.
Definition: acquire.h:257
@ Failed
Some files failed to download.
Definition: acquire.h:262
@ Continue
All files were fetched successfully.
Definition: acquire.h:259
std::vector< Item * >::iterator ItemIterator
Definition: acquire.h:111
UriIterator(pkgAcquire::Queue *Q)
Create a new UriIterator.
std::string Name
The name of this queue.
Definition: acquire.h:464
MethodConfig * Next
The next link on the acquire method list.
Definition: acquire.h:638
Worker * Workers
The head of the list of active workers.
Definition: acquire.h:135
bool Running
If true, a download is currently in progress.
Definition: acquire.h:171
pkgAcquire::Worker * Workers
The head of the list of workers associated with this queue.
Definition: acquire.h:481
bool SendConfig
If true, the worker process should send the entire APT configuration tree to the fetch subprocess whe...
Definition: acquire.h:658
QueueStrategy
Represents the queuing strategy for remote URIs.
Definition: acquire.h:158
@ QueueHost
Generate one queue for each protocol/host combination; downloads from multiple hosts can proceed in p...
Definition: acquire.h:162
ItemIterator ItemsBegin()
Get the head of the list of items.
Definition: acquire.h:301
APT_HIDDEN bool GetSendURIEncoded() const
unsigned long MaxPipeDepth
The maximum number of entries that this queue will attempt to download at once.
Definition: acquire.h:494
int GetLock(string File, bool Errors)
Definition: fileutl.cc:243
#define APT_PURE
Definition: macros.h:56
#define APT_PUBLIC
Definition: macros.h:77
#define APT_HIDDEN
Definition: macros.h:78
A single item placed in this queue.
Definition: acquire.h:409
int APT_HIDDEN GetPriority() const
unsigned long long GetMaximumSize() const
HashStringList GetExpectedHashes() const
void SyncDestinationFiles() const
get partial files in order
QItem * Next
The next item in the queue.
Definition: acquire.h:411
pkgAcquire::Worker * Worker
The worker associated with this item, if any.
Definition: acquire.h:413
std::vector< Item * >::const_iterator owner_iterator
Definition: acquire.h:433
std::vector< Item * > Owners
The underlying items interested in the download.
Definition: acquire.h:416
std::string Custom600Headers() const