apt @VERSION@
Public Types | Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes

pkgAcquire::Item Class Reference

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

#include <acquire-item.h>

Inheritance diagram for pkgAcquire::Item:
WeakPointable pkgAcqArchive pkgAcqDiffIndex pkgAcqFile pkgAcqIndex pkgAcqIndexDiffs pkgAcqMetaIndex pkgAcqMetaSig pkgAcqSubIndex

List of all members.

Public Types

enum  ItemState {
  StatIdle, StatFetching, StatDone, StatError,
  StatAuthError, StatTransientNetworkError
}
 

The current status of this item.

More...

Public Member Functions

virtual void Failed (string Message, pkgAcquire::MethodConfig *Cnf)
 Invoked by the acquire worker when the object couldn't be fetched.
virtual void Done (string Message, unsigned long Size, string Hash, pkgAcquire::MethodConfig *Cnf)
 Invoked by the acquire worker when the object was fetched successfully.
virtual void Start (string Message, unsigned long Size)
 Invoked when the worker starts to fetch this object.
virtual string Custom600Headers ()
 Custom headers to be sent to the fetch process.
virtual string DescURI ()=0
 A "descriptive" URI-like string.
virtual string ShortDesc ()
 Short item description.
virtual void Finished ()
 Invoked by the worker when the download is completely done.
virtual string HashSum ()
 HashSum.
pkgAcquireGetOwner ()
virtual bool IsTrusted ()
void ReportMirrorFailure (string FailCode)
 Report mirror problem.
 Item (pkgAcquire *Owner)
 Initialize an item.
virtual ~Item ()
 Remove this item from its owner's queue by invoking pkgAcquire::Remove.

Public Attributes

enum pkgAcquire::Item::ItemState Status
string ErrorText
 Contains a textual description of the error encountered if #Status 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.
const char * Mode
 If not NULL, contains the name of a subprocess that is operating on this object (for instance, "gzip" or "gpgv").
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".
string UsedMirror
unsigned int QueueCounter
 The number of fetch queues into which this item has been inserted.
string DestFile
 The name of the file into which the retrieved object will be written.

Protected Member Functions

void QueueURI (ItemDesc &Item)
 Insert this item into its owner's queue.
void Dequeue ()
 Remove this item from its owner's queue.
void Rename (string From, string To)
 Rename a file without modifying its timestamp.

Protected Attributes

pkgAcquireOwner
 The acquire object with which this item is associated.

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

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 ( pkgAcquire Owner)

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.

Parameters:
OwnerThe new owner of this item.

References pkgAcquire::Add(), and StatIdle.


Member Function Documentation

virtual string Custom600Headers ( ) [inline, 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 pkgAcqSubIndex, pkgAcqDiffIndex, pkgAcqIndex, pkgAcqIndexTrans, pkgAcqMetaSig, pkgAcqMetaIndex, pkgAcqMetaClearSig, and pkgAcqFile.

Referenced by pkgAcquire::Worker::QueueItem().

virtual string DescURI ( ) [pure virtual]

A "descriptive" URI-like string.

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

Implemented in pkgAcqSubIndex, pkgAcqDiffIndex, pkgAcqIndexDiffs, pkgAcqIndex, pkgAcqMetaSig, pkgAcqMetaIndex, pkgAcqArchive, and pkgAcqFile.

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

virtual void Done ( string  Message,
unsigned long  Size,
string  Hash,
pkgAcquire::MethodConfig 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:
MessageData from the acquire method. Use LookupTag() to parse it.
SizeThe size of the object that was fetched.
HashThe HashSum of the object that was fetched.
CnfThe method via which the object was fetched.
See also:
pkgAcqMethod

Reimplemented in pkgAcqSubIndex, pkgAcqDiffIndex, pkgAcqIndexDiffs, pkgAcqIndex, pkgAcqMetaSig, pkgAcqMetaIndex, pkgAcqArchive, and pkgAcqFile.

Referenced by pkgAcquire::Worker::RunMessages().

virtual void Failed ( string  Message,
pkgAcquire::MethodConfig 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:
MessageAn RFC822-formatted message from the acquire method describing what went wrong. Use LookupTag() to parse it.
CnfThe method via which the worker tried to fetch this object.
See also:
pkgAcqMethod

Reimplemented in pkgAcqSubIndex, pkgAcqDiffIndex, pkgAcqIndexDiffs, pkgAcqIndex, pkgAcqIndexTrans, pkgAcqMetaSig, pkgAcqMetaIndex, pkgAcqMetaClearSig, pkgAcqArchive, and pkgAcqFile.

Referenced by pkgAcquire::Worker::RunMessages().

pkgAcquire* GetOwner ( ) [inline]
Returns:
the acquire process with which this item is associated.

References Owner.

Referenced by pkgAcquire::Worker::RunMessages().

virtual string HashSum ( ) [inline, virtual]

HashSum.

Returns:
the HashSum of this object, if applicable; otherwise, an empty string.

Reimplemented in pkgAcqIndex, pkgAcqArchive, and pkgAcqFile.

Referenced by pkgAcquire::Worker::RunMessages().

virtual bool IsTrusted ( ) [inline, virtual]
Returns:
true if this object is being fetched from a trusted source.

Reimplemented in pkgAcqArchive.

void QueueURI ( ItemDesc Item) [inline, protected]
void Rename ( string  From,
string  To 
) [protected]

Rename a file without modifying its timestamp.

Many item methods call this as their final action.

Parameters:
FromThe file to be renamed.
ToThe new name of #From. If #To exists it will be overwritten.

Referenced by pkgAcqMetaIndex::AuthDone(), and pkgAcqMetaSig::pkgAcqMetaSig().

void ReportMirrorFailure ( string  FailCode)

Report mirror problem.

This allows reporting mirror failures back to a centralized server. The apt-report-mirror-failure script is called for this

Parameters:
FailCodeA short failure string that is send
virtual string ShortDesc ( ) [inline, virtual]
virtual void Start ( string  Message,
unsigned long  Size 
) [virtual]

Invoked when the worker starts to fetch this object.

Parameters:
MessageRFC822-formatted data from the worker process. Use LookupTag() to parse it.
SizeThe size of the object being fetched.
See also:
pkgAcqMethod

Referenced by pkgAcquire::Worker::RunMessages().


Member Data Documentation

bool Complete

If true, the entire object has been successfully fetched.

Subclasses should set this to true when appropriate.

Referenced by pkgAcquire::Enqueue(), pkgAcqArchive::Finished(), pkgAcqDiffIndex::ParseDiffIndex(), pkgAcqArchive::QueueNext(), and pkgAcqMetaIndex::RetrievalDone().

unsigned long ID

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
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 pkgAcquire::Enqueue(), pkgAcqArchive::QueueNext(), and pkgAcqMetaIndex::RetrievalDone().

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 pkgAcquire::Queue::Dequeue(), pkgAcquire::Queue::Enqueue(), and pkgAcquire::Queue::ItemDone().


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