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