zypp/Fetcher.h

   1 /*---------------------------------------------------------------------\
   2 |                          ____ _   __ __ ___                          |
   3 |                         |__  / \ / / . \ . \                         |
   4 |                           / / \ V /|  _/  _/                         |
   5 |                          / /__ | | | | | |                           |
   6 |                         /_____||_| |_| |_|                           |
   7 |                                                                      |
   8 \---------------------------------------------------------------------*/
   9 /** \file       zypp/Fetcher.h
  10  *
  11 */
  12 #ifndef ZYPP_FETCHER_H
  13 #define ZYPP_FETCHER_H
  14
  15 #include <iosfwd>
  16 #include <list>
  17
  18 #include "zypp/base/Flags.h"
  19 #include "zypp/base/PtrTypes.h"
  20 #include "zypp/Pathname.h"
  21 #include "zypp/Url.h"
  22 #include "zypp/OnMediaLocation.h"
  23 #include "zypp/Digest.h"
  24 #include "zypp/MediaSetAccess.h"
  25 #include "zypp/FileChecker.h"
  26 #include "zypp/ProgressData.h"
  27
  28 ///////////////////////////////////////////////////////////////////
  29 namespace zypp
  30 { /////////////////////////////////////////////////////////////////
  31
  32   /**
  33   * This class allows to retrieve a group of files in a confortable
  34   * way, providing some smartness that does not belong to the
  35   * media layer like:
  36   *
  37   * \li Configurable local caches to retrieve already
  38   *     donwloaded files.
  39   * \li File checkers that can check for right checksums
  40   *     digital signatures, etc.
  41   *
  42   * \code
  43   * MediaSetAccess access(url, path);
  44   * Fetcher fetcher;
  45   * fetcher.enqueue( OnMediaLocation().setLocation("/somefile") );
  46   * fetcher.addCachePath("/tmp/cache")
  47   * fetcher.start( "/download-dir, access );
  48   * fetcher.reset();
  49   * \endcode
  50   *
  51   * To use the checkers. just create a functor implementing
  52   * bool operator()(const Pathname &file) \see FileChecker.
  53   * Pass the necessary validation data in the constructor
  54   * of the functor, and pass the object to the \ref enqueue
  55   * method.
  56   *
  57   * \code
  58   * ChecksumFileChecker checker(CheckSum("sha1", "....");
  59   * fetcher.enqueue( location, checker);
  60   * \endcode
  61   *
  62   * If you need to use more than one checker
  63   * \see CompositeFileChecker
  64   *
  65   * Additionally, you can automatically enqueue a job
  66   * with a checksum checker by using \ref enqueueDigested
  67   * which will use the \ref OnMediaLocation checksum
  68   * automatically.
  69   *
  70   * \code
  71   * location.setChecksum(CheckSum("sha1", "...."));
  72   * fetcher.enqueueDigested(location);
  73   * \endcode
  74   *
  75   * \note If the checksum of the location is empty, but
  76   * \ref enqueueDigested is used, then the user will get a
  77   * warning that the file has no checksum.
  78   *
  79   * Additionally, Fetcher supports checking the downloaded
  80   * content by using signed indexes on the remote side.
  81   *
  82   * \code
  83   * MediaSetAccess access(url, path);
  84   * Fetcher fetcher;
  85   * fetcher.addIndex(OnMediaLocation("/content"));
  86   * fetcher.enqueue( OnMediaLocation().setLocation("/somefile") );
  87   * fetcher.start( "/download-dir, access );
  88   * fetcher.reset();
  89   * \endcode
  90   *
  91   * Indexes are supported in SHA1SUMS format (simple text file)
  92   * with sha1sums and file name, or content file, whith
  93   * HASH SHA1 line entries.
  94   *
  95   * \note The indexes file names are relative to the directory
  96   * where the index is.
  97   */
  98   class Fetcher
  99   {
 100     friend std::ostream & operator<<( std::ostream & str,
 101                                       const Fetcher & obj );
 102   public:
 103     /** Implementation  */
 104     class Impl;
 105   public:
 106
 107     /**
 108      * Various option flags to change behavior
 109      */
 110     enum Option
 111     {
 112       /**
 113        * If a content file is found, it is
 114        * downloaded and read.
 115        */
 116       AutoAddContentFileIndexes = 0x0001,
 117       /**
 118        * If a SHA1SUMS file is found, it is
 119        * downloaded and read.
 120        */
 121       AutoAddSha1sumsIndexes = 0x0002,
 122       /**
 123        * If a content or SHA1SUMS file is found,
 124        * it is downloaded and read.
 125        */
 126       AutoAddIndexes = 0x0001 | 0x0002,
 127     };
 128     ZYPP_DECLARE_FLAGS(Options, Option);
 129
 130     /** Default ctor */
 131     Fetcher();
 132     /** Dtor */
 133     virtual ~Fetcher();
 134
 135   public:
 136
 137    /**
 138     * Set the Fetcher options
 139     * \see Fetcher::Options
 140     */
 141     void setOptions( Options options );
 142
 143    /**
 144     * Get current options
 145     * \see Fetcher::Options
 146     */
 147     Options options() const;
 148
 149    /**
 150     * Adds an index containing metadata (for example
 151     * checksums ) that will be retrieved and read
 152     * before the job processing starts.
 153     *
 154     * Nothing will be transfered or checked
 155     * until \ref start() is called.
 156     *
 157     * The index is relative to the media path, and
 158     * the listed files too.
 159     *
 160     * Indexes in the SHA1SUM format, and YaST
 161     * content file
 162     *
 163     * The file has to be signed or the user will be
 164     * warned that the file is unsigned. You can
 165     * place the signature next to the file adding the
 166     * .asc extension.
 167     *
 168     * If you expect the key to not to be in the target
 169     * system, then you can place it next to the index
 170     * using adding the .key extension.
 171     *
 172     */
 173     void addIndex( const OnMediaLocation &resource );
 174
 175    /**
 176     * Enqueue a object for transferal, they will not
 177     * be transfered until \ref start() is called
 178     *
 179     */
 180     void enqueue( const OnMediaLocation &resource,
 181                   const FileChecker &checker = FileChecker() );
 182
 183     /**
 184     * Enqueue a object for transferal, they will not
 185     * be transfered until \ref start() is called
 186     *
 187     * \note As \ref OnMediaLocation contains the digest information,
 188     * a \ref ChecksumFileChecker is automatically added to the
 189     * transfer job, so make sure you don't add another one or
 190     * the user could be asked twice.
 191     *
 192     * \todo FIXME implement checker == operator to avoid this.
 193     */
 194     void enqueueDigested( const OnMediaLocation &resource,
 195                           const FileChecker &checker = FileChecker() );
 196
 197
 198     /**
 199      * Enqueue a directory
 200      *
 201      * As the files to be enqueued are not known
 202      * in advance, all files whose checksum can
 203      * be found in some index are enqueued with
 204      * checksum checking. Otherwise they are not.
 205      *
 206      * Some index may provide
 207      * the checksums, either by \ref addIndex or
 208      * using \ref AutoAddIndexes flag.
 209      *
 210      * Files are checked by providing a
 211      * SHA1SUMS or content file listing
 212      * <checksum> filename
 213      * and a respective SHA1SUMS.asc/content.asc which has
 214      * the signature for the checksums.
 215      *
 216      * If you expect the user to not have the key of
 217      * the signature either in the trusted or untrusted
 218      * keyring, you can offer it as SHA1SUMS.key (or content.key)
 219      *
 220      * \param recursive True if the complete tree should
 221      * be enqueued.
 222      *
 223      * \note As \ref checksums are read from the index,
 224      * a \ref ChecksumFileChecker is automatically added to
 225      * transfer jobs having a checksum available,
 226      * so make sure you don't add another one or
 227      * the user could be asked twice.
 228      *
 229      * \note The format of the file SHA1SUMS is the output of:
 230      * ls | grep -v SHA1SUMS | xargs sha1sum > SHA1SUMS
 231      * in each subdirectory.
 232      *
 233      * \note Every file SHA1SUMS.* except of SHA1SUMS.(asc|key|(void)) will
 234      * not be transfered and will be ignored.
 235      *
 236      */
 237     void enqueueDir( const OnMediaLocation &resource,
 238                      bool recursive = false,
 239                      const FileChecker &checker = FileChecker() );
 240
 241     /**
 242      * Enqueue a directory and always check for
 243      * checksums.
 244      *
 245      * As the files to be enqueued are not known
 246      * in advance, all files are enqueued with
 247      * checksum checking. If the checksum of some file is
 248      * not in some index, then there will be a verification
 249      * warning ( \ref DigestReport ).
 250      *
 251      * Therefore some index will need to provide
 252      * the checksums, either by \ref addIndex or
 253      * using \ref AutoAddIndexes flag.
 254      *
 255      * Files are checked by providing a
 256      * SHA1SUMS or content file listing
 257      * <checksum> filename
 258      * and a respective SHA1SUMS.asc/content.asc which has
 259      * the signature for the checksums.
 260      *
 261      * If you expect the user to not have the key of
 262      * the signature either in the trusted or untrusted
 263      * keyring, you can offer it as SHA1SUMS.key (or content.key)
 264      *
 265      * \param recursive True if the complete tree should
 266      * be enqueued.
 267      *
 268      * \note As \ref checksums are read from the index,
 269      * a \ref ChecksumFileChecker is automatically added to every
 270      * transfer job, so make sure you don't add another one or
 271      * the user could be asked twice.
 272      *
 273      * \note The format of the file SHA1SUMS is the output of:
 274      * ls | grep -v SHA1SUMS | xargs sha1sum > SHA1SUMS
 275      * in each subdirectory.
 276      *
 277      * \note Every file SHA1SUMS.* except of SHA1SUMS.(asc|key|(void)) will
 278      * not be transfered and will be ignored.
 279      *
 280      */
 281     void enqueueDigestedDir( const OnMediaLocation &resource,
 282                              bool recursive = false,
 283                              const FileChecker &checker = FileChecker() );
 284
 285     /**
 286     * adds a directory to the list of directories
 287     * where to look for cached files
 288     */
 289     void addCachePath( const Pathname &cache_dir );
 290
 291     /**
 292      * Reset the transfer (jobs) list
 293      * \note It does not reset the cache directory list
 294      */
 295     void reset();
 296
 297     /**
 298     * start the transfer to a destination directory
 299     * \a dest_dir
 300     * You have to provde a media set access
 301     * \a media to get the files from
 302     * The file tree will be replicated inside this
 303     * directory
 304     *
 305     */
 306     void start( const Pathname &dest_dir,
 307                 MediaSetAccess &media,
 308                 const ProgressData::ReceiverFnc & progress = ProgressData::ReceiverFnc() );
 309
 310   private:
 311     /** Pointer to implementation */
 312     RWCOW_pointer<Impl> _pimpl;
 313   };
 314   ///////////////////////////////////////////////////////////////////
 315   ZYPP_DECLARE_OPERATORS_FOR_FLAGS(Fetcher::Options);
 316
 317   /** \relates Fetcher Stream output */
 318   std::ostream & operator<<( std::ostream & str, const Fetcher & obj );
 319
 320   /////////////////////////////////////////////////////////////////
 321 } // namespace zypp
 322 ///////////////////////////////////////////////////////////////////
 323 #endif // ZYPP_FETCHER_H