Browse Source

* merged daniels wonderful doxygen work

Patches applied:

 * dburrows@debian.org--2005/apt--0--base-0
   tag of mvo@debian.org--2005/apt--debian-experimental--0--patch-9

 * dburrows@debian.org--2005/apt--doxygen--0--base-0
   tag of dburrows@debian.org--2005/apt--0--base-0

 * dburrows@debian.org--2005/apt--doxygen--0--patch-1
   Generate Doxygen output in build/doc/doxygen if Doxygen is installed.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-2
   Partially document the acquire item objects.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-3
   Add an 'acquire' group to collect the stuff related to Acquire.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-4
   Don't pick up emacs autosaves when generating the list of doxygen inputs.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-5
   Don't include redundant scope information in the doxygen output.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-6
   Write more general Acquire documentation.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-7
   I don't know why, but stuff just appeared in my tree.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-8
   Write/edit more Acquire documentation.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-9
   Document pkgAcquire::ItemDesc and pkgAcquire::Queue.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-10
   Document UriIterator (left out documentation of the standard iterator operators).

 * dburrows@debian.org--2005/apt--doxygen--0--patch-11
   Give pkgAcquire::Queue a brief description.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-12
   Add a brief description to pkgAcquire::Item.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-13
   Add a brief description to the DiffInfo class.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-14
   Document pkgAcquire::MethodConfig.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-15
   Document pkgAcquireStatus

 * dburrows@debian.org--2005/apt--doxygen--0--patch-16
   Edit the pkgAcquire::Item documentation to be more in line with how Acquire is documented.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-17
   Document pkgAcqDiffIndex.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-18
   Document the Md5Hash parameter to pkgAcquire::Item::Done.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-19
   Fix a spelling error

 * dburrows@debian.org--2005/apt--doxygen--0--patch-20
   Document pkgAcqIndexDiffs and fix up some previously written documentation.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-21
   Mark the brief descriptions in the acquire item documentation.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-22
   Add documentation about the format of the Message parameter to Done&friends.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-23
   Document pkgAcqIndex.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-24
   Document pkgAcqIndexTrans.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-25
   Autogenerate Doxyfile when Doxyfile.in is modified.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-26
   Check for graphviz in configure.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-27
   Fix the detection of dot.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-28
   If dot is detected, use it to build the documentation.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-29
   Argh, pot update.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-30
   Require graphviz when building the Debian packages.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-31
   Document IndexTarget.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-32
   Consistently capitalize the first word following \param.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-33
   Document pkgAcqMetaSig.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-34
   Be a bit clearer about just what a pkgAcquire::Item is.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-35
   Document pkgAcqMetaIndex.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-36
   Document pkgAcqArchive

 * dburrows@debian.org--2005/apt--doxygen--0--patch-37
   Document pkgAcqFile

 * dburrows@debian.org--2005/apt--doxygen--0--patch-38
   Apply patches from mvo

 * dburrows@debian.org--2005/apt--doxygen--0--patch-39
   Update the Doxyfile template.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-40
   Enable BUILTIN_STL_SUPPORT.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-41
   Whoops: \e, not \i, is used to enable italics.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-42
   Editorial changes and clarifications to the documentation in  acquire-item.h

 * dburrows@debian.org--2005/apt--doxygen--0--patch-43
   Clean out the old doxygen output before generating new output.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-44
   Fix setting and using the DOT_PATH doxygen configuration parameter.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-45
   Make the documentation of ��pkgAcquire::MethodConfig::SendConfig somewhat more accurate.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-46
   Partially document pkgAcquire::Worker.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-47
   Finish documenting pkgAcquire::Worker

 * michael.vogt@ubuntu.com--laptop/apt--doxygen--0--base-0
   tag of dburrows@debian.org--2005/apt--doxygen--0--patch-37

 * michael.vogt@ubuntu.com--laptop/apt--doxygen--0--patch-1
   * some documentation updates

 * michael.vogt@ubuntu.com--laptop/apt--doxygen--0--patch-2
   * apt-pkg/acquire-item.h: reviewed and some modifications

 * michael.vogt@ubuntu.com--laptop/apt--doxygen--0--patch-3
   * minor doc update

 * michael.vogt@ubuntu.com--laptop/apt--doxygen--0--patch-4
   * updated after the input from dburrows

 * mvo@debian.org--2005/apt--debian-sid--0--base-0
   tag of michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-71

 * mvo@debian.org--2005/apt--debian-sid--0--patch-1
   * merged with apt--mvo--0

 * mvo@debian.org--2005/apt--debian-sid--0--patch-2
   * merged with apt--mvo

 * mvo@debian.org--2005/apt--debian-sid--0--patch-3
   * updated apt-all.pot

 * mvo@debian.org--2005/apt--debian-sid--0--patch-4
   * merged with apt--mvo

 * mvo@debian.org--2005/apt--debian-sid--0--patch-5
   * merge with apt--mvo--0

 * mvo@debian.org--2005/apt--debian-sid--0--patch-6
   * merge with apt--mvo

 * mvo@debian.org--2005/apt--debian-sid--0--patch-7
   * applied patch from Petr Vandrovec to fix http download corruption

 * mvo@debian.org--2005/apt--debian-sid--0--patch-8
   * merged with apt--mvo, regenerated the po files

 * mvo@debian.org--2005/apt--debian-sid--0--patch-9
   * merged with apt--mvo
debian/1.8.y
Michael Vogt 17 years ago
parent
commit
3174e150a3
  1. 2
      Makefile
  2. 2
      apt-pkg/acquire-item.cc
  3. 666
      apt-pkg/acquire-item.h
  4. 9
      apt-pkg/acquire-method.h
  5. 259
      apt-pkg/acquire-worker.h
  6. 541
      apt-pkg/acquire.h
  7. 2
      buildlib/environment.mak.in
  8. 11
      configure.in
  9. 2
      debian/control
  10. 1238
      doc/Doxyfile.in
  11. 21
      doc/makefile

2
Makefile

@ -26,7 +26,7 @@ maintainer-clean dist-clean distclean pristine sanity: veryclean
# The startup target builds the necessary configure scripts. It should
# be used after a CVS checkout.
CONVERTED=environment.mak include/config.h include/apti18n.h makefile
CONVERTED=environment.mak include/config.h include/apti18n.h build/doc/Doxyfile makefile
include buildlib/configure.mak
$(BUILDDIR)/include/config.h: buildlib/config.h.in
$(BUILDDIR)/include/apti18n.h: buildlib/apti18n.h.in

2
apt-pkg/acquire-item.cc

@ -362,7 +362,7 @@ void pkgAcqIndexDiffs::Failed(string Message,pkgAcquire::MethodConfig *Cnf)
{
if(Debug)
std::clog << "pkgAcqIndexDiffs failed: " << Desc.URI << std::endl
<< "Falling back to normal index file aquire" << std::endl;
<< "Falling back to normal index file acquire" << std::endl;
new pkgAcqIndex(Owner, RealURI, Description,Desc.ShortDesc,
ExpectedMD5);
Finish();

666
apt-pkg/acquire-item.h

@ -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

9
apt-pkg/acquire-method.h

@ -10,6 +10,13 @@
##################################################################### */
/*}}}*/
/** \addtogroup acquire
* @{
*
* \file acquire-method.h
*/
#ifndef PKGLIB_ACQUIRE_METHOD_H
#define PKGLIB_ACQUIRE_METHOD_H
@ -86,4 +93,6 @@ class pkgAcqMethod
virtual ~pkgAcqMethod() {};
};
/** @} */
#endif

259
apt-pkg/acquire-worker.h

@ -9,6 +9,13 @@
##################################################################### */
/*}}}*/
/** \addtogroup acquire
* @{
*
* \file acquire-worker.h
*/
#ifndef PKGLIB_ACQUIRE_WORKER_H
#define PKGLIB_ACQUIRE_WORKER_H
@ -18,7 +25,25 @@
#pragma interface "apt-pkg/acquire-worker.h"
#endif
// Interfacing to the method process
/** \brief A fetch subprocess.
*
* A worker process is responsible for one stage of the fetch. This
* class encapsulates the communications protocol between the master
* process and the worker, from the master end.
*
* Each worker is intrinsically placed on two linked lists. The
* Queue list (maintained in the #NextQueue variable) is maintained
* by the pkgAcquire::Queue class; it represents the set of workers
* assigned to a particular queue. The Acquire list (maintained in
* the #NextAcquire variable) is maintained by the pkgAcquire class;
* it represents the set of active workers for a particular
* pkgAcquire object.
*
* \todo Like everything else in the Acquire system, this has way too
* many protected items.
*
* \sa pkgAcqMethod, pkgAcquire::Item, pkgAcquire
*/
class pkgAcquire::Worker
{
friend class pkgAcquire;
@ -26,64 +51,274 @@ class pkgAcquire::Worker
protected:
friend class Queue;
/* Linked list starting at a Queue and a linked list starting
at Acquire */
/** \brief The next link on the Queue list.
*
* \todo This is always NULL; is it just for future use?
*/
Worker *NextQueue;
/** \brief The next link on the Acquire list. */
Worker *NextAcquire;
// The access association
/** \brief The Queue with which this worker is associated. */
Queue *OwnerQ;
/** \brief The download progress indicator to which progress
* messages should be sent.
*/
pkgAcquireStatus *Log;
/** \brief The configuration of this method. On startup, the
* target of this pointer is filled in with basic data about the
* method, as reported by the worker.
*/
MethodConfig *Config;
/** \brief The access method to be used by this worker.
*
* \todo Doesn't this duplicate Config->Access?
*/
string Access;
// This is the subprocess IPC setup
/** \brief The PID of the subprocess. */
pid_t Process;
/** \brief A file descriptor connected to the standard output of
* the subprocess.
*
* Used to read messages and data from the subprocess.
*/
int InFd;
/** \brief A file descriptor connected to the standard input of the
* subprocess.
*
* Used to send commands and configuration data to the subprocess.
*/
int OutFd;
/** \brief Set to \b true if the worker is in a state in which it
* might generate data or command responses.
*
* \todo Is this right? It's a guess.
*/
bool InReady;
/** \brief Set to \b true if the worker is in a state in which it
* is legal to send commands to it.
*
* \todo Is this right?
*/
bool OutReady;
// Various internal things
/** If \b true, debugging output will be sent to std::clog. */
bool Debug;
/** \brief The raw text values of messages received from the
* worker, in sequence.
*/
vector<string> MessageQueue;
/** \brief Buffers pending writes to the subprocess.
*
* \todo Wouldn't a std::dequeue be more appropriate?
*/
string OutQueue;
// Private constructor helper
/** \brief Common code for the constructor.
*
* Initializes NextQueue and NextAcquire to NULL; Process, InFd,
* and OutFd to -1, OutReady and InReady to \b false, and Debug
* from _config.
*/
void Construct();
// Message handling things
/** \brief Retrieve any available messages from the subprocess.
*
* The messages are retrieved as in ::ReadMessages(), and
* MessageFailure() is invoked if an error occurs; in particular,
* if the pipe to the subprocess dies unexpectedly while a message
* is being read.
*
* \return \b true if the messages were successfully read, \b
* false otherwise.
*/
bool ReadMessages();
/** \brief Parse and dispatch pending messages.
*
* This dispatches the message in a manner appropriate for its
* type.
*
* \todo Several message types lack separate handlers.
*
* \sa Capabilities(), SendConfiguration(), MediaChange()
*/
bool RunMessages();
/** \brief Read and dispatch any pending messages from the
* subprocess.
*
* \return \b false if the subprocess died unexpectedly while a
* message was being transmitted.
*/
bool InFdReady();
/** \brief Send any pending commands to the subprocess.
*
* This method will fail if there is no pending output.
*
* \return \b true if all commands were succeeded, \b false if an
* error occurred (in which case MethodFailure() will be invoked).
*/
bool OutFdReady();
// The message handlers
/** \brief Handle a 100 Capabilities response from the subprocess.
*
* \param Message the raw text of the message from the subprocess.
*
* The message will be parsed and its contents used to fill
* #Config. If #Config is NULL, this routine is a NOP.
*
* \return \b true.
*/
bool Capabilities(string Message);
/** \brief Send a 601 Configuration message (containing the APT
* configuration) to the subprocess.
*
* The APT configuration will be send to the subprocess in a
* message of the following form:
*
* <pre>
* 601 Configuration
* Config-Item: Fully-Qualified-Item=Val
* Config-Item: Fully-Qualified-Item=Val
* ...
* </pre>
*
* \return \b true if the command was successfully sent, \b false
* otherwise.
*/
bool SendConfiguration();
/** \brief Handle a 403 Media Change message.
*
* \param Message the raw text of the message; the Media field
* indicates what type of media should be changed, and the Drive
* field indicates where the media is located.
*
* Invokes pkgAcquireStatus::MediaChange(Media, Drive) to ask the
* user to swap disks; informs the subprocess of the result (via
* 603 Media Changed, with the Failed field set to \b true if the
* user cancelled the media change).
*/
bool MediaChange(string Message);
/** \brief Invoked when the worked process dies unexpectedly.
*
* Waits for the subprocess to terminate and generates an error if
* it terminated abnormally, then closes and blanks out all file
* descriptors. Discards all pending messages from the
* subprocess.
*
* \return \b false.
*/
bool MethodFailure();
/** \brief Invoked when a fetch job is completed, either
* successfully or unsuccessfully.
*
* Resets the status information for the worker process.
*/
void ItemDone();
public:
// The curent method state
/** \brief The queue entry that is currently being downloaded. */
pkgAcquire::Queue::QItem *CurrentItem;
/** \brief The most recent status string received from the
* subprocess.
*/
string Status;
/** \brief How many bytes of the file have been downloaded. Zero
* if the current progress of the file cannot be determined.
*/
unsigned long CurrentSize;
/** \brief The total number of bytes to be downloaded. Zero if the
* total size of the final is unknown.
*/
unsigned long TotalSize;
/** \brief How much of the file was already downloaded prior to
* starting this worker.
*/
unsigned long ResumePoint;
// Load the method and do the startup
/** \brief Tell the subprocess to download the given item.
*
* \param Item the item to queue up.
* \return \b true if the item was successfully enqueued.
*
* Queues up a 600 URI Acquire message for the given item to be
* sent at the next possible moment. Does \e not flush the output
* queue.
*/
bool QueueItem(pkgAcquire::Queue::QItem *Item);
/** \brief Start up the worker and fill in #Config.
*
* Reads the first message from the worker, which is assumed to be
* a 100 Capabilities message.
*
* \return \b true if all operations completed successfully.
*/
bool Start();
/** \brief Update the worker statistics (CurrentSize, TotalSize,
* etc).
*/
void Pulse();
/** \return The fetch method configuration. */
inline const MethodConfig *GetConf() const {return Config;};
/** \brief Create a new Worker to download files.
*
* \param OwnerQ The queue into which this worker should be
* placed.
*
* \param Config A location in which to store information about
* the fetch method.
*
* \param Log The download progress indicator that should be used
* to report the progress of this worker.
*/
Worker(Queue *OwnerQ,MethodConfig *Config,pkgAcquireStatus *Log);
/** \brief Create a new Worker that should just retrieve
* information about the fetch method.
*
* Nothing in particular forces you to refrain from actually
* downloading stuff, but the various status callbacks won't be
* invoked.
*
* \param Config A location in which to store information about
* the fetch method.
*/
Worker(MethodConfig *Config);
/** \brief Clean up this worker.
*
* Closes the file descriptors; if MethodConfig::NeedsCleanup is
* \b false, also rudely interrupts the worker with a SIGINT.
*/
~Worker();
};
/** @} */
#endif

541
apt-pkg/acquire.h

@ -29,6 +29,40 @@
##################################################################### */
/*}}}*/
/** \defgroup acquire Acquire system
*
* \brief The Acquire system is responsible for retrieving files from
* local or remote URIs and postprocessing them (for instance,
* verifying their authenticity). The core class in this system is
* pkgAcquire, which is responsible for managing the download queues
* during the download. There is at least one download queue for
* each supported protocol; protocols such as http may provide one
* queue per host.
*
* Each file to download is represented by a subclass of
* pkgAcquire::Item. The files add themselves to the download
* queue(s) by providing their URI information to
* pkgAcquire::Item::QueueURI, which calls pkgAcquire::Enqueue.
*
* Once the system is set up, the Run method will spawn subprocesses
* to handle the enqueued URIs; the scheduler will then take items
* from the queues and feed them into the handlers until the queues
* are empty.
*
* \todo Acquire supports inserting an object into several queues at
* once, but it is not clear what its behavior in this case is, and
* no subclass of pkgAcquire::Item seems to actually use this
* capability.
*/
/** \addtogroup acquire
*
* @{
*
* \file acquire.h
*/
#ifndef PKGLIB_ACQUIRE_H
#define PKGLIB_ACQUIRE_H
@ -46,6 +80,15 @@ using std::string;
#include <unistd.h>
class pkgAcquireStatus;
/** \brief The core download scheduler.
*
* This class represents an ongoing download. It manages the lists
* of active and pending downloads and handles setting up and tearing
* down download-related structures.
*
* \todo Why all the protected data items and methods?
*/
class pkgAcquire
{
public:
@ -60,97 +103,299 @@ class pkgAcquire
typedef vector<Item *>::iterator ItemIterator;
typedef vector<Item *>::const_iterator ItemCIterator;
protected:
// List of items to fetch
/** \brief A list of items to download.
*
* This is built monotonically as items are created and only
* emptied when the download shuts down.
*/
vector<Item *> Items;
// List of active queues and fetched method configuration parameters
/** \brief The head of the list of active queues.
*
* \todo why a hand-managed list of queues instead of std::list or
* std::set?
*/
Queue *Queues;
/** \brief The head of the list of active workers.
*
* \todo why a hand-managed list of workers instead of std::list
* or std::set?
*/
Worker *Workers;
/** \brief The head of the list of acquire method configurations.
*
* Each protocol (http, ftp, gzip, etc) via which files can be
* fetched can have a representation in this list. The
* configuration data is filled in by parsing the 100 Capabilities
* string output by a method on startup (see
* pkgAcqMethod::pkgAcqMethod and pkgAcquire::GetConfig).
*
* \todo why a hand-managed config dictionary instead of std::map?
*/
MethodConfig *Configs;
/** \brief The progress indicator for this download. */
pkgAcquireStatus *Log;
/** \brief The total size of the files which are to be fetched.
*
* This is not necessarily the total number of bytes to download
* when, e.g., download resumption and list updates via patches
* are taken into account.
*/
unsigned long ToFetch;
// Configurable parameters for the schedular
enum {QueueHost,QueueAccess} QueueMode;
// Configurable parameters for the scheduler
/** \brief Represents the queuing strategy for remote URIs. */
enum QueueStrategy {
/** \brief Generate one queue for each protocol/host combination; downloads from
* multiple hosts can proceed in parallel.
*/
QueueHost,
/** \brief Generate a single queue for each protocol; serialize
* downloads from multiple hosts.
*/
QueueAccess} QueueMode;
/** \brief If \b true, debugging information will be dumped to std::clog. */
bool Debug;
/** \brief If \b true, a download is currently in progress. */
bool Running;
/** \brief Add the given item to the list of items. */
void Add(Item *Item);
/** \brief Remove the given item from the list of items. */
void Remove(Item *Item);
/** \brief Add the given worker to the list of workers. */
void Add(Worker *Work);
/** \brief Remove the given worker from the list of workers. */
void Remove(Worker *Work);
/** \brief Insert the given fetch request into the appropriate queue.
*
* \param Item The URI to download and the item to download it
* for. Copied by value into the queue; no reference to Item is
* retained.
*/
void Enqueue(ItemDesc &Item);
/** \brief Remove all fetch requests for this item from all queues. */
void Dequeue(Item *Item);
/** \brief Determine the fetch method and queue of a URI.
*
* \param URI The URI to fetch.
*
* \param[out] Config A location in which to place the method via
* which the URI is to be fetched.
*
* \return the string-name of the queue in which a fetch request
* for the given URI should be placed.
*/
string QueueName(string URI,MethodConfig const *&Config);
// FDSET managers for derived classes
/** \brief Build up the set of file descriptors upon which select() should
* block.
*
* The default implementation inserts the file descriptors
* corresponding to active downloads.
*
* \param[out] Fd The largest file descriptor in the generated sets.
*
* \param[out] RSet The set of file descriptors that should be
* watched for input.
*
* \param[out] WSet The set of file descriptors that should be
* watched for output.
*/
virtual void SetFds(int &Fd,fd_set *RSet,fd_set *WSet);
/** Handle input from and output to file descriptors which select()
* has determined are ready. The default implementation
* dispatches to all active downloads.
*
* \param RSet The set of file descriptors that are ready for
* input.
*
* \param WSet The set of file descriptors that are ready for
* output.
*/
virtual void RunFds(fd_set *RSet,fd_set *WSet);
// A queue calls this when it dequeues an item
/** \brief Check for idle queues with ready-to-fetch items.
*
* Called by pkgAcquire::Queue::Done each time an item is dequeued
* but remains on some queues; i.e., another queue should start
* fetching it.
*/
void Bump();
public:
/** \brief Retrieve information about a fetch method by name.
*
* \param Access The name of the method to look up.
*
* \return the method whose name is Access, or \b NULL if no such method exists.
*/
MethodConfig *GetConfig(string Access);
enum RunResult {Continue,Failed,Cancelled};
/** \brief Provides information on how a download terminated. */
enum RunResult {
/** \brief All files were fetched successfully. */
Continue,
/** \brief Some files failed to download. */
Failed,
/** \brief The download was cancelled by the user (i.e., #Log's
* pkgAcquireStatus::Pulse() method returned \b false).
*/
Cancelled};
RunResult Run(int PulseIntervall=500000);
/** \brief Download all the items that have been Add()ed to this
* download process.
*
* This method will block until the download completes, invoking
* methods on #Log to report on the progress of the download.
*
* \param PulseInterval The method pkgAcquireStatus::Pulse will be
* invoked on #Log at intervals of PulseInterval milliseconds.
*
* \return the result of the download.
*/
RunResult Run(int PulseInterval=500000);
/** \brief Remove all items from this download process, terminate
* all download workers, and empty all queues.
*/
void Shutdown();
// Simple iteration mechanism
/** \brief Get the first #Worker object.
*
* \return the first active worker in this download process.
*/
inline Worker *WorkersBegin() {return Workers;};
/** \brief Advance to the next #Worker object.
*
* \return the worker immediately following I, or \b NULL if none
* exists.
*/
Worker *WorkerStep(Worker *I);
/** \brief Get the head of the list of items. */
inline ItemIterator ItemsBegin() {return Items.begin();};
/** \brief Get the end iterator of the list of items. */
inline ItemIterator ItemsEnd() {return Items.end();};
// Iterate over queued Item URIs
class UriIterator;
/** \brief Get the head of the list of enqueued item URIs.
*
* This iterator will step over every element of every active
* queue.
*/
UriIterator UriBegin();
/** \brief Get the end iterator of the list of enqueued item URIs. */
UriIterator UriEnd();
// Cleans out the download dir
/** Deletes each entry in the given directory that is not being
* downloaded by this object. For instance, when downloading new
* list files, calling Clean() will delete the old ones.
*
* \param Dir The directory to be cleaned out.
*
* \return \b true if the directory exists and is readable.
*/
bool Clean(string Dir);
// Returns the size of the total download set
/** \return the total size in bytes of all the items included in
* this download.
*/
double TotalNeeded();
/** \return the size in bytes of all non-local items included in
* this download.
*/
double FetchNeeded();
/** \return the amount of data to be fetched that is already
* present on the filesystem.
*/
double PartialPresent();
/** \brief Construct a new pkgAcquire.
*
* \param Log The progress indicator associated with this
* download, or \b NULL for none. This object is not owned by the
* download process and will not be deleted when the pkgAcquire
* object is destroyed. Naturally, it should live for at least as
* long as the pkgAcquire object does.
*/
pkgAcquire(pkgAcquireStatus *Log = 0);
/** \brief Destroy this pkgAcquire object.
*
* Destroys all queue, method, and item objects associated with
* this download.
*/
virtual ~pkgAcquire();
};
// Description of an Item+URI
/** \brief Represents a single download source from which an item
* should be downloaded.
*