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 <boost/function.hpp>
  17
  18 #include "zypp/base/ReferenceCounted.h"
  19 #include "zypp/base/NonCopyable.h"
  20 #include "zypp/base/PtrTypes.h"
  21 #include "zypp/media/MediaManager.h"
  22 #include "zypp/Pathname.h"
  23 #include "zypp/CheckSum.h"
  24 #include "zypp/OnMediaLocation.h"
  25
  26 ///////////////////////////////////////////////////////////////////
  27 namespace zypp
  28 { /////////////////////////////////////////////////////////////////
  29
  30     DEFINE_PTR_TYPE(MediaSetAccess);
  31
  32     ///////////////////////////////////////////////////////////////////
  33     //
  34     //  CLASS NAME : MediaSetAccess
  35     //
  36     /**
  37      * Media access layer responsible for handling files distributed on a set
  38      * of media.
  39      *
  40      * This is provided as a means to handle CD or DVD sets accessible through
  41      * dir, iso, nfs or other URL schemes other than cd/dvd (see
  42      * \ref MediaManager for info on different implemented media backends).
  43      * Currently it handles URLs containing cdN, CDN, dvdN, and DVDN strings,
  44      * where N is the number of particular media in the set.
  45      *
  46      * Examples:
  47      * \code
  48      * "iso:/?iso=/path/to/iso/images/openSUSE-10.3-Alpha2plus-DVD-x86_64-DVD1.iso"
  49      * "dir:/path/to/cdset/sources/openSUSE-10.3/Alpha2plus/CD1"
  50      * \endcode
  51      *
  52      * MediaSetAccess accesses files on desired media by rewriting
  53      * the original URL, replacing the digit (usually) 1 with requested media
  54      * number and uses \ref MediaManager to get the files from the new URL.
  55      *
  56      * Additionaly, each media number can be assined a media verifier which
  57      * checks if the media we are trying to access is the desired one. See
  58      * \ref MediaVerifierBase for more info.
  59      *
  60      * Code example:
  61      * \code
  62      * Url url("dir:/path/to/cdset/sources/openSUSE-10.3/Alpha2plus/CD1");
  63      *
  64      * MediaSetAccess access(url);
  65      *
  66      * access.setVerifier(1, media1VerifierRef);
  67      * access.setVerifier(2, media2VerifierRef);
  68      *
  69      * Pathname file1 = "/some/file/on/media1";
  70      * access.provideFile(1, file1);
  71      * Pathname file2 = "/some/file/on/media2";
  72      * access.provideFile(2, file1);
  73      *
  74      * \endcode
  75      */
  76     class MediaSetAccess : public base::ReferenceCounted, private base::NonCopyable
  77     {
  78       friend std::ostream & operator<<( std::ostream & str, const MediaSetAccess & obj );
  79
  80     public:
  81       /**
  82        * Creates a callback enabled media access for specified \a url.
  83        *
  84        * \param url
  85        * \param prefered_attach_point Prefered attach (mount) point. Use, if
  86        *        you want to mount the media to a specific directory.
  87        */
  88       MediaSetAccess( const Url &url, const Pathname & prefered_attach_point = "" );
  89       /** \overload Also taking a \ref label. */
  90       MediaSetAccess( const std::string & label_r, const Url &url, const Pathname & prefered_attach_point = "" );
  91       ~MediaSetAccess();
  92
  93       /**
  94        * Sets a \ref MediaVerifier verifier for given media number.
  95        */
  96       void setVerifier( unsigned media_nr, media::MediaVerifierRef verifier );
  97
  98       /**
  99        * The label identifing this media set and to be sent in a media change request.
 100        */
 101       const std::string & label() const
 102       { return _label; }
 103
 104       /**
 105        * Set the label identifing this media set and to be sent in a media change request.
 106        */
 107       void setLabel( const std::string & label_r )
 108       { _label = label_r; }
 109
 110       /**
 111        * Provides a file from a media location.
 112        *
 113        * \param on_media_file location of the file on media
 114        * \return local pathname of the requested file
 115        *
 116        * If \p on_media_file is marked as optional, then
 117        * in case of failure the user interaction callbacks
 118        * will be ignored and the exception will throw
 119        * inmediately.
 120        *
 121        * \throws MediaException if a problem occurs,
 122        *        see \ref media::MediaManager::provideFile()
 123        */
 124       Pathname provideFile( const OnMediaLocation & on_media_file );
 125
 126       /**
 127        * Provides \a file from media \a media_nr.
 128        *
 129        * \param file path to the file relative to media URL
 130        * \param media_nr the media number in the media set
 131        * \return local pathname of the requested file
 132        *
 133        * \throws MediaException if a problem occurs,
 134        *        see \ref media::MediaManager::provideFile()
 135        */
 136       Pathname provideFile(const Pathname & file, unsigned media_nr = 1 );
 137
 138       /**
 139        * Release file from media.
 140        * This signal that file is not needed anymore.
 141        *
 142        * \param on_media_file location of the file on media
 143        */
 144       void releaseFile( const OnMediaLocation & on_media_file );
 145
 146
 147       /**
 148        * Release file from media.
 149        * This signal that file is not needed anymore.
 150        *
 151        * \param file path to the file relative to media URL
 152        * \param media_nr the media number in the media set
 153        */
 154       void releaseFile(const Pathname & file, unsigned media_nr = 1 );
 155
 156       /**
 157        * Provides direcotry \a dir from media number \a media_nr.
 158        *
 159        * \param dir path to the directory relative to media URL
 160        * \param recursive whether to provide the whole directory subtree
 161        * \param media_nr the media number in the media set
 162        * \return local pathname of the requested directory
 163        *
 164        * \throws MediaException if a problem occurs,
 165        *        see \ref media::MediaManager::provideDir()
 166        *        and \ref media::MediaManager::provideDirTree()
 167        */
 168       Pathname provideDir(const Pathname & dir, bool recursive, unsigned media_nr = 1);
 169
 170       /**
 171        * check if a file exists on the specified media
 172        *
 173        * \param file file to check
 174        * \param media_nr Media number
 175        */
 176       bool doesFileExist(const Pathname & file, unsigned media_nr = 1 );
 177
 178       /**
 179        * Release all attached media of this set.
 180        *
 181        * \throws MediaNotOpenException for invalid access IDs.
 182        */
 183       void release();
 184
 185       /**
 186        * Replaces media number in specified url with given \a medianr.
 187        *
 188        * Media number in the URL is searched for with regex
 189        * <tt> "^(.*(cd|dvd))([0-9]+)(\\.iso)$" </tt> for iso scheme and
 190        * with <tt> "^(.*(cd|dvd))([0-9]+)(/?)$" </tt> for other schemes.
 191        *
 192        * For cd and dvd scheme it returns the original URL, as well as for
 193        * URL which do not match the above regexes.
 194        *
 195        * \param url_r   original URL
 196        * \param medianr requested media number
 197        * \return        rewritten URL if applicable, the original URL otherwise
 198        */
 199       static Url rewriteUrl (const Url & url_r, const media::MediaNr medianr);
 200
 201     protected:
 202       Pathname provideFileInternal(const Pathname & file, unsigned media_nr, bool checkonly, bool cached);
 203       media::MediaAccessId getMediaAccessId (media::MediaNr medianr);
 204       virtual std::ostream & dumpOn( std::ostream & str ) const;
 205
 206     private:
 207       /** Media or media set URL */
 208       Url _url;
 209
 210       /**
 211        * Prefered mount point.
 212        *
 213        * \see MediaManager::open(Url,Pathname)
 214        * \see MediaHandler::_attachPoint
 215        */
 216       Pathname _prefAttachPoint;
 217
 218       std::string _label;
 219
 220       typedef std::map<media::MediaNr, media::MediaAccessId> MediaMap;
 221       typedef std::map<media::MediaNr, media::MediaVerifierRef > VerifierMap;
 222
 223       /** Mapping between media number and Media Access ID */
 224       MediaMap _medias;
 225       /** Mapping between media number and corespondent verifier */
 226       VerifierMap _verifiers;
 227     };
 228     ///////////////////////////////////////////////////////////////////
 229
 230     /** \relates MediaSetAccess Stream output */
 231     inline std::ostream & operator<<( std::ostream & str, const MediaSetAccess & obj )
 232     { return obj.dumpOn( str ); }
 233
 234
 235 } // namespace zypp
 236 ///////////////////////////////////////////////////////////////////
 237 #endif // ZYPP_SOURCE_MediaSetAccess_H