pkgAcqDiffIndex Class Referencefinal
Acquire system {{{

An item that is responsible for fetching an index file of {{{ package list diffs and starting the package list's download. More...

`#include <apt-pkg/acquire-item.h>`

Inheritance diagram for pkgAcqDiffIndex:
[legend]
Collaboration diagram for pkgAcqDiffIndex:
[legend]

## Public Member Functions

void | Failed (std::string const &Message, pkgAcquire::MethodConfig const *Cnf) override
| Invoked by the acquire worker when the object couldn't be fetched.
bool | VerifyDone (std::string const &Message, pkgAcquire::MethodConfig const *Cnf) override
| Invoked by the acquire worker to check if the successfully fetched object is also the objected we wanted to have.
void | Done (std::string const &Message, HashStringList const &Hashes, pkgAcquire::MethodConfig const *Cnf) override
| Invoked by the acquire worker when the object was fetched successfully.
std::string | DescURI () const override
| A "descriptive" URI-like string.
std::string | GetMetaKey () const override
bool | ParseDiffIndex (std::string const &IndexDiffFile)
| Parse the Index file for a set of Packages diffs.
| pkgAcqDiffIndex (pkgAcquire *const Owner, pkgAcqMetaClearSig *const TransactionManager, IndexTarget const &Target) APT_NONNULL(2
| Create a new pkgAcqDiffIndex.
Public Member Functions inherited from pkgAcqIndex
void | Failed (std::string const &Message, pkgAcquire::MethodConfig const *Cnf) override
| Invoked by the acquire worker when the object couldn't be fetched.
void | Done (std::string const &Message, HashStringList const &Hashes, pkgAcquire::MethodConfig const *Cnf) override
| Invoked by the acquire worker when the object was fetched successfully.
std::string | Custom600Headers () const override
| Custom headers to be sent to the fetch process.
std::string | DescURI () const override
| A "descriptive" URI-like string.
std::string | GetMetaKey () const override
| pkgAcqIndex (pkgAcquire *const Owner, pkgAcqMetaClearSig *const TransactionManager, IndexTarget const &Target, bool const Derived=false) APT_NONNULL(2
Public Member Functions inherited from pkgAcqBaseIndex
| pkgAcqBaseIndex (pkgAcquire *const Owner, pkgAcqMetaClearSig *const TransactionManager, IndexTarget const &Target) APT_NONNULL(2
Public Member Functions inherited from pkgAcqTransactionItem
std::string | DescURI () const override
| A "descriptive" URI-like string.
HashStringList | GetExpectedHashes () const override
bool | HashesRequired () const override
virtual bool | AcquireByHash () const
| pkgAcqTransactionItem (pkgAcquire *const Owner, pkgAcqMetaClearSig *const TransactionManager, IndexTarget const &Target) APT_NONNULL(2
Public Member Functions inherited from pkgAcquire::Item
APT_HIDDEN void | FailMessage (std::string const &Message)
virtual void | Start (std::string const &Message, unsigned long long const Size)
| Invoked when the worker starts to fetch this object.
APT_HIDDEN std::unordered_map< std::string, std::string > & | ModifyCustomFields ()
APT_HIDDEN bool | PopAlternativeURI (std::string &NewURI)
APT_HIDDEN bool | IsGoodAlternativeURI (std::string const &AltUri) const
APT_HIDDEN void | PushAlternativeURI (std::string &&NewURI, std::unordered_map< std::string, std::string > &&fields, bool const at_the_back)
APT_HIDDEN void | RemoveAlternativeSite (std::string const &AltUri)
virtual std::string | ShortDesc () const
| Short item description.
APT_HIDDEN void | Cancelled ()
| Invoked by the worker when the download is cancelled before completion.
virtual void | Finished ()
| Invoked by the worker when the download is completely done.
std::string | HashSum () const
pkgAcquire * | GetOwner () const
pkgAcquire::ItemDesc & | GetItemDesc ()
virtual bool | IsTrusted () const
void | SetActiveSubprocess (std::string const &subprocess)
| Set the name of the current active subprocess.
| Item (pkgAcquire *const Owner)
| Initialize an item.
virtual | ~Item ()
| Remove this item from its owner's queue by invoking pkgAcquire::Remove.
bool APT_HIDDEN | IsRedirectionLoop (std::string const &NewURI)
int APT_HIDDEN | Priority ()
| The priority of the item, used for queuing.
void APT_HIDDEN | FetchAfter (time_point FetchAfter)
| internal clock definitions to avoid typing all that all over the place
time_point APT_HIDDEN | FetchAfter ()
Public Member Functions inherited from WeakPointable
void | AddWeakPointer (WeakPointable **weakptr)
void | RemoveWeakPointer (WeakPointable **weakptr)
| ~WeakPointable ()

## Protected Member Functions

std::string | GetFinalFilename () const override
| Get the full pathname of the final file for the current URI.
bool | QueueURI (pkgAcquire::ItemDesc &Item) override
| Insert this item into its owner's queue.
bool | TransactionState (TransactionStates state) override
Protected Member Functions inherited from pkgAcqIndex
void | StageDownloadDone (std::string const &Message)
| Handle what needs to be done when the download is done.
void | StageDecompressDone ()
| Handle what needs to be done when the decompression/copy is done.
void | InitByHashIfNeeded ()
| Do the changes needed to fetch via AptByHash (if needed).
std::string | GetFinalFilename () const override
| Get the full pathname of the final file for the current URI.
bool | TransactionState (TransactionStates state) override
APT_HIDDEN void | Init (std::string const &URI, std::string const &URIDesc, std::string const &ShortDesc)
APT_HIDDEN bool | CommonFailed (std::string const &TargetURI, std::string const &Message, pkgAcquire::MethodConfig const *const Cnf)
Protected Member Functions inherited from pkgAcqTransactionItem
HashStringList | GetExpectedHashesFor (std::string const &MetaKey) const
bool | QueueURI (pkgAcquire::ItemDesc &Item) override
| Insert this item into its owner's queue.
Protected Member Functions inherited from pkgAcquire::Item
bool | RenameOnError (RenameOnErrorState const state)
| Rename failed file and set error.
void | Dequeue ()
| Remove this item from its owner's queue.
bool | Rename (std::string const &From, std::string const &To)
| Rename a file without modifying its timestamp.

## Protected Attributes

bool | Debug
| If true, debugging information will be written to std::clog.
Protected Attributes inherited from pkgAcqIndex
AllStages | Stage
std::string | EraseFileName
| If set, this partially downloaded file will be removed when the download completes.
std::string | CompressionExtensions
| The compression-related file extensions that are being added to the downloaded file one by one if first fails (e.g., "gz bz2").
std::string | CurrentCompressionExtension
| The actual compression extension currently used.
Protected Attributes inherited from pkgAcquire::Item
pkgAcquire *const | Owner
| The acquire object with which this item is associated.
pkgAcquire::ItemDesc | Desc
| The item that is currently being downloaded.

## Additional Inherited Members

Public Types inherited from pkgAcqTransactionItem
enum | TransactionStates { TransactionStarted , TransactionCommit , TransactionAbort }
Public Types inherited from pkgAcquire::Item
enum | ItemState { StatIdle , StatFetching , StatDone , StatError , StatAuthError , StatTransientNetworkError }
| The current status of this item. More...
Public Attributes inherited from pkgAcqTransactionItem
IndexTarget const | Target
std::string | PartialFile
| storge name until a transaction is finished
pkgAcqMetaClearSig *const | TransactionManager
| TransactionManager.
Public Attributes inherited from pkgAcquire::Item
enum pkgAcquire::Item::ItemState | Status
std::string | ErrorText
| Contains a textual description of the error encountered if ItemState is StatError or StatAuthError.
unsigned long long | FileSize
| The size of the object to fetch.
unsigned long long | PartialSize
| How much of the object was already fetched.
std::string | ActiveSubprocess
| contains the name of the subprocess that is operating on this object (for instance, "gzip", "rred" or "gpgv"). This is obsoleting #Mode from above as it can manage the lifetime of included string properly.
unsigned long | ID
| A client-supplied unique identifier.
bool | Complete
| If true, the entire object has been successfully fetched.
bool | Local
| If true, the URI of this object is "local".
std::string | UsedMirror
unsigned int | QueueCounter
| The number of fetch queues into which this item has been inserted.
unsigned int | ExpectedAdditionalItems
| The number of additional fetch items that are expected once this item is done.
std::string | DestFile
| The name of the file into which the retrieved object will be written.
unsigned int | Retries
| Number of retries.
Protected Types inherited from pkgAcqIndex
enum | AllStages { STAGE_DOWNLOAD , STAGE_DECOMPRESS_AND_VERIFY }
| The stages the method goes through. More...
Protected Types inherited from pkgAcquire::Item
enum | RenameOnErrorState { HashSumMismatch , SizeMismatch , InvalidFormat , SignatureError , NotClearsigned , MaximumSizeExceeded , PDiffError }

## Detailed Description

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).

See also
  pkgAcqIndexDiffs, pkgAcqIndex

## Constructor & Destructor Documentation

## pkgAcqDiffIndex()

pkgAcqDiffIndex | ( | pkgAcquire *const | Owner,
|  | pkgAcqMetaClearSig *const | TransactionManager,
|  | IndexTarget const & | Target )

Create a new pkgAcqDiffIndex.

Parameters

  Owner | The Acquire object that owns this item.
  URI | The URI of the list file to download.
  URIDesc | A long description of the list file to download.
  ShortDesc | A short description of the list file to download.

Todo
  Magic number as an upper bound on pdiffs we will reasonably acquire

References pkgAcqIndex::CompressionExtensions, Debug, pkgAcquire::Item::Desc, pkgAcquire::Item::ExpectedAdditionalItems, pkgAcquire::Item::Owner, and pkgAcqTransactionItem::TransactionManager.

## Member Function Documentation

## DescURI()

std::string DescURI | ( |  | ) | const

inline nodiscard override virtual

A "descriptive" URI-like string.

Returns
  a URI that should be used to describe what is being fetched.

Implements pkgAcquire::Item.

## Done()

void Done | ( | std::string const & | Message,
|  | HashStringList const & | Hashes,
|  | pkgAcquire::MethodConfig const * | Cnf )

override virtual

Invoked by the acquire worker when the object was fetched successfully.

Note that the object might 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.

Parameters

  Message | Data from the acquire method. Use LookupTag() to parse it.
  Hashes | The HashSums of the object that was fetched.
  Cnf | The method via which the object was fetched.

See also
  pkgAcqMethod

Reimplemented from pkgAcquire::Item.

References pkgAcquire::Item::Complete, Debug, pkgAcquire::Item::Dequeue(), pkgAcquire::Item::Desc, pkgAcquire::Item::DestFile, pkgAcquire::Item::Owner, pkgAcquire::Item::StatDone, and pkgAcqTransactionItem::TransactionManager.

## Failed()

void Failed | ( | std::string const & | Message,
|  | pkgAcquire::MethodConfig const * | Cnf )

override virtual

Invoked by the acquire worker when the object couldn't be fetched.

This is a branch of the continuation of the fetch process.

Parameters

  Message | An RFC822-formatted message from the acquire method describing what went wrong. Use LookupTag() to parse it.
  Cnf | The method via which the worker tried to fetch this object.

See also
  pkgAcqMethod

Reimplemented from pkgAcqBaseIndex.

References Debug, pkgAcquire::Item::Desc, pkgAcquire::Item::ExpectedAdditionalItems, pkgAcquire::Item::Owner, pkgAcquire::Item::RenameOnError(), pkgAcquire::Item::StatDone, and pkgAcqTransactionItem::TransactionManager.

## GetFinalFilename()

std::string GetFinalFilename | ( |  | ) | const

nodiscard override protected virtual

Get the full pathname of the final file for the current URI.

Reimplemented from pkgAcqBaseIndex.

## GetMetaKey()

std::string GetMetaKey | ( |  | ) | const

nodiscard override virtual

Reimplemented from pkgAcqTransactionItem.

## ParseDiffIndex()

bool ParseDiffIndex | ( | std::string const & | IndexDiffFile | ) |

Parse the Index file for a set of Packages diffs.

Parses the Index file and creates additional download items as necessary.

Parameters

  IndexDiffFile | The name of the Index file.

Returns
  true if the Index file was successfully parsed, false otherwise.

Todo
  all of pdiff supports only .gz compressed patches

References Debug, pkgAcquire::Item::ErrorText, pkgAcquire::Item::ExpectedAdditionalItems, DiffInfo::file, HashStringList::FileSize(), HashStringList::find(), pkgAcqTransactionItem::PartialFile, HashStringList::push_back(), DiffInfo::result_hashes, pkgAcqTransactionItem::TransactionManager, and HashStringList::usable().

Referenced by VerifyDone().

## QueueURI()

bool QueueURI | ( | pkgAcquire::ItemDesc & | Item | ) |

override protected virtual

Insert this item into its owner's queue.

The method is designed to check if the request would end in an IMSHit and if it determines that it would, it isn't queueing the Item and instead sets it to completion instantly.

Parameters

  Item | Metadata about this item (its URI and description).

Returns
  true if the item was inserted, false if IMSHit was detected

Reimplemented from pkgAcquire::Item.

References pkgAcquire::Item::Item(), and pkgAcqTransactionItem::QueueURI().

## TransactionState()

bool TransactionState | ( | TransactionStates | state | ) |

override protected virtual

Reimplemented from pkgAcqTransactionItem.

## VerifyDone()

bool VerifyDone | ( | std::string const & | Message,
|  | pkgAcquire::MethodConfig const * | Cnf )

override virtual

Invoked by the acquire worker to check if the successfully fetched object is also the objected we wanted to have.

Note that the object might 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.

This is called before Done is called and can prevent it by returning false which will result in Failed being called instead.

You should prefer to use this method over calling Failed() from Done() as this has e.g. the wrong progress reporting.

Parameters

  Message | Data from the acquire method. Use LookupTag() to parse it.
  Cnf | The method via which the object was fetched.

See also
  pkgAcqMethod

Reimplemented from pkgAcquire::Item.

References pkgAcquire::Item::DestFile, pkgAcquire::Item::ErrorText, ParseDiffIndex(), and pkgAcquire::Item::StatError.

The documentation for this class was generated from the following files:

- apt-pkg/acquire-item.h
- apt-pkg/acquire-item.cc