apt-pkg/acquire-item.h

   1 // -*- mode: cpp; mode: fold -*-
   2 // Description                                                          /*{{{*/
   3 // $Id: acquire-item.h,v 1.26.2.3 2004/01/02 18:51:00 mdz Exp $
   4 /* ######################################################################
   5
   6    Acquire Item - Item to acquire
   7
   8    When an item is instantiated it will add it self to the local list in
   9    the Owner Acquire class. Derived classes will then call QueueURI to
  10    register all the URI's they wish to fetch at the initial moment.
  11
  12    Three item classes are provided to provide functionality for
  13    downloading of Index, Translation and Packages files.
  14
  15    A Archive class is provided for downloading .deb files. It does Hash
  16    checking and source location as well as a retry algorithm.
  17
  18    ##################################################################### */
  19                                                                         /*}}}*/
  20 #ifndef PKGLIB_ACQUIRE_ITEM_H
  21 #define PKGLIB_ACQUIRE_ITEM_H
  22
  23 #include <apt-pkg/acquire.h>
  24 #include <apt-pkg/hashes.h>
  25 #include <apt-pkg/weakptr.h>
  26 #include <apt-pkg/pkgcache.h>
  27 #include <apt-pkg/cacheiterators.h>
  28
  29 #include <string>
  30 #include <vector>
  31
  32 #ifndef APT_8_CLEANER_HEADERS
  33 #include <apt-pkg/indexfile.h>
  34 #include <apt-pkg/vendor.h>
  35 #include <apt-pkg/sourcelist.h>
  36 #include <apt-pkg/pkgrecords.h>
  37 #include <apt-pkg/indexrecords.h>
  38 #endif
  39
  40 /** \addtogroup acquire
  41  *  @{
  42  *
  43  *  \file acquire-item.h
  44  */
  45
  46 class indexRecords;
  47 class pkgRecords;
  48 class pkgSourceList;
  49 class IndexTarget;
  50 class pkgAcqMetaBase;
  51
  52 /** \brief Represents the process by which a pkgAcquire object should   {{{
  53  *  retrieve a file or a collection of files.
  54  *
  55  *  By convention, Item subclasses should insert themselves into the
  56  *  acquire queue when they are created by calling QueueURI(), and
  57  *  remove themselves by calling Dequeue() when either Done() or
  58  *  Failed() is invoked.  Item objects are also responsible for
  59  *  notifying the download progress indicator (accessible via
  60  *  #Owner->Log) of their status.
  61  *
  62  *  \see pkgAcquire
  63  */
  64 class pkgAcquire::Item : public WeakPointable
  65 {
  66    void *d;
  67
  68    protected:
  69
  70    /** \brief The acquire object with which this item is associated. */
  71    pkgAcquire *Owner;
  72
  73    /** \brief Insert this item into its owner's queue.
  74     *
  75     *  \param Item Metadata about this item (its URI and
  76     *  description).
  77     */
  78    inline void QueueURI(ItemDesc &Item)
  79                  {Owner->Enqueue(Item);};
  80
  81    /** \brief Remove this item from its owner's queue. */
  82    inline void Dequeue() {Owner->Dequeue(this);};
  83
  84    /** \brief Rename a file without modifying its timestamp.
  85     *
  86     *  Many item methods call this as their final action.
  87     *
  88     *  \param From The file to be renamed.
  89     *
  90     *  \param To The new name of \a From.  If \a To exists it will be
  91     *  overwritten.
  92     */
  93    bool Rename(std::string From,std::string To);
  94
  95    public:
  96
  97    /** \brief The current status of this item. */
  98    enum ItemState
  99      {
 100        /** \brief The item is waiting to be downloaded. */
 101        StatIdle,
 102
 103        /** \brief The item is currently being downloaded. */
 104        StatFetching,
 105
 106        /** \brief The item has been successfully downloaded. */
 107        StatDone,
 108
 109        /** \brief An error was encountered while downloading this
 110         *  item.
 111         */
 112        StatError,
 113
 114        /** \brief The item was downloaded but its authenticity could
 115         *  not be verified.
 116         */
 117        StatAuthError,
 118
 119        /** \brief The item was could not be downloaded because of
 120         *  a transient network error (e.g. network down)
 121         */
 122        StatTransientNetworkError,
 123      } Status;
 124
 125    /** \brief Contains a textual description of the error encountered
 126     *  if #ItemState is #StatError or #StatAuthError.
 127     */
 128    std::string ErrorText;
 129
 130    /** \brief The size of the object to fetch. */
 131    unsigned long long FileSize;
 132
 133    /** \brief How much of the object was already fetched. */
 134    unsigned long long PartialSize;
 135
 136    /** \brief If not \b NULL, contains the name of a subprocess that
 137     *  is operating on this object (for instance, "gzip" or "gpgv").
 138     */
 139    const char *Mode;
 140
 141    /** \brief A client-supplied unique identifier.
 142     *
 143     *  This field is initalized to 0; it is meant to be filled in by
 144     *  clients that wish to use it to uniquely identify items.
 145     *
 146     *  \todo it's unused in apt itself
 147     */
 148    unsigned long ID;
 149
 150    /** \brief If \b true, the entire object has been successfully fetched.
 151     *
 152     *  Subclasses should set this to \b true when appropriate.
 153     */
 154    bool Complete;
 155
 156    /** \brief If \b true, the URI of this object is "local".
 157     *
 158     *  The only effect of this field is to exclude the object from the
 159     *  download progress indicator's overall statistics.
 160     */
 161    bool Local;
 162    std::string UsedMirror;
 163
 164    /** \brief The number of fetch queues into which this item has been
 165     *  inserted.
 166     *
 167     *  There is one queue for each source from which an item could be
 168     *  downloaded.
 169     *
 170     *  \sa pkgAcquire
 171     */
 172    unsigned int QueueCounter;
 173
 174    /** \brief TransactionManager */
 175    pkgAcqMetaBase *TransactionManager;
 176
 177    /** \brief The number of additional fetch items that are expected
 178     *  once this item is done.
 179     *
 180     *  Some items like pkgAcqMeta{Index,Sig} will queue additional
 181     *  items. This variable can be set by the methods if it knows
 182     *  in advance how many items to expect to get a more accurate
 183     *  progress.
 184     */
 185    unsigned int ExpectedAdditionalItems;
 186
 187    /** \brief The name of the file into which the retrieved object
 188     *  will be written.
 189     */
 190    std::string DestFile;
 191
 192    /** \brief storge name until a transaction is finished */
 193    std::string PartialFile;
 194
 195    /** \brief Invoked by the acquire worker when the object couldn't
 196     *  be fetched.
 197     *
 198     *  This is a branch of the continuation of the fetch process.
 199     *
 200     *  \param Message An RFC822-formatted message from the acquire
 201     *  method describing what went wrong.  Use LookupTag() to parse
 202     *  it.
 203     *
 204     *  \param Cnf The method via which the worker tried to fetch this object.
 205     *
 206     *  \sa pkgAcqMethod
 207     */
 208    virtual void Failed(std::string Message,pkgAcquire::MethodConfig *Cnf);
 209
 210    /** \brief Invoked by the acquire worker when the object was
 211     *  fetched successfully.
 212     *
 213     *  Note that the object might \e not have been written to
 214     *  DestFile; check for the presence of an Alt-Filename entry in
 215     *  Message to find the file to which it was really written.
 216     *
 217     *  Done is often used to switch from one stage of the processing
 218     *  to the next (e.g. fetching, unpacking, copying).  It is one
 219     *  branch of the continuation of the fetch process.
 220     *
 221     *  \param Message Data from the acquire method.  Use LookupTag()
 222     *  to parse it.
 223     *  \param Size The size of the object that was fetched.
 224     *  \param Hashes The HashSums of the object that was fetched.
 225     *  \param Cnf The method via which the object was fetched.
 226     *
 227     *  \sa pkgAcqMethod
 228     */
 229    virtual void Done(std::string Message, unsigned long long Size, HashStringList const &Hashes,
 230                      pkgAcquire::MethodConfig *Cnf);
 231
 232    /** \brief Invoked when the worker starts to fetch this object.
 233     *
 234     *  \param Message RFC822-formatted data from the worker process.
 235     *  Use LookupTag() to parse it.
 236     *
 237     *  \param Size The size of the object being fetched.
 238     *
 239     *  \sa pkgAcqMethod
 240     */
 241    virtual void Start(std::string Message,unsigned long long Size);
 242
 243    /** \brief Custom headers to be sent to the fetch process.
 244     *
 245     *  \return a string containing RFC822-style headers that are to be
 246     *  inserted into the 600 URI Acquire message sent to the fetch
 247     *  subprocess.  The headers are inserted after a newline-less
 248     *  line, so they should (if nonempty) have a leading newline and
 249     *  no trailing newline.
 250     */
 251    virtual std::string Custom600Headers() const {return std::string();};
 252
 253    /** \brief A "descriptive" URI-like string.
 254     *
 255     *  \return a URI that should be used to describe what is being fetched.
 256     */
 257    virtual std::string DescURI() const = 0;
 258    /** \brief Short item description.
 259     *
 260     *  \return a brief description of the object being fetched.
 261     */
 262    virtual std::string ShortDesc() const {return DescURI();}
 263
 264    /** \brief Invoked by the worker when the download is completely done. */
 265    virtual void Finished() {};
 266
 267    /** \brief HashSums
 268     *
 269     *  \return the HashSums of this object, if applicable; otherwise, an
 270     *  empty list.
 271     */
 272    HashStringList HashSums() const {return ExpectedHashes;};
 273    std::string HashSum() const {HashStringList const hashes = HashSums(); HashString const * const hs = hashes.find(NULL); return hs != NULL ? hs->toStr() : ""; };
 274
 275    /** \return the acquire process with which this item is associated. */
 276    pkgAcquire *GetOwner() const {return Owner;};
 277
 278    /** \return \b true if this object is being fetched from a trusted source. */
 279    virtual bool IsTrusted() const {return false;};
 280
 281    // report mirror problems
 282    /** \brief Report mirror problem
 283     *
 284     *  This allows reporting mirror failures back to a centralized
 285     *  server. The apt-report-mirror-failure script is called for this
 286     *
 287     *  \param FailCode A short failure string that is send
 288     */
 289    void ReportMirrorFailure(std::string FailCode);
 290
 291
 292    /** \brief Initialize an item.
 293     *
 294     *  Adds the item to the list of items known to the acquire
 295     *  process, but does not place it into any fetch queues (you must
 296     *  manually invoke QueueURI() to do so).
 297     *
 298     *  \param Owner The new owner of this item.
 299     *  \param ExpectedHashes of the file represented by this item
 300     */
 301    Item(pkgAcquire *Owner,
 302         HashStringList const &ExpectedHashes=HashStringList(),
 303         pkgAcqMetaBase *TransactionManager=NULL);
 304
 305    /** \brief Remove this item from its owner's queue by invoking
 306     *  pkgAcquire::Remove.
 307     */
 308    virtual ~Item();
 309
 310    protected:
 311
 312    enum RenameOnErrorState {
 313       HashSumMismatch,
 314       SizeMismatch,
 315       InvalidFormat,
 316       SignatureError,
 317       NotClearsigned,
 318    };
 319
 320    /** \brief Rename failed file and set error
 321     *
 322     * \param state respresenting the error we encountered
 323     */
 324    bool RenameOnError(RenameOnErrorState const state);
 325
 326    /** \brief The HashSums of the item is supposed to have than done */
 327    HashStringList ExpectedHashes;
 328
 329    /** \brief The item that is currently being downloaded. */
 330    pkgAcquire::ItemDesc Desc;
 331 };
 332                                                                         /*}}}*/
 333 /** \brief Information about an index patch (aka diff). */              /*{{{*/
 334 struct DiffInfo {
 335    /** The filename of the diff. */
 336    std::string file;
 337
 338    /** The sha1 hash of the diff. */
 339    std::string sha1;
 340
 341    /** The size of the diff. */
 342    unsigned long size;
 343 };
 344                                                                         /*}}}*/
 345                                                                         /*}}}*/
 346
 347 class pkgAcqMetaBase  : public pkgAcquire::Item
 348 {
 349    void *d;
 350
 351  protected:
 352    std::vector<Item*> Transaction;
 353
 354  public:
 355    // transaction code
 356    void Add(Item *I);
 357    void AbortTransaction();
 358    bool TransactionHasError() APT_PURE;
 359    void CommitTransaction();
 360
 361    // helper for the signature warning
 362    bool GenerateAuthWarning(const std::string &RealURI,
 363                             const std::string &Message);
 364
 365
 366    pkgAcqMetaBase(pkgAcquire *Owner,
 367                   HashStringList const &ExpectedHashes=HashStringList(),
 368                   pkgAcqMetaBase *TransactionManager=NULL)
 369       : Item(Owner, ExpectedHashes, TransactionManager) {};
 370 };
 371
 372 /** \brief An acquire item that downloads the detached signature        {{{
 373  *  of a meta-index (Release) file, then queues up the release
 374  *  file itself.
 375  *
 376  *  \todo Why protected members?
 377  *
 378  *  \sa pkgAcqMetaIndex
 379  */
 380 class pkgAcqMetaSig : public pkgAcqMetaBase
 381 {
 382    void *d;
 383
 384    protected:
 385
 386    /** \brief The URI of the signature file.  Unlike Desc.URI, this is
 387     *  never modified; it is used to determine the file that is being
 388     *  downloaded.
 389     */
 390    std::string RealURI;
 391
 392    std::string URIDesc;
 393    std::string ShortDesc;
 394
 395    /** \brief A package-system-specific parser for the meta-index file. */
 396    indexRecords* MetaIndexParser;
 397
 398    /** \brief The file we need to verify */
 399    std::string MetaIndexFile;
 400
 401    /** \brief The index files which should be looked up in the meta-index
 402     *  and then downloaded.
 403     *
 404     *  \todo Why a list of pointers instead of a list of structs?
 405     */
 406    const std::vector<IndexTarget*>* IndexTargets;
 407
 408    /** \brief If we are in fetching or download state */
 409    bool AuthPass;
 410
 411    /** \brief Was this file already on disk */
 412    bool IMSHit;
 413
 414    public:
 415
 416    // Specialized action members
 417    virtual void Failed(std::string Message,pkgAcquire::MethodConfig *Cnf);
 418    virtual void Done(std::string Message,unsigned long long Size, HashStringList const &Hashes,
 419                      pkgAcquire::MethodConfig *Cnf);
 420    virtual std::string Custom600Headers() const;
 421    virtual std::string DescURI() const {return RealURI; };
 422
 423    /** \brief Create a new pkgAcqMetaSig. */
 424    pkgAcqMetaSig(pkgAcquire *Owner,
 425                  pkgAcqMetaBase *TransactionManager,
 426                  std::string URI,std::string URIDesc, std::string ShortDesc,
 427                  std::string MetaIndexFile,
 428                  const std::vector<IndexTarget*>* IndexTargets,
 429                  indexRecords* MetaIndexParser);
 430    virtual ~pkgAcqMetaSig();
 431 };
 432                                                                         /*}}}*/
 433
 434 /** \brief An item that is responsible for downloading the meta-index   {{{
 435  *  file (i.e., Release) itself and verifying its signature.
 436  *
 437  *  Once the download and verification are complete, the downloads of
 438  *  the individual index files are queued up using pkgAcqDiffIndex.
 439  *  If the meta-index file had a valid signature, the expected hashsums
 440  *  of the index files will be the md5sums listed in the meta-index;
 441  *  otherwise, the expected hashsums will be "" (causing the
 442  *  authentication of the index files to be bypassed).
 443  */
 444 class pkgAcqMetaIndex : public pkgAcqMetaBase
 445 {
 446    void *d;
 447
 448    protected:
 449    /** \brief The URI that is actually being downloaded; never
 450     *  modified by pkgAcqMetaIndex.
 451     */
 452    std::string RealURI;
 453
 454    /** \brief The file in which the signature for this index was stored.
 455     *
 456     *  If empty, the signature and the md5sums of the individual
 457     *  indices will not be checked.
 458     */
 459    std::string SigFile;
 460
 461    /** \brief The index files to download. */
 462    const std::vector<IndexTarget*>* IndexTargets;
 463
 464    /** \brief The parser for the meta-index file. */
 465    indexRecords* MetaIndexParser;
 466
 467    /** \brief If \b true, the index's signature is currently being verified.
 468     */
 469    bool AuthPass;
 470    // required to deal gracefully with problems caused by incorrect ims hits
 471    bool IMSHit;
 472
 473    /** \brief Check that the release file is a release file for the
 474     *  correct distribution.
 475     *
 476     *  \return \b true if no fatal errors were encountered.
 477     */
 478    bool VerifyVendor(std::string Message);
 479
 480    /** \brief Called when a file is finished being retrieved.
 481     *
 482     *  If the file was not downloaded to DestFile, a copy process is
 483     *  set up to copy it to DestFile; otherwise, Complete is set to \b
 484     *  true and the file is moved to its final location.
 485     *
 486     *  \param Message The message block received from the fetch
 487     *  subprocess.
 488     */
 489    void RetrievalDone(std::string Message);
 490
 491    /** \brief Called when authentication succeeded.
 492     *
 493     *  Sanity-checks the authenticated file, queues up the individual
 494     *  index files for download, and saves the signature in the lists
 495     *  directory next to the authenticated list file.
 496     *
 497     *  \param Message The message block received from the fetch
 498     *  subprocess.
 499     */
 500    void AuthDone(std::string Message);
 501
 502    std::string URIDesc;
 503    std::string ShortDesc;
 504
 505    /** \brief The URI of the meta-index file for the detached signature */
 506    std::string MetaIndexSigURI;
 507
 508    /** \brief A "URI-style" description of the meta-index file */
 509    std::string MetaIndexSigURIDesc;
 510
 511    /** \brief A brief description of the meta-index file */
 512    std::string MetaIndexSigShortDesc;
 513
 514    /** \brief delayed constructor */
 515    void Init(std::string URIDesc, std::string ShortDesc);
 516
 517    public:
 518
 519    /** \brief Starts downloading the individual index files.
 520     *
 521     *  \param verify If \b true, only indices whose expected hashsum
 522     *  can be determined from the meta-index will be downloaded, and
 523     *  the hashsums of indices will be checked (reporting
 524     *  #StatAuthError if there is a mismatch).  If verify is \b false,
 525     *  no hashsum checking will be performed.
 526     */
 527    void QueueIndexes(bool verify);
 528
 529    // Specialized action members
 530    virtual void Failed(std::string Message,pkgAcquire::MethodConfig *Cnf);
 531    virtual void Done(std::string Message,unsigned long long Size, HashStringList const &Hashes,
 532                      pkgAcquire::MethodConfig *Cnf);
 533    virtual std::string Custom600Headers() const;
 534    virtual std::string DescURI() const {return RealURI; };
 535    virtual void Finished();
 536
 537    /** \brief Create a new pkgAcqMetaIndex. */
 538    pkgAcqMetaIndex(pkgAcquire *Owner,
 539                    pkgAcqMetaBase *TransactionManager,
 540                    std::string URI,std::string URIDesc, std::string ShortDesc,
 541                    std::string MetaIndexSigURI, std::string MetaIndexSigURIDesc, std::string MetaIndexSigShortDesc,
 542                    const std::vector<IndexTarget*>* IndexTargets,
 543                    indexRecords* MetaIndexParser);
 544 };
 545                                                                         /*}}}*/
 546 /** \brief An item repsonsible for downloading clearsigned metaindexes  {{{*/
 547 class pkgAcqMetaClearSig : public pkgAcqMetaIndex
 548 {
 549    void *d;
 550
 551    /** \brief The URI of the meta-index file for the detached signature */
 552    std::string MetaIndexURI;
 553
 554    /** \brief A "URI-style" description of the meta-index file */
 555    std::string MetaIndexURIDesc;
 556
 557    /** \brief A brief description of the meta-index file */
 558    std::string MetaIndexShortDesc;
 559
 560    /** \brief The URI of the detached meta-signature file if the clearsigned one failed. */
 561    std::string MetaSigURI;
 562
 563    /** \brief A "URI-style" description of the meta-signature file */
 564    std::string MetaSigURIDesc;
 565
 566    /** \brief A brief description of the meta-signature file */
 567    std::string MetaSigShortDesc;
 568
 569 public:
 570    virtual void Failed(std::string Message,pkgAcquire::MethodConfig *Cnf);
 571    virtual std::string Custom600Headers() const;
 572    virtual void Done(std::string Message,unsigned long long Size, HashStringList const &Hashes,
 573                      pkgAcquire::MethodConfig *Cnf);
 574
 575    /** \brief Create a new pkgAcqMetaClearSig. */
 576    pkgAcqMetaClearSig(pkgAcquire *Owner,
 577                 std::string const &URI, std::string const &URIDesc, std::string const &ShortDesc,
 578                 std::string const &MetaIndexURI, std::string const &MetaIndexURIDesc, std::string const &MetaIndexShortDesc,
 579                 std::string const &MetaSigURI, std::string const &MetaSigURIDesc, std::string const &MetaSigShortDesc,
 580                 const std::vector<IndexTarget*>* IndexTargets,
 581                 indexRecords* MetaIndexParser);
 582    virtual ~pkgAcqMetaClearSig();
 583 };
 584                                                                         /*}}}*/
 585
 586
 587 /** \brief Common base class for all classes that deal with fetching    {{{
 588            indexes
 589  */
 590 class pkgAcqBaseIndex : public pkgAcquire::Item
 591 {
 592    void *d;
 593
 594  protected:
 595    /** \brief Pointer to the IndexTarget data
 596     */
 597    const struct IndexTarget * Target;
 598    indexRecords *MetaIndexParser;
 599    /** \brief The MetaIndex Key */
 600    std::string MetaKey;
 601
 602    pkgAcqBaseIndex(pkgAcquire *Owner,
 603                    pkgAcqMetaBase *TransactionManager,
 604                    struct IndexTarget const * const Target,
 605                    HashStringList const &ExpectedHashes,
 606                    indexRecords *MetaIndexParser)
 607       : Item(Owner, ExpectedHashes, TransactionManager), Target(Target),
 608         MetaIndexParser(MetaIndexParser) {};
 609 };
 610                                                                         /*}}}*/
 611 /** \brief An item that is responsible for fetching an index file of    {{{
 612  *  package list diffs and starting the package list's download.
 613  *
 614  *  This item downloads the Index file and parses it, then enqueues
 615  *  additional downloads of either the individual patches (using
 616  *  pkgAcqIndexDiffs) or the entire Packages file (using pkgAcqIndex).
 617  *
 618  *  \sa pkgAcqIndexDiffs, pkgAcqIndex
 619  */
 620 class pkgAcqDiffIndex : public pkgAcqBaseIndex
 621 {
 622    void *d;
 623
 624  protected:
 625    /** \brief If \b true, debugging information will be written to std::clog. */
 626    bool Debug;
 627
 628    /** \brief The URI of the index file to recreate at our end (either
 629     *  by downloading it or by applying partial patches).
 630     */
 631    std::string RealURI;
 632
 633    /** \brief The index file which will be patched to generate the new
 634     *  file.
 635     */
 636    std::string CurrentPackagesFile;
 637
 638    /** \brief A description of the Packages file (stored in
 639     *  pkgAcquire::ItemDesc::Description).
 640     */
 641    std::string Description;
 642
 643    /** \brief If the copy step of the packages file is done
 644     */
 645    bool PackagesFileReadyInPartial;
 646
 647  public:
 648    // Specialized action members
 649    virtual void Failed(std::string Message,pkgAcquire::MethodConfig *Cnf);
 650    virtual void Done(std::string Message,unsigned long long Size, HashStringList const &Hashes,
 651                      pkgAcquire::MethodConfig *Cnf);
 652    virtual std::string DescURI() const {return RealURI + "Index";};
 653    virtual std::string Custom600Headers() const;
 654
 655    /** \brief Parse the Index file for a set of Packages diffs.
 656     *
 657     *  Parses the Index file and creates additional download items as
 658     *  necessary.
 659     *
 660     *  \param IndexDiffFile The name of the Index file.
 661     *
 662     *  \return \b true if the Index file was successfully parsed, \b
 663     *  false otherwise.
 664     */
 665    bool ParseDiffIndex(std::string IndexDiffFile);
 666
 667
 668    /** \brief Create a new pkgAcqDiffIndex.
 669     *
 670     *  \param Owner The Acquire object that owns this item.
 671     *
 672     *  \param URI The URI of the list file to download.
 673     *
 674     *  \param URIDesc A long description of the list file to download.
 675     *
 676     *  \param ShortDesc A short description of the list file to download.
 677     *
 678     *  \param ExpectedHashes The list file's hashsums which are expected.
 679     */
 680    pkgAcqDiffIndex(pkgAcquire *Owner,
 681                    pkgAcqMetaBase *TransactionManager,
 682                    struct IndexTarget const * const Target,
 683                    HashStringList const &ExpectedHashes,
 684                    indexRecords *MetaIndexParser);
 685 };
 686                                                                         /*}}}*/
 687 /** \brief An item that is responsible for fetching client-merge patches {{{
 688  *  that need to be applied to a given package index file.
 689  *
 690  *  Instead of downloading and applying each patch one by one like its
 691  *  sister #pkgAcqIndexDiffs this class will download all patches at once
 692  *  and call rred with all the patches downloaded once. Rred will then
 693  *  merge and apply them in one go, which should be a lot faster – but is
 694  *  incompatible with server-based merges of patches like reprepro can do.
 695  *
 696  *  \sa pkgAcqDiffIndex, pkgAcqIndex
 697  */
 698 class pkgAcqIndexMergeDiffs : public pkgAcqBaseIndex
 699 {
 700    void *d;
 701
 702    protected:
 703
 704    /** \brief If \b true, debugging output will be written to
 705     *  std::clog.
 706     */
 707    bool Debug;
 708
 709    /** \brief URI of the package index file that is being
 710     *  reconstructed.
 711     */
 712    std::string RealURI;
 713
 714    /** \brief description of the file being downloaded. */
 715    std::string Description;
 716
 717    /** \brief information about the current patch */
 718    struct DiffInfo const patch;
 719
 720    /** \brief list of all download items for the patches */
 721    std::vector<pkgAcqIndexMergeDiffs*> const * const allPatches;
 722
 723    /** The current status of this patch. */
 724    enum DiffState
 725    {
 726       /** \brief The diff is currently being fetched. */
 727       StateFetchDiff,
 728
 729       /** \brief The diff is currently being applied. */
 730       StateApplyDiff,
 731
 732       /** \brief the work with this diff is done */
 733       StateDoneDiff,
 734
 735       /** \brief something bad happened and fallback was triggered */
 736       StateErrorDiff
 737    } State;
 738
 739    public:
 740    /** \brief Called when the patch file failed to be downloaded.
 741     *
 742     *  This method will fall back to downloading the whole index file
 743     *  outright; its arguments are ignored.
 744     */
 745    virtual void Failed(std::string Message,pkgAcquire::MethodConfig *Cnf);
 746    virtual void Done(std::string Message,unsigned long long Size, HashStringList const &Hashes,
 747          pkgAcquire::MethodConfig *Cnf);
 748    virtual std::string DescURI() const {return RealURI + "Index";};
 749
 750    /** \brief Create an index merge-diff item.
 751     *
 752     *  \param Owner The pkgAcquire object that owns this item.
 753     *
 754     *  \param URI The URI of the package index file being
 755     *  reconstructed.
 756     *
 757     *  \param URIDesc A long description of this item.
 758     *
 759     *  \param ShortDesc A brief description of this item.
 760     *
 761     *  \param ExpectedHashes The expected md5sum of the completely
 762     *  reconstructed package index file; the index file will be tested
 763     *  against this value when it is entirely reconstructed.
 764     *
 765     *  \param patch contains infos about the patch this item is supposed
 766     *  to download which were read from the index
 767     *
 768     *  \param allPatches contains all related items so that each item can
 769     *  check if it was the last one to complete the download step
 770     */
 771    pkgAcqIndexMergeDiffs(pkgAcquire *Owner,
 772                          pkgAcqMetaBase *TransactionManager,
 773                          struct IndexTarget const * const Target,
 774                          HashStringList const &ExpectedHash,
 775                          indexRecords *MetaIndexParser,
 776                          DiffInfo const &patch,
 777                          std::vector<pkgAcqIndexMergeDiffs*> const * const allPatches);
 778 };
 779                                                                         /*}}}*/
 780 /** \brief An item that is responsible for fetching server-merge patches {{{
 781  *  that need to be applied to a given package index file.
 782  *
 783  *  After downloading and applying a single patch, this item will
 784  *  enqueue a new pkgAcqIndexDiffs to download and apply the remaining
 785  *  patches.  If no patch can be found that applies to an intermediate
 786  *  file or if one of the patches cannot be downloaded, falls back to
 787  *  downloading the entire package index file using pkgAcqIndex.
 788  *
 789  *  \sa pkgAcqDiffIndex, pkgAcqIndex
 790  */
 791 class pkgAcqIndexDiffs : public pkgAcqBaseIndex
 792 {
 793    void *d;
 794
 795    private:
 796
 797    /** \brief Queue up the next diff download.
 798     *
 799     *  Search for the next available diff that applies to the file
 800     *  that currently exists on disk, and enqueue it by calling
 801     *  QueueURI().
 802     *
 803     *  \return \b true if an applicable diff was found, \b false
 804     *  otherwise.
 805     */
 806    bool QueueNextDiff();
 807
 808    /** \brief Handle tasks that must be performed after the item
 809     *  finishes downloading.
 810     *
 811     *  Dequeues the item and checks the resulting file's hashsums
 812     *  against ExpectedHashes after the last patch was applied.
 813     *  There is no need to check the md5/sha1 after a "normal"
 814     *  patch because QueueNextDiff() will check the sha1 later.
 815     *
 816     *  \param allDone If \b true, the file was entirely reconstructed,
 817     *  and its md5sum is verified.
 818     */
 819    void Finish(bool allDone=false);
 820
 821    protected:
 822
 823    /** \brief If \b true, debugging output will be written to
 824     *  std::clog.
 825     */
 826    bool Debug;
 827
 828    /** \brief The URI of the package index file that is being
 829     *  reconstructed.
 830     */
 831    std::string RealURI;
 832
 833    /** A description of the file being downloaded. */
 834    std::string Description;
 835
 836    /** The patches that remain to be downloaded, including the patch
 837     *  being downloaded right now.  This list should be ordered so
 838     *  that each diff appears before any diff that depends on it.
 839     *
 840     *  \todo These are indexed by sha1sum; why not use some sort of
 841     *  dictionary instead of relying on ordering and stripping them
 842     *  off the front?
 843     */
 844    std::vector<DiffInfo> available_patches;
 845
 846    /** Stop applying patches when reaching that sha1 */
 847    std::string ServerSha1;
 848
 849    /** The current status of this patch. */
 850    enum DiffState
 851      {
 852         /** \brief The diff is in an unknown state. */
 853          StateFetchUnkown,
 854
 855          /** \brief The diff is currently being fetched. */
 856          StateFetchDiff,
 857
 858          /** \brief The diff is currently being uncompressed. */
 859          StateUnzipDiff, // FIXME: No longer used
 860
 861          /** \brief The diff is currently being applied. */
 862          StateApplyDiff
 863    } State;
 864
 865    public:
 866
 867    /** \brief Called when the patch file failed to be downloaded.
 868     *
 869     *  This method will fall back to downloading the whole index file
 870     *  outright; its arguments are ignored.
 871     */
 872    virtual void Failed(std::string Message,pkgAcquire::MethodConfig *Cnf);
 873
 874    virtual void Done(std::string Message,unsigned long long Size, HashStringList const &Hashes,
 875                      pkgAcquire::MethodConfig *Cnf);
 876    virtual std::string DescURI() const {return RealURI + "IndexDiffs";};
 877
 878    /** \brief Create an index diff item.
 879     *
 880     *  After filling in its basic fields, this invokes Finish(true) if
 881     *  \a diffs is empty, or QueueNextDiff() otherwise.
 882     *
 883     *  \param Owner The pkgAcquire object that owns this item.
 884     *
 885     *  \param URI The URI of the package index file being
 886     *  reconstructed.
 887     *
 888     *  \param URIDesc A long description of this item.
 889     *
 890     *  \param ShortDesc A brief description of this item.
 891     *
 892     *  \param ExpectedHashes The expected md5sum of the completely
 893     *  reconstructed package index file; the index file will be tested
 894     *  against this value when it is entirely reconstructed.
 895     *
 896     *  \param ServerSha1 is the sha1sum of the current file on the server
 897     *
 898     *  \param diffs The remaining diffs from the index of diffs.  They
 899     *  should be ordered so that each diff appears before any diff
 900     *  that depends on it.
 901     */
 902    pkgAcqIndexDiffs(pkgAcquire *Owner,
 903                     pkgAcqMetaBase *TransactionManager,
 904                     struct IndexTarget const * const Target,
 905                     HashStringList const &ExpectedHash,
 906                     indexRecords *MetaIndexParser,
 907                     std::string ServerSha1,
 908                     std::vector<DiffInfo> diffs=std::vector<DiffInfo>());
 909 };
 910                                                                         /*}}}*/
 911 /** \brief An acquire item that is responsible for fetching an index    {{{
 912  *  file (e.g., Packages or Sources).
 913  *
 914  *  \sa pkgAcqDiffIndex, pkgAcqIndexDiffs, pkgAcqIndexTrans
 915  *
 916  *  \todo Why does pkgAcqIndex have protected members?
 917  */
 918 class pkgAcqIndex : public pkgAcqBaseIndex
 919 {
 920    void *d;
 921
 922    protected:
 923
 924    /** \brief If \b true, the index file has been decompressed. */
 925    bool Decompression;
 926
 927    /** \brief If \b true, the partially downloaded file will be
 928     *  removed when the download completes.
 929     */
 930    bool Erase;
 931
 932    /** \brief The object that is actually being fetched (minus any
 933     *  compression-related extensions).
 934     */
 935    std::string RealURI;
 936
 937    /** \brief The compression-related file extensions that are being
 938     *  added to the downloaded file one by one if first fails (e.g., "gz bz2").
 939     */
 940    std::string CompressionExtension;
 941
 942
 943    /** \brief Do the changes needed to fetch via AptByHash (if needed) */
 944    void InitByHashIfNeeded(const std::string MetaKey);
 945
 946    /** \brief Auto select the right compression to use */
 947    void AutoSelectCompression();
 948
 949    /** \brief Get the full pathname of the final file for the current URI
 950     */
 951    std::string GetFinalFilename() const;
 952
 953    /** \brief Schedule file for verification after a IMS hit */
 954    void ReverifyAfterIMS();
 955
 956    public:
 957
 958    // Specialized action members
 959    virtual void Failed(std::string Message,pkgAcquire::MethodConfig *Cnf);
 960    virtual void Done(std::string Message,unsigned long long Size, HashStringList const &Hashes,
 961                      pkgAcquire::MethodConfig *Cnf);
 962    virtual std::string Custom600Headers() const;
 963    virtual std::string DescURI() const {return Desc.URI;};
 964
 965    /** \brief Create a pkgAcqIndex.
 966     *
 967     *  \param Owner The pkgAcquire object with which this item is
 968     *  associated.
 969     *
 970     *  \param URI The URI of the index file that is to be downloaded.
 971     *
 972     *  \param URIDesc A "URI-style" description of this index file.
 973     *
 974     *  \param ShortDesc A brief description of this index file.
 975     *
 976     *  \param ExpectedHashes The expected hashsum of this index file.
 977     *
 978     *  \param compressExt The compression-related extension with which
 979     *  this index file should be downloaded, or "" to autodetect
 980     *  Compression types can be set with config Acquire::CompressionTypes,
 981     *  default is ".lzma" or ".bz2" (if the needed binaries are present)
 982     *  fallback is ".gz" or none.
 983     */
 984    pkgAcqIndex(pkgAcquire *Owner,std::string URI,std::string URIDesc,
 985                std::string ShortDesc, HashStringList const &ExpectedHashes);
 986    pkgAcqIndex(pkgAcquire *Owner, pkgAcqMetaBase *TransactionManager,
 987                IndexTarget const * const Target,
 988                HashStringList const &ExpectedHash,
 989                indexRecords *MetaIndexParser);
 990
 991    void Init(std::string const &URI, std::string const &URIDesc,
 992              std::string const &ShortDesc);
 993 };
 994                                                                         /*}}}*/
 995 /** \brief An acquire item that is responsible for fetching a           {{{
 996  *  translated index file.
 997  *
 998  *  The only difference from pkgAcqIndex is that transient failures
 999  *  are suppressed: no error occurs if the translated index file is
1000  *  missing.
1001  */
1002 class pkgAcqIndexTrans : public pkgAcqIndex
1003 {
1004    void *d;
1005
1006    public:
1007
1008    virtual void Failed(std::string Message,pkgAcquire::MethodConfig *Cnf);
1009    virtual std::string Custom600Headers() const;
1010
1011    /** \brief Create a pkgAcqIndexTrans.
1012     *
1013     *  \param Owner The pkgAcquire object with which this item is
1014     *  associated.
1015     *
1016     *  \param URI The URI of the index file that is to be downloaded.
1017     *
1018     *  \param URIDesc A "URI-style" description of this index file.
1019     *
1020     *  \param ShortDesc A brief description of this index file.
1021     */
1022    pkgAcqIndexTrans(pkgAcquire *Owner,
1023                     std::string URI,std::string URIDesc,
1024                     std::string ShortDesc);
1025    pkgAcqIndexTrans(pkgAcquire *Owner,
1026                     pkgAcqMetaBase *TransactionManager,
1027                     IndexTarget const * const Target,
1028                     HashStringList const &ExpectedHashes,
1029                     indexRecords *MetaIndexParser);
1030 };
1031                                                                         /*}}}*/
1032 /** \brief Information about an index file. */                          /*{{{*/
1033 class IndexTarget
1034 {
1035    void *d;
1036
1037  public:
1038    /** \brief A URI from which the index file can be downloaded. */
1039    std::string URI;
1040
1041    /** \brief A description of the index file. */
1042    std::string Description;
1043
1044    /** \brief A shorter description of the index file. */
1045    std::string ShortDesc;
1046
1047    /** \brief The key by which this index file should be
1048     *  looked up within the meta signature file.
1049     */
1050    std::string MetaKey;
1051
1052    virtual bool IsOptional() const {
1053       return false;
1054    }
1055 };
1056                                                                         /*}}}*/
1057 /** \brief Information about an optional index file. */                 /*{{{*/
1058 class OptionalIndexTarget : public IndexTarget
1059 {
1060    void *d;
1061
1062    virtual bool IsOptional() const {
1063       return true;
1064    }
1065 };
1066                                                                         /*}}}*/
1067
1068 /** \brief An item that is responsible for fetching a package file.     {{{
1069  *
1070  *  If the package file already exists in the cache, nothing will be
1071  *  done.
1072  */
1073 class pkgAcqArchive : public pkgAcquire::Item
1074 {
1075    void *d;
1076
1077    protected:
1078    /** \brief The package version being fetched. */
1079    pkgCache::VerIterator Version;
1080
1081    /** \brief The list of sources from which to pick archives to
1082     *  download this package from.
1083     */
1084    pkgSourceList *Sources;
1085
1086    /** \brief A package records object, used to look up the file
1087     *  corresponding to each version of the package.
1088     */
1089    pkgRecords *Recs;
1090
1091    /** \brief A location in which the actual filename of the package
1092     *  should be stored.
1093     */
1094    std::string &StoreFilename;
1095
1096    /** \brief The next file for this version to try to download. */
1097    pkgCache::VerFileIterator Vf;
1098
1099    /** \brief How many (more) times to try to find a new source from
1100     *  which to download this package version if it fails.
1101     *
1102     *  Set from Acquire::Retries.
1103     */
1104    unsigned int Retries;
1105
1106    /** \brief \b true if this version file is being downloaded from a
1107     *  trusted source.
1108     */
1109    bool Trusted;
1110
1111    /** \brief Queue up the next available file for this version. */
1112    bool QueueNext();
1113
1114    public:
1115
1116    virtual void Failed(std::string Message,pkgAcquire::MethodConfig *Cnf);
1117    virtual void Done(std::string Message,unsigned long long Size, HashStringList const &Hashes,
1118                      pkgAcquire::MethodConfig *Cnf);
1119    virtual std::string DescURI() const {return Desc.URI;};
1120    virtual std::string ShortDesc() const {return Desc.ShortDesc;};
1121    virtual void Finished();
1122    virtual bool IsTrusted() const;
1123
1124    /** \brief Create a new pkgAcqArchive.
1125     *
1126     *  \param Owner The pkgAcquire object with which this item is
1127     *  associated.
1128     *
1129     *  \param Sources The sources from which to download version
1130     *  files.
1131     *
1132     *  \param Recs A package records object, used to look up the file
1133     *  corresponding to each version of the package.
1134     *
1135     *  \param Version The package version to download.
1136     *
1137     *  \param[out] StoreFilename A location in which the actual filename of
1138     *  the package should be stored.  It will be set to a guessed
1139     *  basename in the constructor, and filled in with a fully
1140     *  qualified filename once the download finishes.
1141     */
1142    pkgAcqArchive(pkgAcquire *Owner,pkgSourceList *Sources,
1143                  pkgRecords *Recs,pkgCache::VerIterator const &Version,
1144                  std::string &StoreFilename);
1145 };
1146                                                                         /*}}}*/
1147 /** \brief Retrieve an arbitrary file to the current directory.         {{{
1148  *
1149  *  The file is retrieved even if it is accessed via a URL type that
1150  *  normally is a NOP, such as "file".  If the download fails, the
1151  *  partial file is renamed to get a ".FAILED" extension.
1152  */
1153 class pkgAcqFile : public pkgAcquire::Item
1154 {
1155    void *d;
1156
1157    /** \brief How many times to retry the download, set from
1158     *  Acquire::Retries.
1159     */
1160    unsigned int Retries;
1161
1162    /** \brief Should this file be considered a index file */
1163    bool IsIndexFile;
1164
1165    public:
1166
1167    // Specialized action members
1168    virtual void Failed(std::string Message,pkgAcquire::MethodConfig *Cnf);
1169    virtual void Done(std::string Message,unsigned long long Size, HashStringList const &CalcHashes,
1170                      pkgAcquire::MethodConfig *Cnf);
1171    virtual std::string DescURI() const {return Desc.URI;};
1172    virtual std::string Custom600Headers() const;
1173
1174    /** \brief Create a new pkgAcqFile object.
1175     *
1176     *  \param Owner The pkgAcquire object with which this object is
1177     *  associated.
1178     *
1179     *  \param URI The URI to download.
1180     *
1181     *  \param Hashes The hashsums of the file to download, if they are known;
1182     *  otherwise empty list.
1183     *
1184     *  \param Size The size of the file to download, if it is known;
1185     *  otherwise 0.
1186     *
1187     *  \param Desc A description of the file being downloaded.
1188     *
1189     *  \param ShortDesc A brief description of the file being
1190     *  downloaded.
1191     *
1192     *  \param DestDir The directory the file should be downloaded into.
1193     *
1194     *  \param DestFilename The filename+path the file is downloaded to.
1195     *
1196     *  \param IsIndexFile The file is considered a IndexFile and cache-control
1197     *                     headers like "cache-control: max-age=0" are send
1198     *
1199     * If DestFilename is empty, download to DestDir/\<basename\> if
1200     * DestDir is non-empty, $CWD/\<basename\> otherwise.  If
1201     * DestFilename is NOT empty, DestDir is ignored and DestFilename
1202     * is the absolute name to which the file should be downloaded.
1203     */
1204
1205    pkgAcqFile(pkgAcquire *Owner, std::string URI, HashStringList const &Hashes, unsigned long long Size,
1206               std::string Desc, std::string ShortDesc,
1207               const std::string &DestDir="", const std::string &DestFilename="",
1208               bool IsIndexFile=false);
1209 };
1210                                                                         /*}}}*/
1211 /** @} */
1212
1213 #endif