LTP GCOV extension - code coverage report
Current view: | directory - usr/include/apt-pkg - acquire.h
Test: | lcov.info
Date: | 2008-08-14 |  | Instrumented lines: | 5
Code covered: | 0.0 % |  | Executed lines: | 0

           1                 : // -*- mode: cpp; mode: fold -*-
           2                 : // Description                                                          /*{{{*/
           3                 : // $Id: acquire.h,v 1.29.2.1 2003/12/24 23:09:17 mdz Exp $
           4                 : /* ######################################################################
           5                 :
           6                 :    Acquire - File Acquiration
           7                 :
           8                 :    This module contians the Acquire system. It is responsible for bringing
           9                 :    files into the local pathname space. It deals with URIs for files and
          10                 :    URI handlers responsible for downloading or finding the URIs.
          11                 :
          12                 :    Each file to download is represented by an Acquire::Item class subclassed
          13                 :    into a specialization. The Item class can add itself to several URI
          14                 :    acquire queues each prioritized by the download scheduler. When the
          15                 :    system is run the proper URI handlers are spawned and the the acquire
          16                 :    queues are fed into the handlers by the schedular until the queues are
          17                 :    empty. This allows for an Item to be downloaded from an alternate source
          18                 :    if the first try turns out to fail. It also alows concurrent downloading
          19                 :    of multiple items from multiple sources as well as dynamic balancing
          20                 :    of load between the sources.
          21                 :
          22                 :    Schedualing of downloads is done on a first ask first get basis. This
          23                 :    preserves the order of the download as much as possible. And means the
          24                 :    fastest source will tend to process the largest number of files.
          25                 :
          26                 :    Internal methods and queues for performing gzip decompression,
          27                 :    md5sum hashing and file copying are provided to allow items to apply
          28                 :    a number of transformations to the data files they are working with.
          29                 :
          30                 :    ##################################################################### */
          31                 :                                                                         /*}}}*/
          32                 :
          33                 : /** \defgroup acquire Acquire system
          34                 :  *
          35                 :  *  \brief The Acquire system is responsible for retrieving files from
          36                 :  *  local or remote URIs and postprocessing them (for instance,
          37                 :  *  verifying their authenticity).  The core class in this system is
          38                 :  *  pkgAcquire, which is responsible for managing the download queues
          39                 :  *  during the download.  There is at least one download queue for
          40                 :  *  each supported protocol; protocols such as http may provide one
          41                 :  *  queue per host.
          42                 :  *
          43                 :  *  Each file to download is represented by a subclass of
          44                 :  *  pkgAcquire::Item.  The files add themselves to the download
          45                 :  *  queue(s) by providing their URI information to
          46                 :  *  pkgAcquire::Item::QueueURI, which calls pkgAcquire::Enqueue.
          47                 :  *
          48                 :  *  Once the system is set up, the Run method will spawn subprocesses
          49                 :  *  to handle the enqueued URIs; the scheduler will then take items
          50                 :  *  from the queues and feed them into the handlers until the queues
          51                 :  *  are empty.
          52                 :  *
          53                 :  *  \todo Acquire supports inserting an object into several queues at
          54                 :  *  once, but it is not clear what its behavior in this case is, and
          55                 :  *  no subclass of pkgAcquire::Item seems to actually use this
          56                 :  *  capability.
          57                 :  */
          58                 :
          59                 : /** \addtogroup acquire
          60                 :  *
          61                 :  *  @{
          62                 :  *
          63                 :  *  \file acquire.h
          64                 :  */
          65                 :
          66                 : #ifndef PKGLIB_ACQUIRE_H
          67                 : #define PKGLIB_ACQUIRE_H
          68                 :
          69                 : #include <vector>
          70                 : #include <string>
          71                 :
          72                 : using std::vector;
          73                 : using std::string;
          74                 :
          75                 :
          76                 : #include <sys/time.h>
          77                 : #include <unistd.h>
          78                 :
          79                 : class pkgAcquireStatus;
          80                 :
          81                 : /** \brief The core download scheduler.
          82                 :  *
          83                 :  *  This class represents an ongoing download.  It manages the lists
          84                 :  *  of active and pending downloads and handles setting up and tearing
          85                 :  *  down download-related structures.
          86                 :  *
          87                 :  *  \todo Why all the protected data items and methods?
          88                 :  */
          89                 : class pkgAcquire
          90                 : {
          91                 :    public:
          92                 :
          93                 :    class Item;
          94                 :    class Queue;
          95                 :    class Worker;
          96                 :    struct MethodConfig;
          97                 :    struct ItemDesc;
          98                 :    friend class Item;
          99                 :    friend class Queue;
         100                 :
         101                 :    typedef vector<Item *>::iterator ItemIterator;
         102                 :    typedef vector<Item *>::const_iterator ItemCIterator;
         103                 :
         104                 :    protected:
         105                 :
         106                 :    /** \brief A list of items to download.
         107                 :     *
         108                 :     *  This is built monotonically as items are created and only
         109                 :     *  emptied when the download shuts down.
         110                 :     */
         111                 :    vector<Item *> Items;
         112                 :
         113                 :    /** \brief The head of the list of active queues.
         114                 :     *
         115                 :     *  \todo why a hand-managed list of queues instead of std::list or
         116                 :     *  std::set?
         117                 :     */
         118                 :    Queue *Queues;
         119                 :
         120                 :    /** \brief The head of the list of active workers.
         121                 :     *
         122                 :     *  \todo why a hand-managed list of workers instead of std::list
         123                 :     *  or std::set?
         124                 :     */
         125                 :    Worker *Workers;
         126                 :
         127                 :    /** \brief The head of the list of acquire method configurations.
         128                 :     *
         129                 :     *  Each protocol (http, ftp, gzip, etc) via which files can be
         130                 :     *  fetched can have a representation in this list.  The
         131                 :     *  configuration data is filled in by parsing the 100 Capabilities
         132                 :     *  string output by a method on startup (see
         133                 :     *  pkgAcqMethod::pkgAcqMethod and pkgAcquire::GetConfig).
         134                 :     *
         135                 :     *  \todo why a hand-managed config dictionary instead of std::map?
         136                 :     */
         137                 :    MethodConfig *Configs;
         138                 :
         139                 :    /** \brief The progress indicator for this download. */
         140                 :    pkgAcquireStatus *Log;
         141                 :
         142                 :    /** \brief The total size of the files which are to be fetched.
         143                 :     *
         144                 :     *  This is not necessarily the total number of bytes to download
         145                 :     *  when, e.g., download resumption and list updates via patches
         146                 :     *  are taken into account.
         147                 :     */
         148                 :    unsigned long ToFetch;
         149                 :
         150                 :    // Configurable parameters for the scheduler
         151                 :
         152                 :    /** \brief Represents the queuing strategy for remote URIs. */
         153                 :    enum QueueStrategy {
         154                 :      /** \brief Generate one queue for each protocol/host combination; downloads from
         155                 :       *  multiple hosts can proceed in parallel.
         156                 :       */
         157                 :      QueueHost,
         158                 :      /** \brief Generate a single queue for each protocol; serialize
         159                 :       *  downloads from multiple hosts.
         160                 :       */
         161                 :      QueueAccess} QueueMode;
         162                 :
         163                 :    /** \brief If \b true, debugging information will be dumped to std::clog. */
         164                 :    bool Debug;
         165                 :    /** \brief If \b true, a download is currently in progress. */
         166                 :    bool Running;
         167                 :
         168                 :    /** \brief Add the given item to the list of items. */
         169                 :    void Add(Item *Item);
         170                 :
         171                 :    /** \brief Remove the given item from the list of items. */
         172                 :    void Remove(Item *Item);
         173                 :
         174                 :    /** \brief Add the given worker to the list of workers. */
         175                 :    void Add(Worker *Work);
         176                 :
         177                 :    /** \brief Remove the given worker from the list of workers. */
         178                 :    void Remove(Worker *Work);
         179                 :
         180                 :    /** \brief Insert the given fetch request into the appropriate queue.
         181                 :     *
         182                 :     *  \param Item The URI to download and the item to download it
         183                 :     *  for.  Copied by value into the queue; no reference to Item is
         184                 :     *  retained.
         185                 :     */
         186                 :    void Enqueue(ItemDesc &Item);
         187                 :
         188                 :    /** \brief Remove all fetch requests for this item from all queues. */
         189                 :    void Dequeue(Item *Item);
         190                 :
         191                 :    /** \brief Determine the fetch method and queue of a URI.
         192                 :     *
         193                 :     *  \param URI The URI to fetch.
         194                 :     *
         195                 :     *  \param[out] Config A location in which to place the method via
         196                 :     *  which the URI is to be fetched.
         197                 :     *
         198                 :     *  \return the string-name of the queue in which a fetch request
         199                 :     *  for the given URI should be placed.
         200                 :     */
         201                 :    string QueueName(string URI,MethodConfig const *&Config);
         202                 :
         203                 :    /** \brief Build up the set of file descriptors upon which select() should
         204                 :     *  block.
         205                 :     *
         206                 :     *  The default implementation inserts the file descriptors
         207                 :     *  corresponding to active downloads.
         208                 :     *
         209                 :     *  \param[out] Fd The largest file descriptor in the generated sets.
         210                 :     *
         211                 :     *  \param[out] RSet The set of file descriptors that should be
         212                 :     *  watched for input.
         213                 :     *
         214                 :     *  \param[out] WSet The set of file descriptors that should be
         215                 :     *  watched for output.
         216                 :     */
         217                 :    virtual void SetFds(int &Fd,fd_set *RSet,fd_set *WSet);
         218                 :
         219                 :    /** Handle input from and output to file descriptors which select()
         220                 :     *  has determined are ready.  The default implementation
         221                 :     *  dispatches to all active downloads.
         222                 :     *
         223                 :     *  \param RSet The set of file descriptors that are ready for
         224                 :     *  input.
         225                 :     *
         226                 :     *  \param WSet The set of file descriptors that are ready for
         227                 :     *  output.
         228                 :     */
         229                 :    virtual void RunFds(fd_set *RSet,fd_set *WSet);
         230                 :
         231                 :    /** \brief Check for idle queues with ready-to-fetch items.
         232                 :     *
         233                 :     *  Called by pkgAcquire::Queue::Done each time an item is dequeued
         234                 :     *  but remains on some queues; i.e., another queue should start
         235                 :     *  fetching it.
         236                 :     */
         237                 :    void Bump();
         238                 :
         239                 :    public:
         240                 :
         241                 :    /** \brief Retrieve information about a fetch method by name.
         242                 :     *
         243                 :     *  \param Access The name of the method to look up.
         244                 :     *
         245                 :     *  \return the method whose name is Access, or \b NULL if no such method exists.
         246                 :     */
         247                 :    MethodConfig *GetConfig(string Access);
         248                 :
         249                 :    /** \brief Provides information on how a download terminated. */
         250                 :    enum RunResult {
         251                 :      /** \brief All files were fetched successfully. */
         252                 :      Continue,
         253                 :
         254                 :      /** \brief Some files failed to download. */
         255                 :      Failed,
         256                 :
         257                 :      /** \brief The download was cancelled by the user (i.e., #Log's
         258                 :       *  pkgAcquireStatus::Pulse() method returned \b false).
         259                 :       */
         260                 :      Cancelled};
         261                 :
         262                 :    /** \brief Download all the items that have been Add()ed to this
         263                 :     *  download process.
         264                 :     *
         265                 :     *  This method will block until the download completes, invoking
         266                 :     *  methods on #Log to report on the progress of the download.
         267                 :     *
         268                 :     *  \param PulseInterval The method pkgAcquireStatus::Pulse will be
         269                 :     *  invoked on #Log at intervals of PulseInterval milliseconds.
         270                 :     *
         271                 :     *  \return the result of the download.
         272                 :     */
         273                 :    RunResult Run(int PulseInterval=500000);
         274                 :
         275                 :    /** \brief Remove all items from this download process, terminate
         276                 :     *  all download workers, and empty all queues.
         277                 :     */
         278                 :    void Shutdown();
         279                 :
         280                 :    /** \brief Get the first #Worker object.
         281                 :     *
         282                 :     *  \return the first active worker in this download process.
         283                 :     */
         284                 :    inline Worker *WorkersBegin() {return Workers;};
         285                 :
         286                 :    /** \brief Advance to the next #Worker object.
         287                 :     *
         288                 :     *  \return the worker immediately following I, or \b NULL if none
         289                 :     *  exists.
         290                 :     */
         291                 :    Worker *WorkerStep(Worker *I);
         292                 :
         293                 :    /** \brief Get the head of the list of items. */
         294                 :    inline ItemIterator ItemsBegin() {return Items.begin();};
         295                 :
         296                 :    /** \brief Get the end iterator of the list of items. */
         297                 :    inline ItemIterator ItemsEnd() {return Items.end();};
         298                 :
         299                 :    // Iterate over queued Item URIs
         300                 :    class UriIterator;
         301                 :    /** \brief Get the head of the list of enqueued item URIs.
         302                 :     *
         303                 :     *  This iterator will step over every element of every active
         304                 :     *  queue.
         305                 :     */
         306                 :    UriIterator UriBegin();
         307                 :    /** \brief Get the end iterator of the list of enqueued item URIs. */
         308                 :    UriIterator UriEnd();
         309                 :
         310                 :    /** Deletes each entry in the given directory that is not being
         311                 :     *  downloaded by this object.  For instance, when downloading new
         312                 :     *  list files, calling Clean() will delete the old ones.
         313                 :     *
         314                 :     *  \param Dir The directory to be cleaned out.
         315                 :     *
         316                 :     *  \return \b true if the directory exists and is readable.
         317                 :     */
         318                 :    bool Clean(string Dir);
         319                 :
         320                 :    /** \return the total size in bytes of all the items included in
         321                 :     *  this download.
         322                 :     */
         323                 :    double TotalNeeded();
         324                 :
         325                 :    /** \return the size in bytes of all non-local items included in
         326                 :     *  this download.
         327                 :     */
         328                 :    double FetchNeeded();
         329                 :
         330                 :    /** \return the amount of data to be fetched that is already
         331                 :     *  present on the filesystem.
         332                 :     */
         333                 :    double PartialPresent();
         334                 :
         335                 :    /** \brief Construct a new pkgAcquire.
         336                 :     *
         337                 :     *  \param Log The progress indicator associated with this
         338                 :     *  download, or \b NULL for none.  This object is not owned by the
         339                 :     *  download process and will not be deleted when the pkgAcquire
         340                 :     *  object is destroyed.  Naturally, it should live for at least as
         341                 :     *  long as the pkgAcquire object does.
         342                 :     */
         343                 :    pkgAcquire(pkgAcquireStatus *Log = 0);
         344                 :
         345                 :    /** \brief Destroy this pkgAcquire object.
         346                 :     *
         347                 :     *  Destroys all queue, method, and item objects associated with
         348                 :     *  this download.
         349                 :     */
         350                 :    virtual ~pkgAcquire();
         351                 : };
         352                 :
         353                 : /** \brief Represents a single download source from which an item
         354                 :  *  should be downloaded.
         355                 :  *
         356                 :  *  An item may have several assocated ItemDescs over its lifetime.
         357                 :  */
         358                 : struct pkgAcquire::ItemDesc
         359                 : {
         360                 :    /** \brief The URI from which to download this item. */
         361                 :    string URI;
         362                 :    /** brief A description of this item. */
         363                 :    string Description;
         364                 :    /** brief A shorter description of this item. */
         365                 :    string ShortDesc;
         366                 :    /** brief The underlying item which is to be downloaded. */
         367                 :    Item *Owner;
         368                 : };
         369                 :
         370                 : /** \brief A single download queue in a pkgAcquire object.
         371                 :  *
         372                 :  *  \todo Why so many protected values?
         373                 :  */
         374                 : class pkgAcquire::Queue
         375                 : {
         376                 :    friend class pkgAcquire;
         377                 :    friend class pkgAcquire::UriIterator;
         378                 :    friend class pkgAcquire::Worker;
         379                 :
         380                 :    /** \brief The next queue in the pkgAcquire object's list of queues. */
         381                 :    Queue *Next;
         382                 :
         383                 :    protected:
         384                 :
         385                 :    /** \brief A single item placed in this queue. */
         386                 :    struct QItem : pkgAcquire::ItemDesc
         387                 :    {
         388                 :       /** \brief The next item in the queue. */
         389                 :       QItem *Next;
         390                 :       /** \brief The worker associated with this item, if any. */
         391                 :       pkgAcquire::Worker *Worker;
         392                 :
         393                 :       /** \brief Assign the ItemDesc portion of this QItem from
         394                 :        *  another ItemDesc
         395                 :        */
         396                 :       void operator =(pkgAcquire::ItemDesc const &I)
         397                 :       {
         398                 :          URI = I.URI;
         399                 :          Description = I.Description;
         400                 :          ShortDesc = I.ShortDesc;
         401                 :          Owner = I.Owner;
         402                 :       };
         403                 :    };
         404                 :
         405                 :    /** \brief The name of this queue. */
         406                 :    string Name;
         407                 :
         408                 :    /** \brief The head of the list of items contained in this queue.
         409                 :     *
         410                 :     *  \todo why a by-hand list instead of an STL structure?
         411                 :     */
         412                 :    QItem *Items;
         413                 :
         414                 :    /** \brief The head of the list of workers associated with this queue.
         415                 :     *
         416                 :     *  \todo This is plural because support exists in Queue for
         417                 :     *  multiple workers.  However, it does not appear that there is
         418                 :     *  any way to actually associate more than one worker with a
         419                 :     *  queue.
         420                 :     *
         421                 :     *  \todo Why not just use a std::set?
         422                 :     */
         423                 :    pkgAcquire::Worker *Workers;
         424                 :
         425                 :    /** \brief the download scheduler with which this queue is associated. */
         426                 :    pkgAcquire *Owner;
         427                 :
         428                 :    /** \brief The number of entries in this queue that are currently
         429                 :     *  being downloaded.
         430                 :     */
         431                 :    signed long PipeDepth;
         432                 :
         433                 :    /** \brief The maximum number of entries that this queue will
         434                 :     *  attempt to download at once.
         435                 :     */
         436                 :    unsigned long MaxPipeDepth;
         437                 :
         438                 :    public:
         439                 :
         440                 :    /** \brief Insert the given fetch request into this queue.
         441                 :     *
         442                 :     *  \return \b true if the queuing was successful. May return
         443                 :     *  \b false if the Item is already in the queue
         444                 :     */
         445                 :    bool Enqueue(ItemDesc &Item);
         446                 :
         447                 :    /** \brief Remove all fetch requests for the given item from this queue.
         448                 :     *
         449                 :     *  \return \b true if at least one request was removed from the queue.
         450                 :     */
         451                 :    bool Dequeue(Item *Owner);
         452                 :
         453                 :    /** \brief Locate an item in this queue.
         454                 :     *
         455                 :     *  \param URI A URI to match against.
         456                 :     *  \param Owner A pkgAcquire::Worker to match against.
         457                 :     *
         458                 :     *  \return the first item in the queue whose URI is #URI and that
         459                 :     *  is being downloaded by #Owner.
         460                 :     */
         461                 :    QItem *FindItem(string URI,pkgAcquire::Worker *Owner);
         462                 :
         463                 :    /** Presumably this should start downloading an item?
         464                 :     *
         465                 :     *  \todo Unimplemented.  Implement it or remove?
         466                 :     */
         467                 :    bool ItemStart(QItem *Itm,unsigned long Size);
         468                 :
         469                 :    /** \brief Remove the given item from this queue and set its state
         470                 :     *  to pkgAcquire::Item::StatDone.
         471                 :     *
         472                 :     *  If this is the only queue containing the item, the item is also
         473                 :     *  removed from the main queue by calling pkgAcquire::Dequeue.
         474                 :     *
         475                 :     *  \param Itm The item to remove.
         476                 :     *
         477                 :     *  \return \b true if no errors are encountered.
         478                 :     */
         479                 :    bool ItemDone(QItem *Itm);
         480                 :
         481                 :    /** \brief Start the worker process associated with this queue.
         482                 :     *
         483                 :     *  If a worker process is already associated with this queue,
         484                 :     *  this is equivalent to calling Cycle().
         485                 :     *
         486                 :     *  \return \b true if the startup was successful.
         487                 :     */
         488                 :    bool Startup();
         489                 :
         490                 :    /** \brief Shut down the worker process associated with this queue.
         491                 :     *
         492                 :     *  \param Final If \b true, then the process is stopped unconditionally.
         493                 :     *               Otherwise, it is only stopped if it does not need cleanup
         494                 :     *               as indicated by the pkgAcqMethod::NeedsCleanup member of
         495                 :     *               its configuration.
         496                 :     *
         497                 :     *  \return \b true.
         498                 :     */
         499                 :    bool Shutdown(bool Final);
         500                 :
         501                 :    /** \brief Send idle items to the worker process.
         502                 :     *
         503                 :     *  Fills up the pipeline by inserting idle items into the worker's queue.
         504                 :     */
         505                 :    bool Cycle();
         506                 :
         507                 :    /** \brief Check for items that could be enqueued.
         508                 :     *
         509                 :     *  Call this after an item placed in multiple queues has gone from
         510                 :     *  the pkgAcquire::Item::StatFetching state to the
         511                 :     *  pkgAcquire::Item::StatIdle state, to possibly refill an empty queue.
         512                 :     *  This is an alias for Cycle().
         513                 :     *
         514                 :     *  \todo Why both this and Cycle()?  Are they expected to be
         515                 :     *  different someday?
         516                 :     */
         517                 :    void Bump();
         518                 :
         519                 :    /** \brief Create a new Queue.
         520                 :     *
         521                 :     *  \param Name The name of the new queue.
         522                 :     *  \param Owner The download process that owns the new queue.
         523                 :     */
         524                 :    Queue(string Name,pkgAcquire *Owner);
         525                 :
         526                 :    /** Shut down all the worker processes associated with this queue
         527                 :     *  and empty the queue.
         528                 :     */
         529                 :    ~Queue();
         530                 : };
         531                 :
         532                 : /** \brief Iterates over all the URIs being fetched by a pkgAcquire object. */
         533                 : class pkgAcquire::UriIterator
         534                 : {
         535                 :    /** The next queue to iterate over. */
         536                 :    pkgAcquire::Queue *CurQ;
         537                 :    /** The item that we currently point at. */
         538                 :    pkgAcquire::Queue::QItem *CurItem;
         539                 :
         540                 :    public:
         541                 :
         542                 :    inline void operator ++() {operator ++();};
         543                 :
         544                 :    void operator ++(int)
         545                 :    {
         546                 :       CurItem = CurItem->Next;
         547                 :       while (CurItem == 0 && CurQ != 0)
         548                 :       {
         549                 :          CurItem = CurQ->Items;
         550                 :          CurQ = CurQ->Next;
         551                 :       }
         552                 :    };
         553                 :
         554                 :    inline pkgAcquire::ItemDesc const *operator ->() const {return CurItem;};
         555                 :    inline bool operator !=(UriIterator const &rhs) const {return rhs.CurQ != CurQ || rhs.CurItem != CurItem;};
         556                 :    inline bool operator ==(UriIterator const &rhs) const {return rhs.CurQ == CurQ && rhs.CurItem == CurItem;};
         557                 :
         558                 :    /** \brief Create a new UriIterator.
         559                 :     *
         560                 :     *  \param Q The queue over which this UriIterator should iterate.
         561                 :     */
         562                 :    UriIterator(pkgAcquire::Queue *Q) : CurQ(Q), CurItem(0)
         563                 :    {
         564                 :       while (CurItem == 0 && CurQ != 0)
         565                 :       {
         566                 :          CurItem = CurQ->Items;
         567                 :          CurQ = CurQ->Next;
         568                 :       }
         569                 :    }
         570                 : };
         571                 :
         572                 : /** \brief Information about the properties of a single acquire method. */
         573                 : struct pkgAcquire::MethodConfig
         574                 : {
         575                 :    /** \brief The next link on the acquire method list.
         576                 :     *
         577                 :     *  \todo Why not an STL container?
         578                 :     */
         579                 :    MethodConfig *Next;
         580                 :
         581                 :    /** \brief The name of this acquire method (e.g., http). */
         582                 :    string Access;
         583                 :
         584                 :    /** \brief The implementation version of this acquire method. */
         585                 :    string Version;
         586                 :
         587                 :    /** \brief If \b true, only one download queue should be created for this
         588                 :     *  method.
         589                 :     */
         590                 :    bool SingleInstance;
         591                 :
         592                 :    /** \brief If \b true, this method supports pipelined downloading. */
         593                 :    bool Pipeline;
         594                 :
         595                 :    /** \brief If \b true, the worker process should send the entire
         596                 :     *  APT configuration tree to the fetch subprocess when it starts
         597                 :     *  up.
         598                 :     */
         599                 :    bool SendConfig;
         600                 :
         601                 :    /** \brief If \b true, this fetch method does not require network access;
         602                 :     *  all files are to be acquired from the local disk.
         603                 :     */
         604                 :    bool LocalOnly;
         605                 :
         606                 :    /** \brief If \b true, the subprocess has to carry out some cleanup
         607                 :     *  actions before shutting down.
         608                 :     *
         609                 :     *  For instance, the cdrom method needs to unmount the CD after it
         610                 :     *  finishes.
         611                 :     */
         612                 :    bool NeedsCleanup;
         613                 :
         614                 :    /** \brief If \b true, this fetch method acquires files from removable media. */
         615                 :    bool Removable;
         616                 :
         617                 :    /** \brief Set up the default method parameters.
         618                 :     *
         619                 :     *  All fields are initialized to NULL, "", or \b false as
         620                 :     *  appropriate.
         621                 :     */
         622                 :    MethodConfig();
         623                 : };
         624                 :
         625                 : /** \brief A monitor object for downloads controlled by the pkgAcquire class.
         626                 :  *
         627                 :  *  \todo Why protected members?
         628                 :  *
         629                 :  *  \todo Should the double members be uint64_t?
         630                 :  */
         631                 : class pkgAcquireStatus
         632                 : {
         633                 :    protected:
         634                 :
         635                 :    /** \brief The last time at which this monitor object was updated. */
         636                 :    struct timeval Time;
         637                 :
         638                 :    /** \brief The time at which the download started. */
         639                 :    struct timeval StartTime;
         640                 :
         641                 :    /** \brief The number of bytes fetched as of the previous call to
         642                 :     *  pkgAcquireStatus::Pulse, including local items.
         643                 :     */
         644                 :    double LastBytes;
         645                 :
         646                 :    /** \brief The current rate of download as of the most recent call
         647                 :     *  to pkgAcquireStatus::Pulse, in bytes per second.
         648                 :     */
         649                 :    double CurrentCPS;
         650                 :
         651                 :    /** \brief The number of bytes fetched as of the most recent call
         652                 :     *  to pkgAcquireStatus::Pulse, including local items.
         653                 :     */
         654                 :    double CurrentBytes;
         655                 :
         656                 :    /** \brief The total number of bytes that need to be fetched.
         657                 :     *
         658                 :     *  \warning This member is inaccurate, as new items might be
         659                 :     *  enqueued while the download is in progress!
         660                 :     */
         661                 :    double TotalBytes;
         662                 :
         663                 :    /** \brief The total number of bytes accounted for by items that
         664                 :     *  were successfully fetched.
         665                 :     */
         666                 :    double FetchedBytes;
         667                 :
         668                 :    /** \brief The amount of time that has elapsed since the download
         669                 :     *   started.
         670                 :     */
         671                 :    unsigned long ElapsedTime;
         672                 :
         673                 :    /** \brief The total number of items that need to be fetched.
         674                 :     *
         675                 :     *  \warning This member is inaccurate, as new items might be
         676                 :     *  enqueued while the download is in progress!
         677                 :     */
         678                 :    unsigned long TotalItems;
         679                 :
         680                 :    /** \brief The number of items that have been successfully downloaded. */
         681                 :    unsigned long CurrentItems;
         682                 :
         683                 :    public:
         684                 :
         685                 :    /** \brief If \b true, the download scheduler should call Pulse()
         686                 :     *  at the next available opportunity.
         687                 :     */
         688                 :    bool Update;
         689                 :
         690                 :    /** \brief If \b true, extra Pulse() invocations will be performed.
         691                 :     *
         692                 :     *  With this option set, Pulse() will be called every time that a
         693                 :     *  download item starts downloading, finishes downloading, or
         694                 :     *  terminates with an error.
         695                 :     */
         696                 :    bool MorePulses;
         697                 :
         698                 :    /** \brief Invoked when a local or remote file has been completely fetched.
         699                 :     *
         700                 :     *  \param Size The size of the file fetched.
         701                 :     *
         702                 :     *  \param ResumePoint How much of the file was already fetched.
         703                 :     */
         704                 :    virtual void Fetched(unsigned long Size,unsigned long ResumePoint);
         705                 :
         706                 :    /** \brief Invoked when the user should be prompted to change the
         707                 :     *         inserted removable media.
         708                 :     *
         709                 :     *  This method should not return until the user has confirmed to
         710                 :     *  the user interface that the media change is complete.
         711                 :     *
         712                 :     *  \param Media The name of the media type that should be changed.
         713                 :     *
         714                 :     *  \param Drive The identifying name of the drive whose media
         715                 :     *               should be changed.
         716                 :     *
         717                 :     *  \return \b true if the user confirms the media change, \b
         718                 :     *  false if it is cancelled.
         719                 :     *
         720                 :     *  \todo This is a horrible blocking monster; it should be CPSed
         721                 :     *  with prejudice.
         722                 :     */
         723                 :    virtual bool MediaChange(string Media,string Drive) = 0;
         724                 :
         725                 :    /** \brief Invoked when an item is confirmed to be up-to-date.
         726                 :
         727                 :     * For instance, when an HTTP download is informed that the file on
         728                 :     * the server was not modified.
         729                 :     */
         730               0 :    virtual void IMSHit(pkgAcquire::ItemDesc &/*Itm*/) {};
         731                 :
         732                 :    /** \brief Invoked when some of an item's data is fetched. */
         733               0 :    virtual void Fetch(pkgAcquire::ItemDesc &/*Itm*/) {};
         734                 :
         735                 :    /** \brief Invoked when an item is successfully and completely fetched. */
         736               0 :    virtual void Done(pkgAcquire::ItemDesc &/*Itm*/) {};
         737                 :
         738                 :    /** \brief Invoked when the process of fetching an item encounters
         739                 :     *  a fatal error.
         740                 :     */
         741               0 :    virtual void Fail(pkgAcquire::ItemDesc &/*Itm*/) {};
         742                 :
         743                 :    /** \brief Periodically invoked while the Acquire process is underway.
         744                 :     *
         745                 :     *  Subclasses should first call pkgAcquireStatus::Pulse(), then
         746                 :     *  update their status output.  The download process is blocked
         747                 :     *  while Pulse() is being called.
         748                 :     *
         749                 :     *  \return \b false if the user asked to cancel the whole Acquire process.
         750                 :     *
         751                 :     *  \see pkgAcquire::Run
         752                 :     */
         753                 :    virtual bool Pulse(pkgAcquire *Owner);
         754                 :
         755                 :    /** \brief Invoked when the Acquire process starts running. */
         756                 :    virtual void Start();
         757                 :
         758                 :    /** \brief Invoked when the Acquire process stops running. */
         759                 :    virtual void Stop();
         760                 :
         761                 :    /** \brief Initialize all counters to 0 and the time to the current time. */
         762                 :    pkgAcquireStatus();
         763               0 :    virtual ~pkgAcquireStatus() {};
         764                 : };
         765                 :
         766                 : /** @} */
         767                 :
         768                 : #endif

Generated by: LTP GCOV extension version 1.6