pkgAcquire::Item Class Referenceabstract
Acquire system {{{

Represents the process by which a pkgAcquire object should retrieve a file or a collection of files. More...

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

Inheritance diagram for pkgAcquire::Item:
[legend]
Collaboration diagram for pkgAcquire::Item:
[legend]

## Classes

class | Private

## Public Types

enum | ItemState { StatIdle , StatFetching , StatDone , StatError , StatAuthError , StatTransientNetworkError }
| The current status of this item. More...

## Public Member Functions

virtual void | Failed (std::string const &Message, pkgAcquire::MethodConfig const *const Cnf)
| Invoked by the acquire worker when the object couldn't be fetched.
APT_HIDDEN void | FailMessage (std::string const &Message)
virtual bool | VerifyDone (std::string const &Message, pkgAcquire::MethodConfig const *const Cnf)
| Invoked by the acquire worker to check if the successfully fetched object is also the objected we wanted to have.
virtual void | Done (std::string const &Message, HashStringList const &Hashes, pkgAcquire::MethodConfig const *const Cnf)
| Invoked by the acquire worker when the object was fetched successfully.
virtual void | Start (std::string const &Message, unsigned long long const Size)
| Invoked when the worker starts to fetch this object.
virtual std::string | Custom600Headers () const
| Custom headers to be sent to the fetch process.
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 | DescURI () const =0
| A "descriptive" URI-like string.
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.
virtual HashStringList | GetExpectedHashes () const =0
std::string | HashSum () const
virtual bool | HashesRequired () 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 ()

## Public Attributes

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

enum | RenameOnErrorState { HashSumMismatch , SizeMismatch , InvalidFormat , SignatureError , NotClearsigned , MaximumSizeExceeded , PDiffError }

## Protected Member Functions

bool | RenameOnError (RenameOnErrorState const state)
| Rename failed file and set error.
virtual bool | QueueURI (ItemDesc &Item)
| Insert this item into its owner's queue.
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.
virtual std::string | GetFinalFilename () const
| Get the full pathname of the final file for the current URI.

## Protected Attributes

pkgAcquire *const | Owner
| The acquire object with which this item is associated.
pkgAcquire::ItemDesc | Desc
| The item that is currently being downloaded.

## Friends

class | pkgAcqMetaBase
class | pkgAcqMetaClearSig

## Detailed Description

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 also
  pkgAcquire

## Member Enumeration Documentation

## ItemState

enum ItemState

The current status of this item.

Enumerator
StatIdle | The item is waiting to be downloaded.
StatFetching | The item is currently being downloaded.
StatDone | The item has been successfully downloaded.
StatError | An error was encountered while downloading this item.
StatAuthError | The item was downloaded but its authenticity could not be verified.
StatTransientNetworkError | The item was could not be downloaded because of a transient network error (e.g. network down).

## Constructor & Destructor Documentation

## Item()

Item | ( | pkgAcquire *const | Owner | ) |

explicit

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

Parameters

  Owner | The new owner of this item.

References Complete, ExpectedAdditionalItems, FileSize, ID, Local, Owner, PartialSize, pkgAcquire::pkgAcquire(), QueueCounter, Retries, and StatIdle.

Referenced by pkgAcqArchive::pkgAcqArchive(), pkgAcqChangelog::pkgAcqChangelog(), pkgAcqChangelog::pkgAcqChangelog(), pkgAcqChangelog::pkgAcqChangelog(), pkgAcqFile::pkgAcqFile(), pkgAcqDiffIndex::QueueURI(), pkgAcqMetaBase::QueueURI(), pkgAcqTransactionItem::QueueURI(), and QueueURI().

## Member Function Documentation

## Custom600Headers()

std::string Custom600Headers | ( |  | ) | const

virtual

Custom headers to be sent to the fetch process.

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

Reimplemented in pkgAcqAuxFile, pkgAcqFile, pkgAcqIndex, pkgAcqIndexDiffs, pkgAcqIndexMergeDiffs, pkgAcqMetaBase, pkgAcqMetaClearSig, and pkgAcqMetaSig.

Referenced by pkgAcqFile::Custom600Headers(), pkgAcqIndex::Custom600Headers(), pkgAcqIndexDiffs::Custom600Headers(), pkgAcqIndexMergeDiffs::Custom600Headers(), pkgAcqMetaBase::Custom600Headers(), pkgAcqMetaSig::Custom600Headers(), and pkgAcquire::Worker::QueueItem().

## DescURI()

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

pure virtual

A "descriptive" URI-like string.

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

Implemented in CleanupItem, NoActionItem, pkgAcqArchive, pkgAcqChangelog, pkgAcqDiffIndex, pkgAcqFile, pkgAcqIndex, pkgAcqIndexDiffs, pkgAcqIndexMergeDiffs, pkgAcqMetaIndex, and pkgAcqTransactionItem.

Referenced by pkgAcquire::Worker::RunMessages(), and ShortDesc().

## Done()

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

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 in pkgAcqArchive, pkgAcqAuxFile, pkgAcqChangelog, pkgAcqDiffIndex, pkgAcqFile, pkgAcqIndex, pkgAcqIndexDiffs, pkgAcqIndexMergeDiffs, pkgAcqMetaClearSig, pkgAcqMetaIndex, and pkgAcqMetaSig.

References pkgAcquire::Dequeue(), ErrorText, FileSize, and StatDone.

## Failed()

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

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 in pkgAcqArchive, pkgAcqAuxFile, pkgAcqBaseIndex, pkgAcqChangelog, pkgAcqDiffIndex, pkgAcqIndex, pkgAcqIndexDiffs, pkgAcqIndexMergeDiffs, pkgAcqMetaClearSig, pkgAcqMetaIndex, and pkgAcqMetaSig.

References Complete, pkgAcquire::Dequeue(), pkgAcquire::MethodConfig::LocalOnly, QueueCounter, StatAuthError, StatDone, StatError, StatFetching, StatIdle, and StatTransientNetworkError.

Referenced by pkgAcqAuxFile::Failed(), pkgAcqBaseIndex::Failed(), and pkgAcqMetaIndex::Failed().

## Finished()

void Finished | ( |  | ) |

virtual

Invoked by the worker when the download is completely done.

Reimplemented in pkgAcqArchive, pkgAcqAuxFile, and pkgAcqMetaClearSig.

Referenced by pkgAcquire::Run().

## GetExpectedHashes()

virtual HashStringList GetExpectedHashes | ( |  | ) | const

pure virtual

Returns
  HashSums the DestFile is supposed to have in this stage

Implemented in CleanupItem, NoActionItem, pkgAcqArchive, pkgAcqChangelog, pkgAcqFile, pkgAcqIndexDiffs, pkgAcqIndexMergeDiffs, pkgAcqMetaBase, and pkgAcqTransactionItem.

Referenced by HashSum(), and pkgAcquire::Worker::QueueItem().

## GetFinalFilename()

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

protected virtual

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

Reimplemented in pkgAcqArchive, pkgAcqBaseIndex, pkgAcqDiffIndex, pkgAcqIndex, pkgAcqMetaBase, and pkgAcqMetaSig.

References Desc.

Referenced by pkgAcqTransactionItem::QueueURI().

## GetOwner()

APT_PURE pkgAcquire * GetOwner | ( |  | ) | const

Returns
  the acquire process with which this item is associated.

References Owner, and pkgAcquire::pkgAcquire().

## HashesRequired()

virtual bool HashesRequired | ( |  | ) | const

inline virtual

Returns
  if having no hashes is a hard failure or not

Idealy this is always true for every subclass, but thanks to historical grow we don't have hashes for all files in all cases in all steps, so it is slightly more complicated than it should be.

Reimplemented in pkgAcqArchive, pkgAcqChangelog, pkgAcqFile, pkgAcqIndexDiffs, pkgAcqIndexMergeDiffs, pkgAcqMetaBase, pkgAcqMetaSig, and pkgAcqTransactionItem.

## HashSum()

std::string HashSum | ( |  | ) | const

Returns
  the 'best' hash for display proposes like –print-uris

References HashStringList::find(), and GetExpectedHashes().

## IsTrusted()

APT_PURE bool IsTrusted | ( |  | ) | const

virtual

Returns
  true if this object is being fetched from a trusted source.

Reimplemented in pkgAcqArchive.

## QueueURI()

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

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 in pkgAcqDiffIndex, pkgAcqMetaBase, and pkgAcqTransactionItem.

References Item(), and Owner.

Referenced by pkgAcqFile::Done(), pkgAcqFile::pkgAcqFile(), pkgAcqMetaBase::QueueURI(), and pkgAcqTransactionItem::QueueURI().

## Rename()

bool Rename | ( | std::string const & | From,
|  | std::string const & | To )

protected

Rename a file without modifying its timestamp.

Many item methods call this as their final action.

Parameters

  From | The file to be renamed.
  To | The new name of From. If To exists it will be overwritten. If From and To are equal nothing happens.

References ErrorText, and StatError.

Referenced by pkgAcqArchive::Done(), pkgAcqChangelog::Done(), pkgAcqIndexDiffs::Done(), pkgAcqIndexMergeDiffs::Done(), pkgAcqAuxFile::Failed(), pkgAcqIndexDiffs::Failed(), pkgAcqIndexMergeDiffs::Failed(), pkgAcqMetaClearSig::Failed(), pkgAcqMetaSig::Failed(), and RenameOnError().

## RenameOnError()

bool RenameOnError | ( | RenameOnErrorState const | state | ) |

protected

Rename failed file and set error.

Parameters

  state | respresenting the error we encountered

References DestFile, ErrorText, Rename(), StatAuthError, and StatError.

Referenced by pkgAcqDiffIndex::Failed(), pkgAcqIndexDiffs::Failed(), pkgAcqIndexMergeDiffs::Failed(), and pkgAcqMetaClearSig::VerifyDone().

## SetActiveSubprocess()

void SetActiveSubprocess | ( | std::string const & | subprocess | ) |

Set the name of the current active subprocess.

See also ActiveSubprocess

References ActiveSubprocess.

Referenced by pkgAcqIndexDiffs::Done(), pkgAcqIndexMergeDiffs::Done(), and pkgAcqIndex::StageDownloadDone().

## ShortDesc()

std::string ShortDesc | ( |  | ) | const

virtual

Short item description.

Returns
  a brief description of the object being fetched.

Reimplemented in pkgAcqArchive.

References DescURI().

Referenced by pkgAcqMetaIndex::Init(), and pkgAcqFile::pkgAcqFile().

## Start()

void Start | ( | std::string const & | Message,
|  | unsigned long long const | Size )

virtual

Invoked when the worker starts to fetch this object.

Parameters

  Message | RFC822-formatted data from the worker process. Use LookupTag() to parse it.
  Hashes | The expected hashes of the object being fetched.

See also
  pkgAcqMethod

References Complete, ErrorText, FileSize, and StatFetching.

## VerifyDone()

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

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 in pkgAcqDiffIndex, and pkgAcqMetaClearSig.

References ErrorText, and StatError.

## Member Data Documentation

## Complete

bool Complete

If true, the entire object has been successfully fetched.

Subclasses should set this to true when appropriate.

Referenced by pkgAcqArchive::Done(), pkgAcqChangelog::Done(), pkgAcqDiffIndex::Done(), pkgAcqFile::Done(), pkgAcqIndexMergeDiffs::Done(), Failed(), pkgAcqArchive::Finished(), Item(), pkgAcqMetaSig::pkgAcqMetaSig(), pkgAcquire::Worker::RunMessages(), pkgAcqIndex::StageDownloadDone(), and Start().

## ExpectedAdditionalItems

unsigned int ExpectedAdditionalItems

The number of additional fetch items that are expected once this item is done.

Some items like pkgAcqMeta{Index,Sig} will queue additional items. This variable can be set by the methods if it knows in advance how many items to expect to get a more accurate progress.

Referenced by pkgAcqDiffIndex::Failed(), Item(), pkgAcqDiffIndex::ParseDiffIndex(), pkgAcqDiffIndex::pkgAcqDiffIndex(), pkgAcqMetaClearSig::pkgAcqMetaClearSig(), and pkgAcqMetaClearSig::QueueIndexes().

## ID

unsigned long ID

A client-supplied unique identifier.

This field is initialized to 0; it is meant to be filled in by clients that wish to use it to uniquely identify items.

APT progress reporting will store an ID there as shown in "Get:42 …"

Referenced by Item().

## Local

bool Local

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

Referenced by pkgAcqArchive::Done(), pkgAcqFile::Done(), pkgAcqIndexDiffs::Done(), pkgAcqIndexMergeDiffs::Done(), Item(), pkgAcquire::Worker::RunMessages(), and pkgAcqIndex::StageDownloadDone().

## QueueCounter

unsigned int QueueCounter

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.

See also
  pkgAcquire

Referenced by Failed(), Item(), and pkgAcquire::Queue::ItemDone().

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

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