zypp/MediaSetAccess.h

   1 /*---------------------------------------------------------------------\
   2 |                          ____ _   __ __ ___                          |
   3 |                         |__  / \ / / . \ . \                         |
   4 |                           / / \ V /|  _/  _/                         |
   5 |                          / /__ | | | | | |                           |
   6 |                         /_____||_| |_| |_|                           |
   7 |                                                                      |
   8 \---------------------------------------------------------------------*/
   9
  10 #ifndef ZYPP_MediaSetAccess_H
  11 #define ZYPP_MediaSetAccess_H
  12
  13 #include <iosfwd>
  14 #include <string>
  15 #include <vector>
  16 #include "zypp/base/Function.h"
  17
  18 #include "zypp/base/ReferenceCounted.h"
  19 #include "zypp/base/NonCopyable.h"
  20 #include "zypp/base/Flags.h"
  21 #include "zypp/base/PtrTypes.h"
  22 #include "zypp/media/MediaManager.h"
  23 #include "zypp/Pathname.h"
  24 #include "zypp/CheckSum.h"
  25 #include "zypp/OnMediaLocation.h"
  26
  27 ///////////////////////////////////////////////////////////////////
  28 namespace zypp
  29 { /////////////////////////////////////////////////////////////////
  30
  31     DEFINE_PTR_TYPE(MediaSetAccess);
  32
  33     ///////////////////////////////////////////////////////////////////
  34     //
  35     //  CLASS NAME : MediaSetAccess
  36     //
  37     /**
  38      * Media access layer responsible for handling files distributed on a set
  39      * of media with media change and abort/retry/ingore user callback handling.
  40      *
  41      * This is provided as a means to handle CD or DVD sets accessible through
  42      * dir, iso, nfs or other URL schemes other than cd/dvd (see
  43      * \ref MediaManager for info on different implemented media backends).
  44      * Currently it handles URLs ending on (case insensitive ) CD#, DVD# or MEDIA#,
  45      * where # is the number of a particular medium in the set.
  46      *
  47      * Examples:
  48      * \code
  49      * "iso:/?iso=/path/to/iso/images/openSUSE-10.3-Alpha2plus-DVD-x86_64-DVD1.iso"
  50      * "dir:/path/to/cdset/sources/openSUSE-10.3/Alpha2plus/CD1"
  51      * \endcode
  52      *
  53      * MediaSetAccess accesses files on the desired medium by rewriting
  54      * the original URL, replacing the digit (usually) 1 with requested media
  55      * number and uses \ref MediaManager to get the files from the new URL.
  56      *
  57      * NOTE: Access to medium #1 always uses the url passed to the CTOR!
  58      *
  59      * Additionaly, each media number can be assinged a media verifier which
  60      * checks if the media we are trying to access is the desired one. See
  61      * \ref MediaVerifierBase for more info.
  62      *
  63      * Code example:
  64      * \code
  65      * Url url("dir:/path/to/cdset/sources/openSUSE-10.3/Alpha2plus/CD1");
  66      *
  67      * MediaSetAccess access(url);
  68      *
  69      * access.setVerifier(1, media1VerifierRef);
  70      * access.setVerifier(2, media2VerifierRef);
  71      *
  72      * Pathname file1 = "/some/file/on/media1";
  73      * Pathname providedfile1 = access.provideFile(file1, 1);
  74      * Pathname file2 = "/some/file/on/media2";
  75      * Pathname providedfile2 = access.provideFile(file1, 2);
  76      *
  77      * \endcode
  78      */
  79     class MediaSetAccess : public base::ReferenceCounted, private base::NonCopyable
  80     {
  81       friend std::ostream & operator<<( std::ostream & str, const MediaSetAccess & obj );
  82
  83     public:
  84       /**
  85        * Creates a callback enabled media access for specified \a url.
  86        *
  87        * \param url
  88        * \param prefered_attach_point Prefered attach (mount) point. Use, if
  89        *        you want to mount the media to a specific directory.
  90        */
  91       MediaSetAccess( const Url &url, const Pathname & prefered_attach_point = "" );
  92       /** \overload Also taking a \ref label. */
  93       MediaSetAccess( const std::string & label_r, const Url &url, const Pathname & prefered_attach_point = "" );
  94       ~MediaSetAccess();
  95
  96       /**
  97        * Sets a \ref MediaVerifier verifier for given media number.
  98        */
  99       void setVerifier( unsigned media_nr, media::MediaVerifierRef verifier );
 100
 101       /**
 102        * The label identifing this media set and to be sent in a media change request.
 103        */
 104       const std::string & label() const
 105       { return _label; }
 106
 107       /**
 108        * Set the label identifing this media set and to be sent in a media change request.
 109        */
 110       void setLabel( const std::string & label_r )
 111       { _label = label_r; }
 112
 113       enum ProvideFileOption
 114       {
 115         /**
 116          * The user is not asked anything, and the error
 117          * exception is just propagated */
 118         PROVIDE_DEFAULT = 0x0,
 119         PROVIDE_NON_INTERACTIVE = 0x1
 120       };
 121       ZYPP_DECLARE_FLAGS(ProvideFileOptions,ProvideFileOption);
 122
 123       /**
 124        * Provides a file from a media location.
 125        *
 126        * \param resource location of the file on media
 127        * \return local pathname of the requested file
 128        *
 129        * \throws MediaException if a problem occured and user has chosen to
 130        *         abort the operation. The calling code should take care
 131        *         to quit the current operation.
 132        * \throws SkipRequestException if a problem occured and user has chosen
 133        *         to skip the current operation. The calling code should continue
 134        *         with the next one, if possible.
 135        *
 136        *
 137        * If the resource is marked as optional, no Exception is thrown
 138        * and Pathname() is returned
 139        *
 140        * the optional deltafile argument describes a file that can
 141        * be used for delta download algorithms.
 142        *
 143        * \note interaction with the user does not ocurr if
 144        * \ref ProvideFileOptions::NON_INTERACTIVE is set.
 145        *
 146        * \note OnMediaLocation::optional() hint has no effect on the transfer.
 147        *
 148        * \see zypp::media::MediaManager::provideFile()
 149        */
 150       Pathname provideFile( const OnMediaLocation & resource, ProvideFileOptions options = PROVIDE_DEFAULT, const Pathname &deltafile = Pathname() );
 151
 152       /**
 153        * Provides \a file from media \a media_nr.
 154        *
 155        * \param file path to the file relative to media URL
 156        * \param media_nr the media number in the media set
 157        * \return local pathname of the requested file
 158        *
 159        * \note interaction with the user does not ocurr if
 160        * \ref ProvideFileOptions::NON_INTERACTIVE is set.
 161        *
 162        * \note OnMediaLocation::optional() hint has no effect on the transfer.
 163        *
 164        * \throws MediaException if a problem occured and user has chosen to
 165        *         abort the operation. The calling code should take care
 166        *         to quit the current operation.
 167        * \throws SkipRequestException if a problem occured and user has chosen
 168        *         to skip the current operation. The calling code should continue
 169        *         with the next one, if possible.
 170        * \see zypp::media::MediaManager::provideFile()
 171        */
 172       Pathname provideFile(const Pathname & file, unsigned media_nr = 1, ProvideFileOptions options = PROVIDE_DEFAULT );
 173
 174       /**
 175        * Release file from media.
 176        * This signal that file is not needed anymore.
 177        *
 178        * \param resource location of the file on media
 179        */
 180       void releaseFile( const OnMediaLocation &resource );
 181
 182
 183       /**
 184        * Release file from media.
 185        * This signal that file is not needed anymore.
 186        *
 187        * \param file path to the file relative to media URL
 188        * \param media_nr the media number in the media set
 189        */
 190       void releaseFile(const Pathname & file, unsigned media_nr = 1 );
 191
 192       /**
 193        * Provides direcotry \a dir from media number \a media_nr.
 194        *
 195        * \param dir path to the directory relative to media URL
 196        * \param recursive whether to provide the whole directory subtree
 197        * \param media_nr the media number in the media set
 198        * \return local pathname of the requested directory
 199        *
 200        * \throws MediaException if a problem occured and user has chosen to
 201        *         abort the operation. The calling code should take care
 202        *         to quit the current operation.
 203        * \todo throw SkipRequestException if a problem occured and user has chosen
 204        *         to skip the current operation. The calling code should continue
 205        *         with the next one, if possible.
 206        * \see zypp::media::MediaManager::provideDir()
 207        * \see zypp::media::MediaManager::provideDirTree()
 208        */
 209       Pathname provideDir(const Pathname & dir, bool recursive, unsigned media_nr = 1, ProvideFileOptions options = PROVIDE_DEFAULT );
 210
 211       /**
 212        * Checks if a file exists on the specified media, with user callbacks.
 213        *
 214        * \param file file to check
 215        * \param media_nr Media number
 216        *
 217        * \throws MediaException if a problem occured and user has chosen to
 218        *         abort the operation. The calling code should take care
 219        *         to quit the current operation.
 220        * \throws SkipRequestException if a problem occured and user has chosen
 221        *         to skip the current operation. The calling code should continue
 222        *         with the next one, if possible.
 223        * \see zypp::media::MediaManager::doesFileExist(MediaAccessId,const Pathname&)
 224        */
 225       bool doesFileExist(const Pathname & file, unsigned media_nr = 1 );
 226
 227       /**
 228        * Fills \ref retlist with directory information.
 229        */
 230       void dirInfo( filesystem::DirContent &retlist, const Pathname &dirname,
 231                     bool dots = true, unsigned media_nr = 1 );
 232
 233       /**
 234        * Release all attached media of this set.
 235        *
 236        * \throws MediaNotOpenException for invalid access IDs.
 237        */
 238       void release();
 239
 240       /**
 241        * Replaces media number in specified url with given \a medianr.
 242        *
 243        * Media number in the URL is searched for with regex
 244        * <tt> "^(.*(cd|dvd|media))([0-9]+)(\\.iso)$" </tt> for iso scheme and
 245        * with <tt> "^(.*(cd|dvd|media))([0-9]+)(/?)$" </tt> for other schemes.
 246        *
 247        * For cd and dvd scheme it returns the original URL, as well as for
 248        * URL which do not match the above regexes.
 249        *
 250        * \param url_r   original URL
 251        * \param medianr requested media number
 252        * \return        rewritten URL if applicable, the original URL otherwise
 253        */
 254       static Url rewriteUrl (const Url & url_r, const media::MediaNr medianr);
 255
 256     protected:
 257       /**
 258        * Provides the \a file from medium number \a media_nr and returns its
 259        * local path.
 260        *
 261        * \note   The method must not throw if \a checkonly is <tt>true</tt>.
 262        *
 263        * \throws MediaException \a checkonly is <tt>false</tt> and
 264        *         a problem occured and user has chosen to
 265        *         abort the operation. The calling code should take care
 266        *         to quit the current operation.
 267        * \throws SkipRequestException \a checkonly is <tt>false</tt> and
 268        *         a problem occured and user has chosen
 269        *         to skip the current operation. The calling code should continue
 270        *         with the next one, if possible.
 271        */
 272       Pathname provideFileInternal( const OnMediaLocation &resource, ProvideFileOptions options );
 273
 274       typedef function<void( media::MediaAccessId, const Pathname & )> ProvideOperation;
 275
 276       void provide( ProvideOperation op, const OnMediaLocation &resource, ProvideFileOptions options, const Pathname &deltafile );
 277
 278       media::MediaAccessId getMediaAccessId (media::MediaNr medianr);
 279       virtual std::ostream & dumpOn( std::ostream & str ) const;
 280
 281     private:
 282       /** Media or media set URL */
 283       Url _url;
 284
 285       /**
 286        * Prefered mount point.
 287        *
 288        * \see MediaManager::open(Url,Pathname)
 289        * \see MediaHandler::_attachPoint
 290        */
 291       Pathname _prefAttachPoint;
 292
 293       std::string _label;
 294
 295       typedef std::map<media::MediaNr, media::MediaAccessId> MediaMap;
 296       typedef std::map<media::MediaNr, media::MediaVerifierRef > VerifierMap;
 297
 298       /** Mapping between media number and Media Access ID */
 299       MediaMap _medias;
 300       /** Mapping between media number and corespondent verifier */
 301       VerifierMap _verifiers;
 302     };
 303     ///////////////////////////////////////////////////////////////////
 304     ZYPP_DECLARE_OPERATORS_FOR_FLAGS(MediaSetAccess::ProvideFileOptions);
 305
 306     /** \relates MediaSetAccess Stream output */
 307     inline std::ostream & operator<<( std::ostream & str, const MediaSetAccess & obj )
 308     { return obj.dumpOn( str ); }
 309
 310
 311 } // namespace zypp
 312 ///////////////////////////////////////////////////////////////////
 313 #endif // ZYPP_SOURCE_MediaSetAccess_H