zypp/media/MediaManager.h

   1 /*---------------------------------------------------------------------\
   2 |                          ____ _   __ __ ___                          |
   3 |                         |__  / \ / / . \ . \                         |
   4 |                           / / \ V /|  _/  _/                         |
   5 |                          / /__ | | | | | |                           |
   6 |                         /_____||_| |_| |_|                           |
   7 |                                                                      |
   8 \---------------------------------------------------------------------*/
   9 /** \file zypp/media/MediaManager.h
  10  *
  11 */
  12 #ifndef ZYPP_MEDIA_MEDIAMANAGER_H
  13 #define ZYPP_MEDIA_MEDIAMANAGER_H
  14
  15 #include <zypp/media/MediaAccess.h>
  16
  17 #include <zypp/base/Deprecated.h>
  18 #include <zypp/base/NonCopyable.h>
  19 #include <zypp/base/PtrTypes.h>
  20 #include <zypp/Pathname.h>
  21 #include <zypp/Url.h>
  22
  23 #include <list>
  24
  25
  26 //////////////////////////////////////////////////////////////////////
  27 namespace zypp
  28 { ////////////////////////////////////////////////////////////////////
  29
  30   ////////////////////////////////////////////////////////////////////
  31   namespace media
  32   { //////////////////////////////////////////////////////////////////
  33
  34
  35     ///////////////////////////////////////////////////////////////////
  36     typedef zypp::RW_pointer<MediaAccess> MediaAccessRef;
  37
  38     // OBSOLETE HERE:
  39     typedef MediaAccessId                 MediaId;
  40     typedef unsigned int                  MediaNr;
  41
  42
  43     ///////////////////////////////////////////////////////////////////
  44     // forward declaration
  45     class MountEntry;
  46
  47
  48     ///////////////////////////////////////////////////////////////////
  49     //
  50     // CLASS NAME : MediaVerifierBase
  51     //
  52     /**
  53      * Interface to implement a media verifier.
  54      */
  55     class MediaVerifierBase //: private zypp::NonCopyable
  56     {
  57     public:
  58       MediaVerifierBase()
  59       {}
  60
  61       virtual
  62       ~MediaVerifierBase()
  63       {}
  64
  65       /*
  66       ** Check if the specified attached media contains
  67       ** the desired media (e.g. SLES10 CD1).
  68       */
  69       virtual bool
  70       isDesiredMedia(const MediaAccessRef &ref) = 0;
  71     };
  72
  73
  74     ///////////////////////////////////////////////////////////////////
  75     //
  76     // CLASS NAME : NoVerifier
  77     //
  78     /**
  79      * Dummy default media verifier, which is always happy.
  80      */
  81     class NoVerifier : public MediaVerifierBase
  82     {
  83     public:
  84       NoVerifier(): MediaVerifierBase()
  85       {}
  86
  87       virtual
  88       ~NoVerifier()
  89       {}
  90
  91       /*
  92       ** Don't check if the specified attached media contains
  93       ** the desired media number. Always return true.
  94       */
  95       virtual bool
  96       isDesiredMedia(const MediaAccessRef &ref)
  97       {
  98         (void)ref;
  99         return true;
 100       }
 101     };
 102
 103
 104     ///////////////////////////////////////////////////////////////////
 105     //
 106     // CLASS NAME : MediaVerifierRef
 107     //
 108     /**
 109      * A shared reference to the MediaVerifier implementation.
 110      */
 111     typedef zypp::RW_pointer<MediaVerifierBase> MediaVerifierRef;
 112
 113
 114     ///////////////////////////////////////////////////////////////////
 115     //
 116     // CLASS NAME : MediaManager
 117     //
 118     /**
 119      * Manages coordinated access to 'physical' media, e.g CDROM
 120      * drives.
 121      *
 122      * \note The MediaManager class is just an envelope around an
 123      * inner singelton like implementation. This means, you can
 124      * create as many managers as you want, also temporary in a
 125      * function call.
 126      *
 127      * \note Don't declare static MediaManager instances, unless
 128      * you want to force (mutex) initialization order problems!
 129      *
 130      */
 131     class MediaManager: private zypp::base::NonCopyable
 132     {
 133     public:
 134       /**
 135        * Creates a MediaManager envelope instance.
 136        *
 137        * In the case, that the inner implementation is not already
 138        * allocated, and the MediaManager constructor was unable to
 139        * allocate it, a std::bad_alloc exception is thrown.
 140        *
 141        * All further instances increase the use counter only.
 142        *
 143        * \throws std::bad_alloc
 144        */
 145       MediaManager();
 146
 147       /**
 148        * Destroys MediaManager envelope instance.
 149        * Decreases the use counter of the inner implementation.
 150        */
 151       ~MediaManager();
 152
 153       /**
 154        * Opens the media access for specified with the url.
 155        *
 156        * If the \p preferred_attach_point parameter does not
 157        * point to a usable attach point directory, the media
 158        * manager automatically creates a temporary attach
 159        * point in a default directory. This default directory
 160        * can be changed using setAttachPrefix() function.
 161        *
 162        * \param  url The media access url.
 163        * \param  preferred_attach_point The preferred, already
 164        *         existing directory, where the media should be
 165        *         attached.
 166        * \return a new media access id.
 167        * \throws std::bad_alloc
 168        * \throws MediaException
 169        */
 170       MediaAccessId
 171       open(const Url &url, const Pathname & preferred_attach_point = "");
 172
 173       /**
 174        * Close the media access with specified id.
 175        * \param accessId The media access id to close.
 176        */
 177       void
 178       close(MediaAccessId accessId);
 179
 180       /**
 181        * Query if the media access is open / exists.
 182        *
 183        * \param accessId The media access id query.
 184        * \return true, if access id is known and open.
 185        */
 186       bool
 187       isOpen(MediaAccessId accessId) const;
 188
 189       /**
 190        * Query the protocol name used by the media access
 191        * handler. Similar to url().getScheme().
 192        *
 193        * \param accessId The media access id query.
 194        * \return The protocol name used by the media access
 195        *         handler, otherwise 'unknown'.
 196        * \throws MediaNotOpenException for invalid access id.
 197        */
 198       std::string
 199       protocol(MediaAccessId accessId) const;
 200
 201       /**
 202        * Url of the media access id, otherwise empty Url.
 203        *
 204        * \throws MediaNotOpenException for invalid access id.
 205        */
 206       Url
 207       url(MediaAccessId accessId) const;
 208
 209     public:
 210       /**
 211        * Add verifier implementation for the specified media id.
 212        * By default, the NoVerifier is used.
 213        *
 214        * \throws MediaNotOpenException for invalid access id.
 215        */
 216       void
 217       addVerifier(MediaAccessId accessId,
 218                   const MediaVerifierRef &verifier);
 219
 220       /**
 221        * Remove verifier for specified media id.
 222        *
 223        * \throws MediaNotOpenException for invalid access id.
 224        */
 225       void
 226       delVerifier(MediaAccessId accessId);
 227
 228     public:
 229       /**
 230        * Set or resets the directory name, where the media manager
 231        * handlers create their temporary attach points (see open()
 232        * function).
 233        * It has effect to newly created temporary attach points only.
 234        *
 235        * \param attach_prefix The new prefix for temporary attach
 236        *        points, or empty pathname to reset to defaults.
 237        * \return True on success, false if the \p attach_prefix
 238        *         parameters contains a path name, that does not
 239        *         point to a writable directory.
 240        */
 241       bool
 242       setAttachPrefix(const Pathname &attach_prefix);
 243
 244       /**
 245        * Attach the media using the concrete handler.
 246        *
 247        * \throws MediaNotOpenException for invalid access id.
 248        */
 249       void
 250       attach(MediaAccessId accessId, bool next = false);
 251
 252       /**
 253        * Reattach to a new attach point.
 254        *
 255        * \deprecated This function will be removed, because the
 256        * reattach function has race conditions (e.g. open file
 257        * in the old attach point). Use setAttachPrefix() instead.
 258        *
 259        * \param accessId A media access Id.
 260        * \param attach_point A new attach point directory.
 261        * \param temporary    Whether to reattach to a temporary
 262        *      attach point bellow of \p attach_point and cleanup
 263        *      it on release (temporary=true), or use the provided
 264        *      directory as attach point without to cleanup it on
 265        *      release (temporary=false, default behaviour).
 266        * \throws MediaNotOpenException
 267        * \throws MediaNotSupportedException
 268        */
 269       void
 270       reattach(MediaAccessId   accessId,
 271                const Pathname &attach_point,
 272                bool            temporary = false) ZYPP_DEPRECATED;
 273
 274       /**
 275        * Release the attached media and optionally eject.
 276        *
 277        * \throws MediaNotOpenException for invalid access id.
 278        */
 279       void
 280       release(MediaAccessId accessId, bool eject = false);
 281
 282       /**
 283        * Disconnect a remote media.
 284        *
 285        * This is useful for media which e.g. holds open a connection
 286        * to a server like FTP. After calling disconnect() the media
 287        * object (attach point) is still valid and files are present.
 288        *
 289        * But after calling disconnect() it's not possible to call
 290        * fetch more data using the provideFile() or provideDir()
 291        * functions anymore.
 292        *
 293        * \throws MediaNotOpenException for invalid access id.
 294        */
 295       void
 296       disconnect(MediaAccessId accessId);
 297
 298       /**
 299        * Check if media is attached or not.
 300        *
 301        * \return True if media is attached.
 302        * \throws MediaNotOpenException for invalid access id.
 303        */
 304       bool
 305       isAttached(MediaAccessId accessId) const;
 306
 307       /**
 308        * Returns information if media is on a shared
 309        * physical device or not.
 310        *
 311        * \return True if it is shared, false if not.
 312        * \throws MediaNotOpenException for invalid access id.
 313        */
 314       bool
 315       isSharedMedia(MediaAccessId accessId) const;
 316
 317       /**
 318        * Ask the registered verifier if the attached
 319        * media is the desired one or not.
 320        * \return True if media is attached and desired
 321        *         according to the actual verifier.
 322        * \throws MediaNotOpenException for invalid access id.
 323        */
 324       bool
 325       isDesiredMedia(MediaAccessId accessId) const;
 326
 327       /**
 328        * Ask the specified verifier if the attached
 329        * media is the desired one or not.
 330        * \return True if media is attached and desired
 331        *         according to the specified verifier.
 332        * \throws MediaNotOpenException for invalid access id.
 333        */
 334       bool
 335       isDesiredMedia(MediaAccessId           accessId,
 336                      const MediaVerifierRef &verifier) const;
 337
 338       /**
 339        * Return the local directory that corresponds to medias url,
 340        * no matter if media isAttached or not. Files requested will
 341        * be available at 'localRoot() + filename' or even better
 342        * 'localPath( filename )'
 343        *
 344        * \returns The directory name pointing to the media root
 345        *          in local filesystem or an empty pathname if the
 346        *          media is not attached.
 347        * \throws MediaNotOpenException for invalid access id.
 348        */
 349       Pathname
 350       localRoot(MediaAccessId accessId) const;
 351
 352       /**
 353        * Shortcut for 'localRoot() + pathname', but returns an empty
 354        * pathname if media is not attached.
 355        * Files provided will be available at 'localPath(filename)'.
 356        * \returns The directory name in local filesystem pointing
 357        *          to the desired relative pathname on the media
 358        *          or an empty pathname if the media is not attached.
 359        * \throws MediaNotOpenException for invalid access id.
 360        */
 361       Pathname
 362       localPath(MediaAccessId accessId, const Pathname & pathname) const;
 363
 364     public:
 365       /**
 366        * Provide provide file denoted by relative path below of the
 367        * 'attach point' of the specified media and the path prefix
 368        * on the media.
 369        *
 370        * \param accessId  The media access id to use.
 371        * \param cached    If cached is set to true, the function checks, if
 372        *                  the file already exists and doesn't download it again
 373        *                  if it does. Currently only the existence is checked,
 374        *                  no other file attributes.
 375        * \param checkonly If this and 'cached' are set to true only the
 376        *                  existence of the file is checked but it's not
 377        *                  downloaded. If 'cached' is unset an errer is
 378        *                  returned always.
 379        *
 380        * \throws MediaNotOpenException in case of invalid access id.
 381        * \throws MediaNotAttachedException in case, that the media is not attached.
 382        * \throws MediaNotDesiredException in case, that the media verification failed.
 383        * \throws MediaNotAFileException in case, that the requested filename is not a file.
 384        * \throws MediaFileNotFoundException in case, that the requested filenamedoes not exists.
 385        * \throws MediaWriteException in case, that the file can't be copied from from remote source.
 386        * \throws MediaSystemException in case a system operation fails.
 387        * \throws MediaException derived exception, depending on the url (handler).
 388        */
 389       void
 390       provideFile(MediaAccessId   accessId,
 391                   const Pathname &filename,
 392                   bool            cached    = false,
 393                   bool            checkonly = false) const;
 394
 395       /**
 396        */
 397       void
 398       provideDir(MediaAccessId   accessId,
 399                  const Pathname &dirname) const;
 400
 401       /**
 402        */
 403       void
 404       provideDirTree(MediaAccessId  accessId,
 405                      const Pathname &dirname) const;
 406
 407       /**
 408        */
 409       void
 410       releaseFile(MediaAccessId   accessId,
 411                   const Pathname &filename) const;
 412
 413       /**
 414        */
 415       void
 416       releaseDir(MediaAccessId   accessId,
 417                  const Pathname &dirname) const;
 418
 419       /**
 420        */
 421       void
 422       releasePath(MediaAccessId   accessId,
 423                   const Pathname &pathname) const;
 424
 425       /**
 426        */
 427       void
 428       dirInfo(MediaAccessId           accessId,
 429               std::list<std::string> &retlist,
 430               const Pathname         &dirname,
 431               bool                    dots = true) const;
 432
 433       /**
 434        */
 435       void
 436       dirInfo(MediaAccessId           accessId,
 437               filesystem::DirContent &retlist,
 438               const Pathname         &dirname,
 439               bool                   dots = true) const;
 440
 441
 442     public:
 443       time_t
 444       getMountTableMTime() const;
 445
 446       std::vector<MountEntry>
 447       getMountEntries() const;
 448
 449       bool
 450       isUseableAttachPoint(const Pathname &path) const;
 451
 452     private:
 453       friend class MediaHandler;
 454
 455       AttachedMedia
 456       getAttachedMedia(MediaAccessId &accessId) const;
 457
 458       AttachedMedia
 459       findAttachedMedia(const MediaSourceRef &media) const;
 460
 461       void
 462       forceMediaRelease(const MediaSourceRef &media);
 463
 464     private:
 465       class  Impl;
 466       static zypp::RW_pointer<MediaManager::Impl> m_impl;
 467     };
 468
 469
 470     //////////////////////////////////////////////////////////////////
 471   } // namespace media
 472   ////////////////////////////////////////////////////////////////////
 473
 474   ////////////////////////////////////////////////////////////////////
 475 } // namespace zypp
 476 //////////////////////////////////////////////////////////////////////
 477
 478 #endif // ZYPP_MEDIA_MEDIAMANAGER_H
 479
 480 /*
 481 ** vim: set ts=2 sts=2 sw=2 ai et:
 482 */