|
|
@@ -31,73 +31,283 @@
|
|
|
#pragma interface "apt-pkg/acquire-item.h"
|
|
|
#endif
|
|
|
|
|
|
-// Item to acquire
|
|
|
+/** \addtogroup acquire
|
|
|
+ * @{
|
|
|
+ *
|
|
|
+ * \file acquire-item.h
|
|
|
+ */
|
|
|
+
|
|
|
+/** \brief Represents the process by which a pkgAcquire object should
|
|
|
+ * retrieve a file or a collection of files.
|
|
|
+ *
|
|
|
+ * By convention, Item subclasses should insert themselves into the
|
|
|
+ * acquire queue when they are created by calling QueueURI(), and
|
|
|
+ * remove themselves by calling Dequeue() when either Done() or
|
|
|
+ * Failed() is invoked. Item objects are also responsible for
|
|
|
+ * notifying the download progress indicator (accessible via
|
|
|
+ * #Owner->Log) of their status.
|
|
|
+ *
|
|
|
+ * \see pkgAcquire
|
|
|
+ */
|
|
|
class pkgAcquire::Item
|
|
|
{
|
|
|
protected:
|
|
|
|
|
|
- // Some private helper methods for registering URIs
|
|
|
+ /** \brief The acquire object with which this item is associated. */
|
|
|
pkgAcquire *Owner;
|
|
|
+
|
|
|
+ /** \brief Insert this item into its owner's queue.
|
|
|
+ *
|
|
|
+ * \param ItemDesc Metadata about this item (its URI and
|
|
|
+ * description).
|
|
|
+ */
|
|
|
inline void QueueURI(ItemDesc &Item)
|
|
|
{Owner->Enqueue(Item);};
|
|
|
+
|
|
|
+ /** \brief Remove this item from its owner's queue. */
|
|
|
inline void Dequeue() {Owner->Dequeue(this);};
|
|
|
|
|
|
- // Safe rename function with timestamp preservation
|
|
|
+ /** \brief Rename a file without modifying its timestamp.
|
|
|
+ *
|
|
|
+ * Many item methods call this as their final action.
|
|
|
+ *
|
|
|
+ * \param From The file to be renamed.
|
|
|
+ *
|
|
|
+ * \param To The new name of #From. If #To exists it will be
|
|
|
+ * overwritten.
|
|
|
+ */
|
|
|
void Rename(string From,string To);
|
|
|
|
|
|
public:
|
|
|
|
|
|
- // State of the item
|
|
|
- enum {StatIdle, StatFetching, StatDone, StatError, StatAuthError} Status;
|
|
|
+ /** \brief The current status of this item. */
|
|
|
+ enum ItemState
|
|
|
+ {
|
|
|
+ /** \brief The item is waiting to be downloaded. */
|
|
|
+ StatIdle,
|
|
|
+
|
|
|
+ /** \brief The item is currently being downloaded. */
|
|
|
+ StatFetching,
|
|
|
+
|
|
|
+ /** \brief The item has been successfully downloaded. */
|
|
|
+ StatDone,
|
|
|
+
|
|
|
+ /** \brief An error was encountered while downloading this
|
|
|
+ * item.
|
|
|
+ */
|
|
|
+ StatError,
|
|
|
+
|
|
|
+ /** \brief The item was downloaded but its authenticity could
|
|
|
+ * not be verified.
|
|
|
+ */
|
|
|
+ StatAuthError
|
|
|
+ } Status;
|
|
|
+
|
|
|
+ /** \brief Contains a textual description of the error encountered
|
|
|
+ * if #Status is #StatError or #StatAuthError.
|
|
|
+ */
|
|
|
string ErrorText;
|
|
|
+
|
|
|
+ /** \brief The size of the object to fetch. */
|
|
|
unsigned long FileSize;
|
|
|
- unsigned long PartialSize;
|
|
|
+
|
|
|
+ /** \brief How much of the object was already fetched. */
|
|
|
+ unsigned long PartialSize;
|
|
|
+
|
|
|
+ /** \brief If not \b NULL, contains the name of a subprocess that
|
|
|
+ * is operating on this object (for instance, "gzip" or "gpgv").
|
|
|
+ */
|
|
|
const char *Mode;
|
|
|
+
|
|
|
+ /** \brief A client-supplied unique identifier.
|
|
|
+ *
|
|
|
+ * This field is initalized to 0; it is meant to be filled in by
|
|
|
+ * clients that wish to use it to uniquely identify items.
|
|
|
+ *
|
|
|
+ * \todo it's unused in apt itself
|
|
|
+ */
|
|
|
unsigned long ID;
|
|
|
+
|
|
|
+ /** \brief If \b true, the entire object has been successfully fetched.
|
|
|
+ *
|
|
|
+ * Subclasses should set this to \b true when appropriate.
|
|
|
+ */
|
|
|
bool Complete;
|
|
|
+
|
|
|
+ /** \brief If \b true, the URI of this object is "local".
|
|
|
+ *
|
|
|
+ * The only effect of this field is to exclude the object from the
|
|
|
+ * download progress indicator's overall statistics.
|
|
|
+ */
|
|
|
bool Local;
|
|
|
|
|
|
- // Number of queues we are inserted into
|
|
|
+ /** \brief The number of fetch queues into which this item has been
|
|
|
+ * inserted.
|
|
|
+ *
|
|
|
+ * There is one queue for each source from which an item could be
|
|
|
+ * downloaded.
|
|
|
+ *
|
|
|
+ * \sa pkgAcquire
|
|
|
+ */
|
|
|
unsigned int QueueCounter;
|
|
|
|
|
|
- // File to write the fetch into
|
|
|
+ /** \brief The name of the file into which the retrieved object
|
|
|
+ * will be written.
|
|
|
+ */
|
|
|
string DestFile;
|
|
|
|
|
|
- // Action members invoked by the worker
|
|
|
+ /** \brief Invoked by the acquire worker when the object couldn't
|
|
|
+ * be fetched.
|
|
|
+ *
|
|
|
+ * This is a branch of the continuation of the fetch process.
|
|
|
+ *
|
|
|
+ * \param Message An RFC822-formatted message from the acquire
|
|
|
+ * method describing what went wrong. Use LookupTag() to parse
|
|
|
+ * it.
|
|
|
+ *
|
|
|
+ * \param Cnf The method via which the worker tried to fetch this object.
|
|
|
+ *
|
|
|
+ * \sa pkgAcqMethod
|
|
|
+ */
|
|
|
virtual void Failed(string Message,pkgAcquire::MethodConfig *Cnf);
|
|
|
+
|
|
|
+ /** \brief Invoked by the acquire worker when the object was
|
|
|
+ * fetched successfully.
|
|
|
+ *
|
|
|
+ * Note that the object might \e not have been written to
|
|
|
+ * DestFile; check for the presence of an Alt-Filename entry in
|
|
|
+ * Message to find the file to which it was really written.
|
|
|
+ *
|
|
|
+ * Done is often used to switch from one stage of the processing
|
|
|
+ * to the next (e.g. fetching, unpacking, copying). It is one
|
|
|
+ * branch of the continuation of the fetch process.
|
|
|
+ *
|
|
|
+ * \param Message Data from the acquire method. Use LookupTag()
|
|
|
+ * to parse it.
|
|
|
+ * \param Size The size of the object that was fetched.
|
|
|
+ * \param Md5Hash The MD5Sum of the object that was fetched.
|
|
|
+ * \param Cnf The method via which the object was fetched.
|
|
|
+ *
|
|
|
+ * \sa pkgAcqMethod
|
|
|
+ */
|
|
|
virtual void Done(string Message,unsigned long Size,string Md5Hash,
|
|
|
pkgAcquire::MethodConfig *Cnf);
|
|
|
+
|
|
|
+ /** \brief Invoked when the worker starts to fetch this object.
|
|
|
+ *
|
|
|
+ * \param Message RFC822-formatted data from the worker process.
|
|
|
+ * Use LookupTag() to parse it.
|
|
|
+ *
|
|
|
+ * \param Size The size of the object being fetched.
|
|
|
+ *
|
|
|
+ * \sa pkgAcqMethod
|
|
|
+ */
|
|
|
virtual void Start(string Message,unsigned long Size);
|
|
|
+
|
|
|
+ /** \brief Custom headers to be sent to the fetch process.
|
|
|
+ *
|
|
|
+ * \return a string containing RFC822-style headers that are to be
|
|
|
+ * inserted into the 600 URI Acquire message sent to the fetch
|
|
|
+ * subprocess. The headers are inserted after a newline-less
|
|
|
+ * line, so they should (if nonempty) have a leading newline and
|
|
|
+ * no trailing newline.
|
|
|
+ */
|
|
|
virtual string Custom600Headers() {return string();};
|
|
|
+
|
|
|
+ /** \brief A "descriptive" URI-like string.
|
|
|
+ *
|
|
|
+ * \return a URI that should be used to describe what is being fetched.
|
|
|
+ */
|
|
|
virtual string DescURI() = 0;
|
|
|
+ /** \brief Short item description.
|
|
|
+ *
|
|
|
+ * \return a brief description of the object being fetched.
|
|
|
+ */
|
|
|
virtual string ShortDesc() {return DescURI();}
|
|
|
+
|
|
|
+ /** \brief Invoked by the worker when the download is completely done. */
|
|
|
virtual void Finished() {};
|
|
|
|
|
|
- // Inquire functions
|
|
|
+ /** \brief MD5Sum.
|
|
|
+ *
|
|
|
+ * \return the MD5Sum of this object, if applicable; otherwise, an
|
|
|
+ * empty string.
|
|
|
+ */
|
|
|
virtual string MD5Sum() {return string();};
|
|
|
+
|
|
|
+ /** \return the acquire process with which this item is associated. */
|
|
|
pkgAcquire *GetOwner() {return Owner;};
|
|
|
+
|
|
|
+ /** \return \b true if this object is being fetched from a trusted source. */
|
|
|
virtual bool IsTrusted() {return false;};
|
|
|
-
|
|
|
+
|
|
|
+ /** \brief Initialize an item.
|
|
|
+ *
|
|
|
+ * Adds the item to the list of items known to the acquire
|
|
|
+ * process, but does not place it into any fetch queues (you must
|
|
|
+ * manually invoke QueueURI() to do so).
|
|
|
+ *
|
|
|
+ * Initializes all fields of the item other than Owner to 0,
|
|
|
+ * false, or the empty string.
|
|
|
+ *
|
|
|
+ * \param Owner The new owner of this item.
|
|
|
+ */
|
|
|
Item(pkgAcquire *Owner);
|
|
|
+
|
|
|
+ /** \brief Remove this item from its owner's queue by invoking
|
|
|
+ * pkgAcquire::Remove.
|
|
|
+ */
|
|
|
virtual ~Item();
|
|
|
};
|
|
|
|
|
|
-// item for index diffs
|
|
|
-
|
|
|
+/** \brief Information about an index patch (aka diff). */
|
|
|
struct DiffInfo {
|
|
|
+ /** The filename of the diff. */
|
|
|
string file;
|
|
|
+
|
|
|
+ /** The sha1 hash of the diff. */
|
|
|
string sha1;
|
|
|
+
|
|
|
+ /** The size of the diff. */
|
|
|
unsigned long size;
|
|
|
};
|
|
|
|
|
|
+/** \brief An item that is responsible for fetching an index file of
|
|
|
+ * package list diffs and starting the package list's download.
|
|
|
+ *
|
|
|
+ * This item downloads the Index file and parses it, then enqueues
|
|
|
+ * additional downloads of either the individual patches (using
|
|
|
+ * pkgAcqIndexDiffs) or the entire Packages file (using pkgAcqIndex).
|
|
|
+ *
|
|
|
+ * \sa pkgAcqIndexDiffs, pkgAcqIndex
|
|
|
+ */
|
|
|
class pkgAcqDiffIndex : public pkgAcquire::Item
|
|
|
{
|
|
|
protected:
|
|
|
+ /** \brief If \b true, debugging information will be written to std::clog. */
|
|
|
bool Debug;
|
|
|
+
|
|
|
+ /** \brief The item that is currently being downloaded. */
|
|
|
pkgAcquire::ItemDesc Desc;
|
|
|
+
|
|
|
+ /** \brief The URI of the index file to recreate at our end (either
|
|
|
+ * by downloading it or by applying partial patches).
|
|
|
+ */
|
|
|
string RealURI;
|
|
|
+
|
|
|
+ /** \brief The MD5Sum that the real index file should have after
|
|
|
+ * all patches have been applied.
|
|
|
+ */
|
|
|
string ExpectedMD5;
|
|
|
+
|
|
|
+ /** \brief The index file which will be patched to generate the new
|
|
|
+ * file.
|
|
|
+ */
|
|
|
string CurrentPackagesFile;
|
|
|
+
|
|
|
+ /** \brief A description of the Packages file (stored in
|
|
|
+ * pkgAcquire::ItemDesc::Description).
|
|
|
+ */
|
|
|
string Description;
|
|
|
|
|
|
public:
|
|
|
@@ -108,54 +318,199 @@ class pkgAcqDiffIndex : public pkgAcquire::Item
|
|
|
virtual string DescURI() {return RealURI + "Index";};
|
|
|
virtual string Custom600Headers();
|
|
|
|
|
|
- // helpers
|
|
|
+ /** \brief Parse the Index file for a set of Packages diffs.
|
|
|
+ *
|
|
|
+ * Parses the Index file and creates additional download items as
|
|
|
+ * necessary.
|
|
|
+ *
|
|
|
+ * \param IndexDiffFile The name of the Index file.
|
|
|
+ *
|
|
|
+ * \return \b true if the Index file was successfully parsed, \b
|
|
|
+ * false otherwise.
|
|
|
+ */
|
|
|
bool ParseDiffIndex(string IndexDiffFile);
|
|
|
|
|
|
+
|
|
|
+ /** \brief Create a new pkgAcqDiffIndex.
|
|
|
+ *
|
|
|
+ * \param Owner The Acquire object that owns this item.
|
|
|
+ *
|
|
|
+ * \param URI The URI of the list file to download.
|
|
|
+ *
|
|
|
+ * \param URIDesc A long description of the list file to download.
|
|
|
+ *
|
|
|
+ * \param ShortDesc A short description of the list file to download.
|
|
|
+ *
|
|
|
+ * \param ExpectedMD5 The list file's MD5 signature.
|
|
|
+ */
|
|
|
pkgAcqDiffIndex(pkgAcquire *Owner,string URI,string URIDesc,
|
|
|
- string ShortDesct, string ExpectedMD5);
|
|
|
+ string ShortDesc, string ExpectedMD5);
|
|
|
};
|
|
|
|
|
|
+/** \brief An item that is responsible for fetching all the patches
|
|
|
+ * that need to be applied to a given package index file.
|
|
|
+ *
|
|
|
+ * After downloading and applying a single patch, this item will
|
|
|
+ * enqueue a new pkgAcqIndexDiffs to download and apply the remaining
|
|
|
+ * patches. If no patch can be found that applies to an intermediate
|
|
|
+ * file or if one of the patches cannot be downloaded, falls back to
|
|
|
+ * downloading the entire package index file using pkgAcqIndex.
|
|
|
+ *
|
|
|
+ * \sa pkgAcqDiffIndex, pkgAcqIndex
|
|
|
+ */
|
|
|
class pkgAcqIndexDiffs : public pkgAcquire::Item
|
|
|
{
|
|
|
+ private:
|
|
|
+
|
|
|
+ /** \brief Queue up the next diff download.
|
|
|
+ *
|
|
|
+ * Search for the next available diff that applies to the file
|
|
|
+ * that currently exists on disk, and enqueue it by calling
|
|
|
+ * QueueURI().
|
|
|
+ *
|
|
|
+ * \return \b true if an applicable diff was found, \b false
|
|
|
+ * otherwise.
|
|
|
+ */
|
|
|
+ bool QueueNextDiff();
|
|
|
+
|
|
|
+ /** \brief Handle tasks that must be performed after the item
|
|
|
+ * finishes downloading.
|
|
|
+ *
|
|
|
+ * Dequeues the item and checks the resulting file's md5sum
|
|
|
+ * against ExpectedMD5 after the last patch was applied.
|
|
|
+ * There is no need to check the md5/sha1 after a "normal"
|
|
|
+ * patch because QueueNextDiff() will check the sha1 later.
|
|
|
+ *
|
|
|
+ * \param allDone If \b true, the file was entirely reconstructed,
|
|
|
+ * and its md5sum is verified.
|
|
|
+ */
|
|
|
+ void Finish(bool allDone=false);
|
|
|
+
|
|
|
protected:
|
|
|
+
|
|
|
+ /** \brief If \b true, debugging output will be written to
|
|
|
+ * std::clog.
|
|
|
+ */
|
|
|
bool Debug;
|
|
|
+
|
|
|
+ /** \brief A description of the item that is currently being
|
|
|
+ * downloaded.
|
|
|
+ */
|
|
|
pkgAcquire::ItemDesc Desc;
|
|
|
+
|
|
|
+ /** \brief The URI of the package index file that is being
|
|
|
+ * reconstructed.
|
|
|
+ */
|
|
|
string RealURI;
|
|
|
+
|
|
|
+ /** \brief The MD5Sum of the package index file that is being
|
|
|
+ * reconstructed.
|
|
|
+ */
|
|
|
string ExpectedMD5;
|
|
|
|
|
|
- // this is the SHA-1 sum we expect after the patching
|
|
|
+ /** A description of the file being downloaded. */
|
|
|
string Description;
|
|
|
+
|
|
|
+ /** The patches that remain to be downloaded, including the patch
|
|
|
+ * being downloaded right now. This list should be ordered so
|
|
|
+ * that each diff appears before any diff that depends on it.
|
|
|
+ *
|
|
|
+ * \todo These are indexed by sha1sum; why not use some sort of
|
|
|
+ * dictionary instead of relying on ordering and stripping them
|
|
|
+ * off the front?
|
|
|
+ */
|
|
|
vector<DiffInfo> available_patches;
|
|
|
- enum {StateFetchIndex,StateFetchDiff,StateUnzipDiff,StateApplyDiff} State;
|
|
|
+ /** The current status of this patch. */
|
|
|
+ enum DiffState
|
|
|
+ {
|
|
|
+ /** \brief The diff is in an unknown state. */
|
|
|
+ StateFetchUnkown,
|
|
|
+
|
|
|
+ /** \brief The diff is currently being fetched. */
|
|
|
+ StateFetchDiff,
|
|
|
+
|
|
|
+ /** \brief The diff is currently being uncompressed. */
|
|
|
+ StateUnzipDiff,
|
|
|
+
|
|
|
+ /** \brief The diff is currently being applied. */
|
|
|
+ StateApplyDiff
|
|
|
+ } State;
|
|
|
|
|
|
public:
|
|
|
|
|
|
- // Specialized action members
|
|
|
+ /** \brief Called when the patch file failed to be downloaded.
|
|
|
+ *
|
|
|
+ * This method will fall back to downloading the whole index file
|
|
|
+ * outright; its arguments are ignored.
|
|
|
+ */
|
|
|
virtual void Failed(string Message,pkgAcquire::MethodConfig *Cnf);
|
|
|
+
|
|
|
virtual void Done(string Message,unsigned long Size,string Md5Hash,
|
|
|
pkgAcquire::MethodConfig *Cnf);
|
|
|
virtual string DescURI() {return RealURI + "Index";};
|
|
|
|
|
|
- // various helpers
|
|
|
- bool QueueNextDiff();
|
|
|
- bool ApplyDiff(string PatchFile);
|
|
|
- void Finish(bool allDone=false);
|
|
|
-
|
|
|
+ /** \brief Create an index diff item.
|
|
|
+ *
|
|
|
+ * After filling in its basic fields, this invokes Finish(true) if
|
|
|
+ * #diffs is empty, or QueueNextDiff() otherwise.
|
|
|
+ *
|
|
|
+ * \param Owner The pkgAcquire object that owns this item.
|
|
|
+ *
|
|
|
+ * \param URI The URI of the package index file being
|
|
|
+ * reconstructed.
|
|
|
+ *
|
|
|
+ * \param URIDesc A long description of this item.
|
|
|
+ *
|
|
|
+ * \param ShortDesc A brief description of this item.
|
|
|
+ *
|
|
|
+ * \param ExpectedMD5 The expected md5sum of the completely
|
|
|
+ * reconstructed package index file; the index file will be tested
|
|
|
+ * against this value when it is entirely reconstructed.
|
|
|
+ *
|
|
|
+ * \param diffs The remaining diffs from the index of diffs. They
|
|
|
+ * should be ordered so that each diff appears before any diff
|
|
|
+ * that depends on it.
|
|
|
+ */
|
|
|
pkgAcqIndexDiffs(pkgAcquire *Owner,string URI,string URIDesc,
|
|
|
- string ShortDesct, string ExpectedMD5,
|
|
|
+ string ShortDesc, string ExpectedMD5,
|
|
|
vector<DiffInfo> diffs=vector<DiffInfo>());
|
|
|
};
|
|
|
|
|
|
-// Item class for index files
|
|
|
+/** \brief An acquire item that is responsible for fetching an index
|
|
|
+ * file (e.g., Packages or Sources).
|
|
|
+ *
|
|
|
+ * \sa pkgAcqDiffIndex, pkgAcqIndexDiffs, pkgAcqIndexTrans
|
|
|
+ *
|
|
|
+ * \todo Why does pkgAcqIndex have protected members?
|
|
|
+ */
|
|
|
class pkgAcqIndex : public pkgAcquire::Item
|
|
|
{
|
|
|
protected:
|
|
|
-
|
|
|
+
|
|
|
+ /** \brief If \b true, the index file has been decompressed. */
|
|
|
bool Decompression;
|
|
|
+
|
|
|
+ /** \brief If \b true, the partially downloaded file will be
|
|
|
+ * removed when the download completes.
|
|
|
+ */
|
|
|
bool Erase;
|
|
|
+
|
|
|
+ /** \brief The download request that is currently being
|
|
|
+ * processed.
|
|
|
+ */
|
|
|
pkgAcquire::ItemDesc Desc;
|
|
|
+
|
|
|
+ /** \brief The object that is actually being fetched (minus any
|
|
|
+ * compression-related extensions).
|
|
|
+ */
|
|
|
string RealURI;
|
|
|
+
|
|
|
+ /** \brief The expected md5sum of the decompressed index file. */
|
|
|
string ExpectedMD5;
|
|
|
+
|
|
|
+ /** \brief The compression-related file extension that is being
|
|
|
+ * added to the downloaded file (e.g., ".gz" or ".bz2").
|
|
|
+ */
|
|
|
string CompressionExtension;
|
|
|
|
|
|
public:
|
|
|
@@ -167,36 +522,120 @@ class pkgAcqIndex : public pkgAcquire::Item
|
|
|
virtual string Custom600Headers();
|
|
|
virtual string DescURI() {return RealURI + CompressionExtension;};
|
|
|
|
|
|
+ /** \brief Create a pkgAcqIndex.
|
|
|
+ *
|
|
|
+ * \param Owner The pkgAcquire object with which this item is
|
|
|
+ * associated.
|
|
|
+ *
|
|
|
+ * \param URI The URI of the index file that is to be downloaded.
|
|
|
+ *
|
|
|
+ * \param URIDesc A "URI-style" description of this index file.
|
|
|
+ *
|
|
|
+ * \param ShortDesc A brief description of this index file.
|
|
|
+ *
|
|
|
+ * \param ExpectedMD5 The expected md5sum of this index file.
|
|
|
+ *
|
|
|
+ * \param compressExt The compression-related extension with which
|
|
|
+ * this index file should be downloaded, or "" to autodetect
|
|
|
+ * (".bz2" is used if bzip2 is installed, ".gz" otherwise).
|
|
|
+ */
|
|
|
pkgAcqIndex(pkgAcquire *Owner,string URI,string URIDesc,
|
|
|
- string ShortDesct, string ExpectedMD5, string compressExt="");
|
|
|
+ string ShortDesc, string ExpectedMD5, string compressExt="");
|
|
|
};
|
|
|
|
|
|
-// Item class for translated package index files
|
|
|
+/** \brief An acquire item that is responsible for fetching a
|
|
|
+ * translated index file.
|
|
|
+ *
|
|
|
+ * The only difference from pkgAcqIndex is that transient failures
|
|
|
+ * are suppressed: no error occurs if the translated index file is
|
|
|
+ * missing.
|
|
|
+ */
|
|
|
class pkgAcqIndexTrans : public pkgAcqIndex
|
|
|
{
|
|
|
public:
|
|
|
|
|
|
virtual void Failed(string Message,pkgAcquire::MethodConfig *Cnf);
|
|
|
+
|
|
|
+ /** \brief Create a pkgAcqIndexTrans.
|
|
|
+ *
|
|
|
+ * \param Owner The pkgAcquire object with which this item is
|
|
|
+ * associated.
|
|
|
+ *
|
|
|
+ * \param URI The URI of the index file that is to be downloaded.
|
|
|
+ *
|
|
|
+ * \param URIDesc A "URI-style" description of this index file.
|
|
|
+ *
|
|
|
+ * \param ShortDesc A brief description of this index file.
|
|
|
+ *
|
|
|
+ * \param ExpectedMD5 The expected md5sum of this index file.
|
|
|
+ *
|
|
|
+ * \param compressExt The compression-related extension with which
|
|
|
+ * this index file should be downloaded, or "" to autodetect
|
|
|
+ * (".bz2" is used if bzip2 is installed, ".gz" otherwise).
|
|
|
+ */
|
|
|
pkgAcqIndexTrans(pkgAcquire *Owner,string URI,string URIDesc,
|
|
|
- string ShortDesct);
|
|
|
+ string ShortDesc);
|
|
|
};
|
|
|
|
|
|
+/** \brief Information about an index file. */
|
|
|
struct IndexTarget
|
|
|
{
|
|
|
+ /** \brief A URI from which the index file can be downloaded. */
|
|
|
string URI;
|
|
|
+
|
|
|
+ /** \brief A description of the index file. */
|
|
|
string Description;
|
|
|
+
|
|
|
+ /** \brief A shorter description of the index file. */
|
|
|
string ShortDesc;
|
|
|
+
|
|
|
+ /** \brief The key by which this index file should be
|
|
|
+ * looked up within the meta signature file.
|
|
|
+ */
|
|
|
string MetaKey;
|
|
|
};
|
|
|
|
|
|
-// Item class for index signatures
|
|
|
+/** \brief An acquire item that downloads the detached signature
|
|
|
+ * of a meta-index (Release) file, then queues up the release
|
|
|
+ * file itself.
|
|
|
+ *
|
|
|
+ * \todo Why protected members?
|
|
|
+ *
|
|
|
+ * \sa pkgAcqMetaIndex
|
|
|
+ */
|
|
|
class pkgAcqMetaSig : public pkgAcquire::Item
|
|
|
{
|
|
|
protected:
|
|
|
-
|
|
|
+ /** \brief The fetch request that is currently being processed. */
|
|
|
pkgAcquire::ItemDesc Desc;
|
|
|
- string RealURI,MetaIndexURI,MetaIndexURIDesc,MetaIndexShortDesc;
|
|
|
+
|
|
|
+ /** \brief The URI of the signature file. Unlike Desc.URI, this is
|
|
|
+ * never modified; it is used to determine the file that is being
|
|
|
+ * downloaded.
|
|
|
+ */
|
|
|
+ string RealURI;
|
|
|
+
|
|
|
+ /** \brief The URI of the meta-index file to be fetched after the signature. */
|
|
|
+ string MetaIndexURI;
|
|
|
+
|
|
|
+ /** \brief A "URI-style" description of the meta-index file to be
|
|
|
+ * fetched after the signature.
|
|
|
+ */
|
|
|
+ string MetaIndexURIDesc;
|
|
|
+
|
|
|
+ /** \brief A brief description of the meta-index file to be fetched
|
|
|
+ * after the signature.
|
|
|
+ */
|
|
|
+ string MetaIndexShortDesc;
|
|
|
+
|
|
|
+ /** \brief A package-system-specific parser for the meta-index file. */
|
|
|
indexRecords* MetaIndexParser;
|
|
|
+
|
|
|
+ /** \brief The index files which should be looked up in the meta-index
|
|
|
+ * and then downloaded.
|
|
|
+ *
|
|
|
+ * \todo Why a list of pointers instead of a list of structs?
|
|
|
+ */
|
|
|
const vector<struct IndexTarget*>* IndexTargets;
|
|
|
|
|
|
public:
|
|
|
@@ -208,27 +647,88 @@ class pkgAcqMetaSig : public pkgAcquire::Item
|
|
|
virtual string Custom600Headers();
|
|
|
virtual string DescURI() {return RealURI; };
|
|
|
|
|
|
+ /** \brief Create a new pkgAcqMetaSig. */
|
|
|
pkgAcqMetaSig(pkgAcquire *Owner,string URI,string URIDesc, string ShortDesc,
|
|
|
string MetaIndexURI, string MetaIndexURIDesc, string MetaIndexShortDesc,
|
|
|
const vector<struct IndexTarget*>* IndexTargets,
|
|
|
indexRecords* MetaIndexParser);
|
|
|
};
|
|
|
|
|
|
-// Item class for index signatures
|
|
|
+/** \brief An item that is responsible for downloading the meta-index
|
|
|
+ * file (i.e., Release) itself and verifying its signature.
|
|
|
+ *
|
|
|
+ * Once the download and verification are complete, the downloads of
|
|
|
+ * the individual index files are queued up using pkgAcqDiffIndex.
|
|
|
+ * If the meta-index file had a valid signature, the expected md5sums
|
|
|
+ * of the index files will be the md5sums listed in the meta-index;
|
|
|
+ * otherwise, the expected md5sums will be "" (causing the
|
|
|
+ * authentication of the index files to be bypassed).
|
|
|
+ */
|
|
|
class pkgAcqMetaIndex : public pkgAcquire::Item
|
|
|
{
|
|
|
protected:
|
|
|
-
|
|
|
+ /** \brief The fetch command that is currently being processed. */
|
|
|
pkgAcquire::ItemDesc Desc;
|
|
|
- string RealURI; // FIXME: is this redundant w/ Desc.URI?
|
|
|
+
|
|
|
+ /** \brief The URI that is actually being downloaded; never
|
|
|
+ * modified by pkgAcqMetaIndex.
|
|
|
+ */
|
|
|
+ string RealURI;
|
|
|
+
|
|
|
+ /** \brief The file in which the signature for this index was stored.
|
|
|
+ *
|
|
|
+ * If empty, the signature and the md5sums of the individual
|
|
|
+ * indices will not be checked.
|
|
|
+ */
|
|
|
string SigFile;
|
|
|
+
|
|
|
+ /** \brief The index files to download. */
|
|
|
const vector<struct IndexTarget*>* IndexTargets;
|
|
|
+
|
|
|
+ /** \brief The parser for the meta-index file. */
|
|
|
indexRecords* MetaIndexParser;
|
|
|
+
|
|
|
+ /** \brief If \b true, the index's signature is currently being verified.
|
|
|
+ */
|
|
|
bool AuthPass;
|
|
|
|
|
|
+ /** \brief Check that the release file is a release file for the
|
|
|
+ * correct distribution.
|
|
|
+ *
|
|
|
+ * \return \b true if no fatal errors were encountered.
|
|
|
+ */
|
|
|
bool VerifyVendor();
|
|
|
+
|
|
|
+ /** \brief Called when a file is finished being retrieved.
|
|
|
+ *
|
|
|
+ * If the file was not downloaded to DestFile, a copy process is
|
|
|
+ * set up to copy it to DestFile; otherwise, Complete is set to \b
|
|
|
+ * true and the file is moved to its final location.
|
|
|
+ *
|
|
|
+ * \param Message The message block received from the fetch
|
|
|
+ * subprocess.
|
|
|
+ */
|
|
|
void RetrievalDone(string Message);
|
|
|
+
|
|
|
+ /** \brief Called when authentication succeeded.
|
|
|
+ *
|
|
|
+ * Sanity-checks the authenticated file, queues up the individual
|
|
|
+ * index files for download, and saves the signature in the lists
|
|
|
+ * directory next to the authenticated list file.
|
|
|
+ *
|
|
|
+ * \param Message The message block received from the fetch
|
|
|
+ * subprocess.
|
|
|
+ */
|
|
|
void AuthDone(string Message);
|
|
|
+
|
|
|
+ /** \brief Starts downloading the individual index files.
|
|
|
+ *
|
|
|
+ * \param verify If \b true, only indices whose expected md5sum
|
|
|
+ * can be determined from the meta-index will be downloaded, and
|
|
|
+ * the md5sums of indices will be checked (reporting
|
|
|
+ * #StatAuthError if there is a mismatch). If verify is \b false,
|
|
|
+ * no md5sum checking will be performed.
|
|
|
+ */
|
|
|
void QueueIndexes(bool verify);
|
|
|
|
|
|
public:
|
|
|
@@ -240,6 +740,7 @@ class pkgAcqMetaIndex : public pkgAcquire::Item
|
|
|
virtual string Custom600Headers();
|
|
|
virtual string DescURI() {return RealURI; };
|
|
|
|
|
|
+ /** \brief Create a new pkgAcqMetaIndex. */
|
|
|
pkgAcqMetaIndex(pkgAcquire *Owner,
|
|
|
string URI,string URIDesc, string ShortDesc,
|
|
|
string SigFile,
|
|
|
@@ -247,28 +748,58 @@ class pkgAcqMetaIndex : public pkgAcquire::Item
|
|
|
indexRecords* MetaIndexParser);
|
|
|
};
|
|
|
|
|
|
-// Item class for archive files
|
|
|
+/** \brief An item that is responsible for fetching a package file.
|
|
|
+ *
|
|
|
+ * If the package file already exists in the cache, nothing will be
|
|
|
+ * done.
|
|
|
+ */
|
|
|
class pkgAcqArchive : public pkgAcquire::Item
|
|
|
{
|
|
|
protected:
|
|
|
-
|
|
|
- // State information for the retry mechanism
|
|
|
+ /** \brief The package version being fetched. */
|
|
|
pkgCache::VerIterator Version;
|
|
|
+
|
|
|
+ /** \brief The fetch command that is currently being processed. */
|
|
|
pkgAcquire::ItemDesc Desc;
|
|
|
+
|
|
|
+ /** \brief The list of sources from which to pick archives to
|
|
|
+ * download this package from.
|
|
|
+ */
|
|
|
pkgSourceList *Sources;
|
|
|
+
|
|
|
+ /** \brief A package records object, used to look up the file
|
|
|
+ * corresponding to each version of the package.
|
|
|
+ */
|
|
|
pkgRecords *Recs;
|
|
|
+
|
|
|
+ /** \brief The md5sum of this package. */
|
|
|
string MD5;
|
|
|
+
|
|
|
+ /** \brief A location in which the actual filename of the package
|
|
|
+ * should be stored.
|
|
|
+ */
|
|
|
string &StoreFilename;
|
|
|
+
|
|
|
+ /** \brief The next file for this version to try to download. */
|
|
|
pkgCache::VerFileIterator Vf;
|
|
|
+
|
|
|
+ /** \brief How many (more) times to try to find a new source from
|
|
|
+ * which to download this package version if it fails.
|
|
|
+ *
|
|
|
+ * Set from Acquire::Retries.
|
|
|
+ */
|
|
|
unsigned int Retries;
|
|
|
+
|
|
|
+ /** \brief \b true if this version file is being downloaded from a
|
|
|
+ * trusted source.
|
|
|
+ */
|
|
|
bool Trusted;
|
|
|
|
|
|
- // Queue the next available file for download.
|
|
|
+ /** \brief Queue up the next available file for this version. */
|
|
|
bool QueueNext();
|
|
|
|
|
|
public:
|
|
|
|
|
|
- // Specialized action members
|
|
|
virtual void Failed(string Message,pkgAcquire::MethodConfig *Cnf);
|
|
|
virtual void Done(string Message,unsigned long Size,string Md5Hash,
|
|
|
pkgAcquire::MethodConfig *Cnf);
|
|
|
@@ -276,18 +807,49 @@ class pkgAcqArchive : public pkgAcquire::Item
|
|
|
virtual string DescURI() {return Desc.URI;};
|
|
|
virtual string ShortDesc() {return Desc.ShortDesc;};
|
|
|
virtual void Finished();
|
|
|
+
|
|
|
virtual bool IsTrusted();
|
|
|
|
|
|
+ /** \brief Create a new pkgAcqArchive.
|
|
|
+ *
|
|
|
+ * \param Owner The pkgAcquire object with which this item is
|
|
|
+ * associated.
|
|
|
+ *
|
|
|
+ * \param Sources The sources from which to download version
|
|
|
+ * files.
|
|
|
+ *
|
|
|
+ * \param Recs A package records object, used to look up the file
|
|
|
+ * corresponding to each version of the package.
|
|
|
+ *
|
|
|
+ * \param Version The package version to download.
|
|
|
+ *
|
|
|
+ * \param StoreFilename A location in which the actual filename of
|
|
|
+ * the package should be stored. It will be set to a guessed
|
|
|
+ * basename in the constructor, and filled in with a fully
|
|
|
+ * qualified filename once the download finishes.
|
|
|
+ */
|
|
|
pkgAcqArchive(pkgAcquire *Owner,pkgSourceList *Sources,
|
|
|
pkgRecords *Recs,pkgCache::VerIterator const &Version,
|
|
|
string &StoreFilename);
|
|
|
};
|
|
|
|
|
|
-// Fetch a generic file to the current directory
|
|
|
+/** \brief Retrieve an arbitrary file to the current directory.
|
|
|
+ *
|
|
|
+ * The file is retrieved even if it is accessed via a URL type that
|
|
|
+ * normally is a NOP, such as "file". If the download fails, the
|
|
|
+ * partial file is renamed to get a ".FAILED" extension.
|
|
|
+ */
|
|
|
class pkgAcqFile : public pkgAcquire::Item
|
|
|
{
|
|
|
+ /** \brief The currently active download process. */
|
|
|
pkgAcquire::ItemDesc Desc;
|
|
|
+
|
|
|
+ /** \brief The md5sum of the file to download, if it is known. */
|
|
|
string Md5Hash;
|
|
|
+
|
|
|
+ /** \brief How many times to retry the download, set from
|
|
|
+ * Acquire::Retries.
|
|
|
+ */
|
|
|
unsigned int Retries;
|
|
|
|
|
|
public:
|
|
|
@@ -298,9 +860,29 @@ class pkgAcqFile : public pkgAcquire::Item
|
|
|
pkgAcquire::MethodConfig *Cnf);
|
|
|
virtual string MD5Sum() {return Md5Hash;};
|
|
|
virtual string DescURI() {return Desc.URI;};
|
|
|
-
|
|
|
+
|
|
|
+ /** \brief Create a new pkgAcqFile object.
|
|
|
+ *
|
|
|
+ * \param Owner The pkgAcquire object with which this object is
|
|
|
+ * associated.
|
|
|
+ *
|
|
|
+ * \param URI The URI to download.
|
|
|
+ *
|
|
|
+ * \param MD5 The md5sum of the file to download, if it is known;
|
|
|
+ * otherwise "".
|
|
|
+ *
|
|
|
+ * \param Size The size of the file to download, if it is known;
|
|
|
+ * otherwise 0.
|
|
|
+ *
|
|
|
+ * \param Desc A description of the file being downloaded.
|
|
|
+ *
|
|
|
+ * \param ShortDesc A brief description of the file being
|
|
|
+ * downloaded.
|
|
|
+ */
|
|
|
pkgAcqFile(pkgAcquire *Owner,string URI,string MD5,unsigned long Size,
|
|
|
string Desc,string ShortDesc);
|
|
|
};
|
|
|
|
|
|
+/** @} */
|
|
|
+
|
|
|
#endif
|
Michael Vogt