27
27
#include <apt-pkg/pkgrecords.h>
28
28
#include <apt-pkg/indexrecords.h>
31
#pragma interface "apt-pkg/acquire-item.h"
31
/** \addtogroup acquire
34
* \file acquire-item.h
37
/** \brief Represents the process by which a pkgAcquire object should
38
* retrieve a file or a collection of files.
40
* By convention, Item subclasses should insert themselves into the
41
* acquire queue when they are created by calling QueueURI(), and
42
* remove themselves by calling Dequeue() when either Done() or
43
* Failed() is invoked. Item objects are also responsible for
44
* notifying the download progress indicator (accessible via
45
* #Owner->Log) of their status.
35
49
class pkgAcquire::Item
39
// Some private helper methods for registering URIs
53
/** \brief The acquire object with which this item is associated. */
56
/** \brief Insert this item into its owner's queue.
58
* \param ItemDesc Metadata about this item (its URI and
41
61
inline void QueueURI(ItemDesc &Item)
42
62
{Owner->Enqueue(Item);};
64
/** \brief Remove this item from its owner's queue. */
43
65
inline void Dequeue() {Owner->Dequeue(this);};
45
// Safe rename function with timestamp preservation
67
/** \brief Rename a file without modifying its timestamp.
69
* Many item methods call this as their final action.
71
* \param From The file to be renamed.
73
* \param To The new name of #From. If #To exists it will be
46
76
void Rename(string From,string To);
51
enum {StatIdle, StatFetching, StatDone, StatError, StatAuthError} Status;
80
/** \brief The current status of this item. */
83
/** \brief The item is waiting to be downloaded. */
86
/** \brief The item is currently being downloaded. */
89
/** \brief The item has been successfully downloaded. */
92
/** \brief An error was encountered while downloading this
97
/** \brief The item was downloaded but its authenticity could
102
/** \brief The item was could not be downloaded because of
103
* a transient network error (e.g. network down)
105
StatTransientNetworkError
108
/** \brief Contains a textual description of the error encountered
109
* if #Status is #StatError or #StatAuthError.
113
/** \brief The size of the object to fetch. */
53
114
unsigned long FileSize;
54
unsigned long PartialSize;
116
/** \brief How much of the object was already fetched. */
117
unsigned long PartialSize;
119
/** \brief If not \b NULL, contains the name of a subprocess that
120
* is operating on this object (for instance, "gzip" or "gpgv").
124
/** \brief A client-supplied unique identifier.
126
* This field is initalized to 0; it is meant to be filled in by
127
* clients that wish to use it to uniquely identify items.
129
* \todo it's unused in apt itself
133
/** \brief If \b true, the entire object has been successfully fetched.
135
* Subclasses should set this to \b true when appropriate.
139
/** \brief If \b true, the URI of this object is "local".
141
* The only effect of this field is to exclude the object from the
142
* download progress indicator's overall statistics.
60
// Number of queues we are inserted into
146
/** \brief The number of fetch queues into which this item has been
149
* There is one queue for each source from which an item could be
61
154
unsigned int QueueCounter;
63
// File to write the fetch into
156
/** \brief The name of the file into which the retrieved object
66
// Action members invoked by the worker
161
/** \brief Invoked by the acquire worker when the object couldn't
164
* This is a branch of the continuation of the fetch process.
166
* \param Message An RFC822-formatted message from the acquire
167
* method describing what went wrong. Use LookupTag() to parse
170
* \param Cnf The method via which the worker tried to fetch this object.
67
174
virtual void Failed(string Message,pkgAcquire::MethodConfig *Cnf);
176
/** \brief Invoked by the acquire worker when the object was
177
* fetched successfully.
179
* Note that the object might \e not have been written to
180
* DestFile; check for the presence of an Alt-Filename entry in
181
* Message to find the file to which it was really written.
183
* Done is often used to switch from one stage of the processing
184
* to the next (e.g. fetching, unpacking, copying). It is one
185
* branch of the continuation of the fetch process.
187
* \param Message Data from the acquire method. Use LookupTag()
189
* \param Size The size of the object that was fetched.
190
* \param Md5Hash The MD5Sum of the object that was fetched.
191
* \param Cnf The method via which the object was fetched.
68
195
virtual void Done(string Message,unsigned long Size,string Md5Hash,
69
196
pkgAcquire::MethodConfig *Cnf);
198
/** \brief Invoked when the worker starts to fetch this object.
200
* \param Message RFC822-formatted data from the worker process.
201
* Use LookupTag() to parse it.
203
* \param Size The size of the object being fetched.
70
207
virtual void Start(string Message,unsigned long Size);
209
/** \brief Custom headers to be sent to the fetch process.
211
* \return a string containing RFC822-style headers that are to be
212
* inserted into the 600 URI Acquire message sent to the fetch
213
* subprocess. The headers are inserted after a newline-less
214
* line, so they should (if nonempty) have a leading newline and
215
* no trailing newline.
71
217
virtual string Custom600Headers() {return string();};
219
/** \brief A "descriptive" URI-like string.
221
* \return a URI that should be used to describe what is being fetched.
72
223
virtual string DescURI() = 0;
224
/** \brief Short item description.
226
* \return a brief description of the object being fetched.
73
228
virtual string ShortDesc() {return DescURI();}
230
/** \brief Invoked by the worker when the download is completely done. */
74
231
virtual void Finished() {};
235
* \return the MD5Sum of this object, if applicable; otherwise, an
77
238
virtual string MD5Sum() {return string();};
240
/** \return the acquire process with which this item is associated. */
78
241
pkgAcquire *GetOwner() {return Owner;};
243
/** \return \b true if this object is being fetched from a trusted source. */
79
244
virtual bool IsTrusted() {return false;};
246
/** \brief Initialize an item.
248
* Adds the item to the list of items known to the acquire
249
* process, but does not place it into any fetch queues (you must
250
* manually invoke QueueURI() to do so).
252
* Initializes all fields of the item other than Owner to 0,
253
* false, or the empty string.
255
* \param Owner The new owner of this item.
81
257
Item(pkgAcquire *Owner);
259
/** \brief Remove this item from its owner's queue by invoking
260
* pkgAcquire::Remove.
85
// item for index diffs
265
/** \brief Information about an index patch (aka diff). */
267
/** The filename of the diff. */
270
/** The sha1 hash of the diff. */
273
/** The size of the diff. */
90
274
unsigned long size;
277
/** \brief An item that is responsible for fetching an index file of
278
* package list diffs and starting the package list's download.
280
* This item downloads the Index file and parses it, then enqueues
281
* additional downloads of either the individual patches (using
282
* pkgAcqIndexDiffs) or the entire Packages file (using pkgAcqIndex).
284
* \sa pkgAcqIndexDiffs, pkgAcqIndex
93
286
class pkgAcqDiffIndex : public pkgAcquire::Item
289
/** \brief If \b true, debugging information will be written to std::clog. */
292
/** \brief The item that is currently being downloaded. */
97
293
pkgAcquire::ItemDesc Desc;
295
/** \brief The URI of the index file to recreate at our end (either
296
* by downloading it or by applying partial patches).
300
/** \brief The MD5Sum that the real index file should have after
301
* all patches have been applied.
99
303
string ExpectedMD5;
305
/** \brief The index file which will be patched to generate the new
100
308
string CurrentPackagesFile;
310
/** \brief A description of the Packages file (stored in
311
* pkgAcquire::ItemDesc::Description).
101
313
string Description;
108
320
virtual string DescURI() {return RealURI + "Index";};
109
321
virtual string Custom600Headers();
323
/** \brief Parse the Index file for a set of Packages diffs.
325
* Parses the Index file and creates additional download items as
328
* \param IndexDiffFile The name of the Index file.
330
* \return \b true if the Index file was successfully parsed, \b
112
333
bool ParseDiffIndex(string IndexDiffFile);
336
/** \brief Create a new pkgAcqDiffIndex.
338
* \param Owner The Acquire object that owns this item.
340
* \param URI The URI of the list file to download.
342
* \param URIDesc A long description of the list file to download.
344
* \param ShortDesc A short description of the list file to download.
346
* \param ExpectedMD5 The list file's MD5 signature.
114
348
pkgAcqDiffIndex(pkgAcquire *Owner,string URI,string URIDesc,
115
string ShortDesct, string ExpectedMD5);
349
string ShortDesc, string ExpectedMD5);
352
/** \brief An item that is responsible for fetching all the patches
353
* that need to be applied to a given package index file.
355
* After downloading and applying a single patch, this item will
356
* enqueue a new pkgAcqIndexDiffs to download and apply the remaining
357
* patches. If no patch can be found that applies to an intermediate
358
* file or if one of the patches cannot be downloaded, falls back to
359
* downloading the entire package index file using pkgAcqIndex.
361
* \sa pkgAcqDiffIndex, pkgAcqIndex
118
363
class pkgAcqIndexDiffs : public pkgAcquire::Item
122
pkgAcquire::ItemDesc Desc;
126
// this is the SHA-1 sum we expect after the patching
128
vector<DiffInfo> available_patches;
129
enum {StateFetchIndex,StateFetchDiff,StateUnzipDiff,StateApplyDiff} State;
133
// Specialized action members
134
virtual void Failed(string Message,pkgAcquire::MethodConfig *Cnf);
135
virtual void Done(string Message,unsigned long Size,string Md5Hash,
136
pkgAcquire::MethodConfig *Cnf);
137
virtual string DescURI() {return RealURI + "Index";};
367
/** \brief Queue up the next diff download.
369
* Search for the next available diff that applies to the file
370
* that currently exists on disk, and enqueue it by calling
373
* \return \b true if an applicable diff was found, \b false
140
376
bool QueueNextDiff();
141
bool ApplyDiff(string PatchFile);
378
/** \brief Handle tasks that must be performed after the item
379
* finishes downloading.
381
* Dequeues the item and checks the resulting file's md5sum
382
* against ExpectedMD5 after the last patch was applied.
383
* There is no need to check the md5/sha1 after a "normal"
384
* patch because QueueNextDiff() will check the sha1 later.
386
* \param allDone If \b true, the file was entirely reconstructed,
387
* and its md5sum is verified.
142
389
void Finish(bool allDone=false);
393
/** \brief If \b true, debugging output will be written to
398
/** \brief A description of the item that is currently being
401
pkgAcquire::ItemDesc Desc;
403
/** \brief The URI of the package index file that is being
408
/** \brief The MD5Sum of the package index file that is being
413
/** A description of the file being downloaded. */
416
/** The patches that remain to be downloaded, including the patch
417
* being downloaded right now. This list should be ordered so
418
* that each diff appears before any diff that depends on it.
420
* \todo These are indexed by sha1sum; why not use some sort of
421
* dictionary instead of relying on ordering and stripping them
424
vector<DiffInfo> available_patches;
425
/** The current status of this patch. */
428
/** \brief The diff is in an unknown state. */
431
/** \brief The diff is currently being fetched. */
434
/** \brief The diff is currently being uncompressed. */
437
/** \brief The diff is currently being applied. */
443
/** \brief Called when the patch file failed to be downloaded.
445
* This method will fall back to downloading the whole index file
446
* outright; its arguments are ignored.
448
virtual void Failed(string Message,pkgAcquire::MethodConfig *Cnf);
450
virtual void Done(string Message,unsigned long Size,string Md5Hash,
451
pkgAcquire::MethodConfig *Cnf);
452
virtual string DescURI() {return RealURI + "Index";};
454
/** \brief Create an index diff item.
456
* After filling in its basic fields, this invokes Finish(true) if
457
* #diffs is empty, or QueueNextDiff() otherwise.
459
* \param Owner The pkgAcquire object that owns this item.
461
* \param URI The URI of the package index file being
464
* \param URIDesc A long description of this item.
466
* \param ShortDesc A brief description of this item.
468
* \param ExpectedMD5 The expected md5sum of the completely
469
* reconstructed package index file; the index file will be tested
470
* against this value when it is entirely reconstructed.
472
* \param diffs The remaining diffs from the index of diffs. They
473
* should be ordered so that each diff appears before any diff
474
* that depends on it.
144
476
pkgAcqIndexDiffs(pkgAcquire *Owner,string URI,string URIDesc,
145
string ShortDesct, string ExpectedMD5,
477
string ShortDesc, string ExpectedMD5,
146
478
vector<DiffInfo> diffs=vector<DiffInfo>());
149
// Item class for index files
481
/** \brief An acquire item that is responsible for fetching an index
482
* file (e.g., Packages or Sources).
484
* \sa pkgAcqDiffIndex, pkgAcqIndexDiffs, pkgAcqIndexTrans
486
* \todo Why does pkgAcqIndex have protected members?
150
488
class pkgAcqIndex : public pkgAcquire::Item
492
/** \brief If \b true, the index file has been decompressed. */
154
493
bool Decompression;
495
/** \brief If \b true, the partially downloaded file will be
496
* removed when the download completes.
500
/** \brief The download request that is currently being
156
503
pkgAcquire::ItemDesc Desc;
505
/** \brief The object that is actually being fetched (minus any
506
* compression-related extensions).
510
/** \brief The expected md5sum of the decompressed index file. */
158
511
string ExpectedMD5;
513
/** \brief The compression-related file extension that is being
514
* added to the downloaded file (e.g., ".gz" or ".bz2").
159
516
string CompressionExtension;
167
524
virtual string Custom600Headers();
168
525
virtual string DescURI() {return RealURI + CompressionExtension;};
527
/** \brief Create a pkgAcqIndex.
529
* \param Owner The pkgAcquire object with which this item is
532
* \param URI The URI of the index file that is to be downloaded.
534
* \param URIDesc A "URI-style" description of this index file.
536
* \param ShortDesc A brief description of this index file.
538
* \param ExpectedMD5 The expected md5sum of this index file.
540
* \param compressExt The compression-related extension with which
541
* this index file should be downloaded, or "" to autodetect
542
* (".bz2" is used if bzip2 is installed, ".gz" otherwise).
170
544
pkgAcqIndex(pkgAcquire *Owner,string URI,string URIDesc,
171
string ShortDesct, string ExpectedMD5, string compressExt="");
545
string ShortDesc, string ExpectedMD5, string compressExt="");
548
/** \brief An acquire item that is responsible for fetching a
549
* translated index file.
551
* The only difference from pkgAcqIndex is that transient failures
552
* are suppressed: no error occurs if the translated index file is
555
class pkgAcqIndexTrans : public pkgAcqIndex
559
virtual void Failed(string Message,pkgAcquire::MethodConfig *Cnf);
561
/** \brief Create a pkgAcqIndexTrans.
563
* \param Owner The pkgAcquire object with which this item is
566
* \param URI The URI of the index file that is to be downloaded.
568
* \param URIDesc A "URI-style" description of this index file.
570
* \param ShortDesc A brief description of this index file.
572
* \param ExpectedMD5 The expected md5sum of this index file.
574
* \param compressExt The compression-related extension with which
575
* this index file should be downloaded, or "" to autodetect
576
* (".bz2" is used if bzip2 is installed, ".gz" otherwise).
578
pkgAcqIndexTrans(pkgAcquire *Owner,string URI,string URIDesc,
582
/** \brief Information about an index file. */
174
583
struct IndexTarget
585
/** \brief A URI from which the index file can be downloaded. */
588
/** \brief A description of the index file. */
177
589
string Description;
591
/** \brief A shorter description of the index file. */
178
592
string ShortDesc;
594
/** \brief The key by which this index file should be
595
* looked up within the meta signature file.
182
// Item class for index signatures
600
/** \brief An acquire item that downloads the detached signature
601
* of a meta-index (Release) file, then queues up the release
604
* \todo Why protected members?
606
* \sa pkgAcqMetaIndex
183
608
class pkgAcqMetaSig : public pkgAcquire::Item
611
/** \brief The fetch request that is currently being processed. */
187
612
pkgAcquire::ItemDesc Desc;
188
string RealURI,MetaIndexURI,MetaIndexURIDesc,MetaIndexShortDesc;
614
/** \brief The URI of the signature file. Unlike Desc.URI, this is
615
* never modified; it is used to determine the file that is being
620
/** \brief The URI of the meta-index file to be fetched after the signature. */
623
/** \brief A "URI-style" description of the meta-index file to be
624
* fetched after the signature.
626
string MetaIndexURIDesc;
628
/** \brief A brief description of the meta-index file to be fetched
629
* after the signature.
631
string MetaIndexShortDesc;
633
/** \brief A package-system-specific parser for the meta-index file. */
189
634
indexRecords* MetaIndexParser;
636
/** \brief The index files which should be looked up in the meta-index
637
* and then downloaded.
639
* \todo Why a list of pointers instead of a list of structs?
190
641
const vector<struct IndexTarget*>* IndexTargets;
198
649
virtual string Custom600Headers();
199
650
virtual string DescURI() {return RealURI; };
652
/** \brief Create a new pkgAcqMetaSig. */
201
653
pkgAcqMetaSig(pkgAcquire *Owner,string URI,string URIDesc, string ShortDesc,
202
654
string MetaIndexURI, string MetaIndexURIDesc, string MetaIndexShortDesc,
203
655
const vector<struct IndexTarget*>* IndexTargets,
204
656
indexRecords* MetaIndexParser);
207
// Item class for index signatures
659
/** \brief An item that is responsible for downloading the meta-index
660
* file (i.e., Release) itself and verifying its signature.
662
* Once the download and verification are complete, the downloads of
663
* the individual index files are queued up using pkgAcqDiffIndex.
664
* If the meta-index file had a valid signature, the expected md5sums
665
* of the index files will be the md5sums listed in the meta-index;
666
* otherwise, the expected md5sums will be "" (causing the
667
* authentication of the index files to be bypassed).
208
669
class pkgAcqMetaIndex : public pkgAcquire::Item
672
/** \brief The fetch command that is currently being processed. */
212
673
pkgAcquire::ItemDesc Desc;
213
string RealURI; // FIXME: is this redundant w/ Desc.URI?
675
/** \brief The URI that is actually being downloaded; never
676
* modified by pkgAcqMetaIndex.
680
/** \brief The file in which the signature for this index was stored.
682
* If empty, the signature and the md5sums of the individual
683
* indices will not be checked.
687
/** \brief The index files to download. */
215
688
const vector<struct IndexTarget*>* IndexTargets;
690
/** \brief The parser for the meta-index file. */
216
691
indexRecords* MetaIndexParser;
693
/** \brief If \b true, the index's signature is currently being verified.
218
696
// required to deal gracefully with problems caused by incorrect ims hits
699
/** \brief Check that the release file is a release file for the
700
* correct distribution.
702
* \return \b true if no fatal errors were encountered.
221
704
bool VerifyVendor(string Message);
706
/** \brief Called when a file is finished being retrieved.
708
* If the file was not downloaded to DestFile, a copy process is
709
* set up to copy it to DestFile; otherwise, Complete is set to \b
710
* true and the file is moved to its final location.
712
* \param Message The message block received from the fetch
222
715
void RetrievalDone(string Message);
717
/** \brief Called when authentication succeeded.
719
* Sanity-checks the authenticated file, queues up the individual
720
* index files for download, and saves the signature in the lists
721
* directory next to the authenticated list file.
723
* \param Message The message block received from the fetch
223
726
void AuthDone(string Message);
728
/** \brief Starts downloading the individual index files.
730
* \param verify If \b true, only indices whose expected md5sum
731
* can be determined from the meta-index will be downloaded, and
732
* the md5sums of indices will be checked (reporting
733
* #StatAuthError if there is a mismatch). If verify is \b false,
734
* no md5sum checking will be performed.
224
736
void QueueIndexes(bool verify);
239
752
indexRecords* MetaIndexParser);
242
// Item class for archive files
755
/** \brief An item that is responsible for fetching a package file.
757
* If the package file already exists in the cache, nothing will be
243
760
class pkgAcqArchive : public pkgAcquire::Item
247
// State information for the retry mechanism
763
/** \brief The package version being fetched. */
248
764
pkgCache::VerIterator Version;
766
/** \brief The fetch command that is currently being processed. */
249
767
pkgAcquire::ItemDesc Desc;
769
/** \brief The list of sources from which to pick archives to
770
* download this package from.
250
772
pkgSourceList *Sources;
774
/** \brief A package records object, used to look up the file
775
* corresponding to each version of the package.
251
777
pkgRecords *Recs;
779
/** \brief The md5sum of this package. */
782
/** \brief A location in which the actual filename of the package
253
785
string &StoreFilename;
787
/** \brief The next file for this version to try to download. */
254
788
pkgCache::VerFileIterator Vf;
790
/** \brief How many (more) times to try to find a new source from
791
* which to download this package version if it fails.
793
* Set from Acquire::Retries.
255
795
unsigned int Retries;
797
/** \brief \b true if this version file is being downloaded from a
258
// Queue the next available file for download.
802
/** \brief Queue up the next available file for this version. */
259
803
bool QueueNext();
263
// Specialized action members
264
807
virtual void Failed(string Message,pkgAcquire::MethodConfig *Cnf);
265
808
virtual void Done(string Message,unsigned long Size,string Md5Hash,
266
809
pkgAcquire::MethodConfig *Cnf);
268
811
virtual string DescURI() {return Desc.URI;};
269
812
virtual string ShortDesc() {return Desc.ShortDesc;};
270
813
virtual void Finished();
271
815
virtual bool IsTrusted();
817
/** \brief Create a new pkgAcqArchive.
819
* \param Owner The pkgAcquire object with which this item is
822
* \param Sources The sources from which to download version
825
* \param Recs A package records object, used to look up the file
826
* corresponding to each version of the package.
828
* \param Version The package version to download.
830
* \param StoreFilename A location in which the actual filename of
831
* the package should be stored. It will be set to a guessed
832
* basename in the constructor, and filled in with a fully
833
* qualified filename once the download finishes.
273
835
pkgAcqArchive(pkgAcquire *Owner,pkgSourceList *Sources,
274
836
pkgRecords *Recs,pkgCache::VerIterator const &Version,
275
837
string &StoreFilename);
278
// Fetch a generic file to the current directory
840
/** \brief Retrieve an arbitrary file to the current directory.
842
* The file is retrieved even if it is accessed via a URL type that
843
* normally is a NOP, such as "file". If the download fails, the
844
* partial file is renamed to get a ".FAILED" extension.
279
846
class pkgAcqFile : public pkgAcquire::Item
848
/** \brief The currently active download process. */
281
849
pkgAcquire::ItemDesc Desc;
851
/** \brief The md5sum of the file to download, if it is known. */
854
/** \brief How many times to retry the download, set from
283
857
unsigned int Retries;
291
865
virtual string MD5Sum() {return Md5Hash;};
292
866
virtual string DescURI() {return Desc.URI;};
294
// If DestFilename is empty, download to DestDir/<basename> if
295
// DestDir is non-empty, $CWD/<basename> otherwise. If
296
// DestFilename is NOT empty, DestDir is ignored and DestFilename
297
// is the absolute name to which the file should be downloaded.
868
/** \brief Create a new pkgAcqFile object.
870
* \param Owner The pkgAcquire object with which this object is
873
* \param URI The URI to download.
875
* \param MD5 The md5sum of the file to download, if it is known;
878
* \param Size The size of the file to download, if it is known;
881
* \param Desc A description of the file being downloaded.
883
* \param ShortDesc A brief description of the file being
886
* \param DestDir The directory the file should be downloaded into.
888
* \param DestFilename The filename+path the file is downloaded to.
891
* If DestFilename is empty, download to DestDir/<basename> if
892
* DestDir is non-empty, $CWD/<basename> otherwise. If
893
* DestFilename is NOT empty, DestDir is ignored and DestFilename
894
* is the absolute name to which the file should be downloaded.
298
897
pkgAcqFile(pkgAcquire *Owner, string URI, string MD5, unsigned long Size,
299
898
string Desc, string ShortDesc,
300
899
const string &DestDir="", const string &DestFilename="");
added
removed
apt-pkg/acquire-item.h
