zypp/media/MediaHandler.h

   1 /*---------------------------------------------------------------------\
   2 |                          ____ _   __ __ ___                          |
   3 |                         |__  / \ / / . \ . \                         |
   4 |                           / / \ V /|  _/  _/                         |
   5 |                          / /__ | | | | | |                           |
   6 |                         /_____||_| |_| |_|                           |
   7 |                                                                      |
   8 \---------------------------------------------------------------------*/
   9 /** \file zypp/media/MediaHandler.h
  10  *
  11 */
  12 #ifndef ZYPP_MEDIA_MEDIAHANDLERL_H
  13 #define ZYPP_MEDIA_MEDIAHANDLERL_H
  14
  15 #include <iosfwd>
  16 #include <string>
  17 #include <list>
  18
  19 #include "zypp/Pathname.h"
  20 #include "zypp/PathInfo.h"
  21 #include "zypp/base/PtrTypes.h"
  22
  23 #include "zypp/Url.h"
  24
  25 #include "zypp/media/MediaSource.h"
  26 #include "zypp/media/MediaException.h"
  27
  28 namespace zypp {
  29   namespace media {
  30
  31
  32 ///////////////////////////////////////////////////////////////////
  33 //
  34 //      CLASS NAME : MediaHandler
  35 /**
  36  * @short Abstract base class for 'physical' MediaHandler like MediaCD, etc.
  37  *
  38  * Handles the requests forwarded by @ref MediaAccess. The public interface
  39  * contains nonvirtual methods, which should do common sanitychecks and
  40  * logging. For the real action they call virtual methods overloaded by the
  41  * concrete handler.
  42  **/
  43 class MediaHandler {
  44     friend std::ostream & operator<<( std::ostream & str, const MediaHandler & obj );
  45
  46     public:
  47         typedef shared_ptr<MediaHandler> Ptr;
  48         typedef shared_ptr<const MediaHandler> constPtr;
  49
  50     private:
  51         /**
  52          * The attached media source.
  53          */
  54         MediaSourceRef _mediaSource;
  55
  56         /**
  57          * this is where the media will be actually "mounted"
  58          * all files are provided 'below' this directory.
  59          **/
  60         AttachPointRef _attachPoint;
  61
  62         /**
  63          * The relative root directory of the data on the media.
  64          * See also _localRoot and urlpath_below_attachpoint_r
  65          * constructor argument.
  66          */
  67         Pathname _relativeRoot;
  68
  69         /**
  70          * The local directory that corresponds to the media url.
  71          * With NFS it's the '_attachPoint', as the directory on the
  72          * server is mounted. With CD/DVD it's 'attach point+_relativeRoot'
  73          * because the CDs root directory is mounted. And with CIFS
  74          * it's '_url.path() without the shares name'.
  75          **/
  76         Pathname _localRoot;
  77
  78         /**
  79          * True if concrete handler downloads files to the local
  80          * filesystem. If true releaseFile/Dir will delete them.
  81          **/
  82         bool _does_download;
  83
  84         /** timestamp of the the last attach verification */
  85         mutable time_t _attach_mtime;
  86
  87     protected:
  88         /**
  89          * Url to handle
  90          **/
  91         const Url        _url;
  92
  93         /**
  94          * Access Id of media handler we depend on.
  95          */
  96         MediaAccessId    _parentId;
  97
  98         /**
  99          * Return the currently used attach point.
 100          **/
 101         Pathname         attachPoint() const;
 102
 103         /**
 104          * Set a new attach point and update localRoot.
 105          */
 106         void             setAttachPoint(const Pathname &path, bool _temporary);
 107
 108         /**
 109          * Set a (shared) attach point and update localRoot.
 110          */
 111         void             setAttachPoint(const AttachPointRef &ref);
 112
 113         /**
 114          * Try to create a default / temporary attach point.
 115          * \return The name of the new attach point or empty path name.
 116          */
 117         Pathname         createAttachPoint() const;
 118
 119         /**
 120          * Remove unused attach point.
 121          */
 122         void             removeAttachPoint();
 123
 124         bool             isUseableAttachPoint(const Pathname &path) const;
 125
 126         std::string      mediaSourceName() const
 127         {
 128           return _mediaSource ? _mediaSource->name : "";
 129         }
 130
 131         void             setMediaSource(const MediaSourceRef &ref);
 132
 133         /**
 134          * MediaAccess (MediaManager) needs access to the
 135          * attachedMedia() function to deliver a shared
 136          * media source and its attach point to other
 137          * media handler instances.
 138          */
 139         friend class MediaAccess;
 140
 141         /**
 142          * Ask the media manager if specified media source
 143          * is already attached.
 144          */
 145         AttachedMedia
 146         findAttachedMedia(const MediaSourceRef &media) const;
 147
 148         bool                 dependsOnParent(MediaAccessId parentId);
 149
 150         /**
 151          * Returns the attached media. Used by MediaManager
 152          * to find other handlers using the same source.
 153          */
 154         AttachedMedia        attachedMedia() const;
 155
 156         bool                 isSharedMedia() const;
 157
 158         bool                 checkAttached(bool aDevice,
 159                                            bool fsType=false) const;
 160
 161         void                 reattach(const Pathname &new_attach_point);
 162         virtual void         reattachTo(const Pathname &new_attach_point);
 163
 164     protected:
 165
 166         ///////////////////////////////////////////////////////////////////
 167         //
 168         // Real action interface to be overloaded by concrete handler.
 169         //
 170         ///////////////////////////////////////////////////////////////////
 171
 172         /**
 173          * Call concrete handler to attach the media.
 174          *
 175          * Asserted that not already attached, and attachPoint is a directory.
 176          *
 177          * @param next try next available device in turn until end of device
 178          * list is reached (for media which are accessible through multiple
 179          * devices like cdroms).
 180          *
 181          * \throws MediaException
 182          *
 183          **/
 184         virtual void attachTo(bool next = false) = 0;
 185
 186         /**
 187          * Call concrete handler to disconnect media.
 188          *
 189          * Asserted that media is attached.
 190          *
 191          * This is useful for media which e.g. holds open a connection to a
 192          * server like FTP. After calling disconnect() the media object still is
 193          * valid and files are present.
 194          *
 195          * After calling disconnect() it's not possible to call provideFile() or
 196          * provideDir() anymore.
 197          *
 198          * \throws MediaException
 199          *
 200          **/
 201         virtual void disconnectFrom() { return; }
 202
 203         /**
 204          * Call concrete handler to release the media.
 205          *
 206          * If eject is true, and the media is used in one handler
 207          * instance only, physically eject the media (i.e. CD-ROM).
 208          *
 209          * Asserted that media is attached.
 210          *
 211          * \throws MediaException
 212          *
 213          **/
 214         virtual void releaseFrom( bool eject ) = 0;
 215
 216         /**
 217          * Call concrete handler to physically eject the media (i.e. CD-ROM)
 218          * in case the media is not attached..
 219          *
 220          * Asserted that media is not attached.
 221          **/
 222         virtual void forceEject() {}
 223
 224         /**
 225          * Call concrete handler to provide file below attach point.
 226          *
 227          * Default implementation provided, that returns whether a file
 228          * is located at '_localRoot + filename'.
 229          *
 230          * Asserted that media is attached.
 231          *
 232          * \throws MediaException
 233          *
 234          **/
 235         virtual void getFile( const Pathname & filename ) const = 0;
 236
 237         /**
 238          * Call concrete handler to provide a file under a different place
 239          * in the file system (usually not under attach point) as a copy.
 240          * Media must be attached before by callee.
 241          *
 242          * Default implementation provided that calls getFile(srcFilename)
 243          * and copies the result around.
 244          *
 245          * \throws MediaException
 246          *
 247          **/
 248         virtual void getFileCopy( const Pathname & srcFilename, const Pathname & targetFilename ) const;
 249
 250
 251         /**
 252          * Call concrete handler to provide directory content (not recursive!)
 253          * below attach point.
 254          *
 255          * Return E_not_supported_by_media if media does not support retrieval of
 256          * directory content.
 257          *
 258          * Default implementation provided, that returns whether a directory
 259          * is located at '_localRoot + dirname'.
 260          *
 261          * Asserted that media is attached.
 262          *
 263          * \throws MediaException
 264          *
 265          **/
 266         virtual void getDir( const Pathname & dirname, bool recurse_r ) const = 0;
 267
 268         /**
 269          * Call concrete handler to provide a content list of directory on media
 270          * via retlist. If dots is false entries starting with '.' are not reported.
 271          *
 272          * Return E_not_supported_by_media if media does not support retrieval of
 273          * directory content.
 274          *
 275          * Default implementation provided, that returns the content of a
 276          * directory at '_localRoot + dirnname' retrieved via 'readdir'.
 277          *
 278          * Asserted that media is attached and retlist is empty.
 279          *
 280          * \throws MediaException
 281          *
 282          **/
 283         virtual void getDirInfo( std::list<std::string> & retlist,
 284                                  const Pathname & dirname, bool dots = true ) const = 0;
 285
 286         /**
 287          * Basically the same as getDirInfo above. The content list is returned as
 288          * filesystem::DirContent, which includes name and filetype of each directory
 289          * entry. Retrieving the filetype usg. requires an additional ::stat call for
 290          * each entry, thus it's more expensive than a simple readdir.
 291          *
 292          * Asserted that media is attached and retlist is empty.
 293          *
 294          * \throws MediaException
 295          *
 296          **/
 297         virtual void getDirInfo( filesystem::DirContent & retlist,
 298                                  const Pathname & dirname, bool dots = true ) const = 0;
 299
 300   protected:
 301
 302         /**
 303          * Retrieve and if available scan dirname/directory.yast.
 304          *
 305          * Asserted that media is attached.
 306          *
 307          * \throws MediaException
 308          *
 309          **/
 310         void getDirectoryYast( std::list<std::string> & retlist,
 311                                const Pathname & dirname, bool dots = true ) const;
 312
 313         /**
 314          * Retrieve and if available scan dirname/directory.yast.
 315          *
 316          * Asserted that media is attached.
 317          *
 318          * \throws MediaException
 319          *
 320          **/
 321         void getDirectoryYast( filesystem::DirContent & retlist,
 322                                const Pathname & dirname, bool dots = true ) const;
 323
 324   public:
 325
 326         /**
 327          * If the concrete media handler provides a nonempty
 328          * attach_point, it must be an existing directory.
 329          *
 330          * On an empty attach_point, MediaHandler will create
 331          * a temporay directory, which will be erased from
 332          * destructor.
 333          *
 334          * On any error, the attach_point is set to an empty Pathname,
 335          * which should lead to E_bad_attachpoint.
 336          **/
 337         MediaHandler ( const Url&       url_r,
 338                        const Pathname & attach_point_r,
 339                        const Pathname & urlpath_below_attachpoint_r,
 340                        const bool       does_download_r );
 341
 342         /**
 343          * Contolling MediaAccess takes care, that attached media is released
 344          * prior to deleting this.
 345          **/
 346         virtual ~MediaHandler();
 347
 348     public:
 349
 350
 351         ///////////////////////////////////////////////////////////////////
 352         //
 353         // MediaAccess interface. Does common checks and logging.
 354         // Invokes real action if necessary.
 355         //
 356         ///////////////////////////////////////////////////////////////////
 357
 358         /**
 359          * Protocol hint for MediaAccess.
 360          **/
 361         std::string protocol() const { return _url.getScheme(); }
 362
 363         /**
 364          * Url used.
 365          **/
 366         Url url() const { return _url; }
 367
 368         /**
 369          * Use concrete handler to attach the media.
 370          *
 371          * @param next try next available device in turn until end of device
 372          * list is reached (for media which are accessible through multiple
 373          * devices like cdroms).
 374          *
 375          * \throws MediaException
 376          *
 377          **/
 378         void attach(bool next);
 379
 380         /**
 381          * True if media is attached.
 382          **/
 383         virtual bool isAttached() const { return _mediaSource; }
 384
 385         /**
 386          * Return the local directory that corresponds to medias url,
 387          * no matter if media isAttached or not. Files requested will
 388          * be available at 'localRoot() + filename' or better
 389          * 'localPath( filename )'.
 390          *
 391          * Returns empty pathname if E_bad_attachpoint
 392          **/
 393         const Pathname & localRoot() const { return _localRoot; }
 394
 395         /**
 396          * Files provided will be available at 'localPath(filename)'.
 397          *
 398          * Returns empty pathname if E_bad_attachpoint
 399          **/
 400          Pathname localPath( const Pathname & pathname ) const;
 401
 402         /**
 403          * Use concrete handler to isconnect media.
 404          *
 405          * This is useful for media which e.g. holds open a connection to a
 406          * server like FTP. After calling disconnect() the media object still is
 407          * valid and files are present.
 408          *
 409          * After calling disconnect() it's not possible to call provideFile() or
 410          * provideDir() anymore.
 411          *
 412          * \throws MediaException
 413          *
 414          **/
 415         void disconnect();
 416
 417         /**
 418          * Use concrete handler to release the media.
 419          * @param eject if true, physically eject the media * (i.e. CD-ROM)
 420          *
 421          * \throws MediaException
 422          *
 423          **/
 424         void release( bool eject = false );
 425
 426         /**
 427          * Use concrete handler to provide file denoted by path below
 428          * 'localRoot'. Filename is interpreted relative to the
 429          * attached url and a path prefix is preserved.
 430          *
 431          * \throws MediaException
 432          *
 433          **/
 434         void provideFile( Pathname filename ) const;
 435
 436         /**
 437          * Call concrete handler to provide a copy of a file under a different place
 438          * in the file system (usually not under attach point) as a copy.
 439          * Media must be attached before by callee.
 440          *
 441          * @param srcFilename    Filename of source file on the media
 442          * @param targetFilename Filename for the target in the file system
 443          *
 444          * \throws MediaException
 445          *
 446          **/
 447         void provideFileCopy( Pathname srcFilename, Pathname targetFilename) const;
 448
 449         /**
 450          * Use concrete handler to provide directory denoted
 451          * by path below 'localRoot' (not recursive!).
 452          * dirname is interpreted relative to the
 453          * attached url and a path prefix is preserved.
 454          *
 455          * \throws MediaException
 456          *
 457          **/
 458         void provideDir( Pathname dirname ) const;
 459
 460         /**
 461          * Use concrete handler to provide directory tree denoted
 462          * by path below 'localRoot' (recursive!!).
 463          * dirname is interpreted relative to the
 464          * attached url and a path prefix is preserved.
 465          *
 466          * \throws MediaException
 467          *
 468          **/
 469         void provideDirTree( Pathname dirname ) const;
 470
 471         /**
 472          * Remove filename below localRoot IFF handler downloads files
 473          * to the local filesystem. Never remove anything from media.
 474          *
 475          * \throws MediaException
 476          *
 477          **/
 478         void releaseFile( const Pathname & filename ) const { return releasePath( filename ); }
 479
 480         /**
 481          * Remove directory tree below localRoot IFF handler downloads files
 482          * to the local filesystem. Never remove anything from media.
 483          *
 484          * \throws MediaException
 485          *
 486          **/
 487         void releaseDir( const Pathname & dirname ) const { return releasePath( dirname ); }
 488
 489         /**
 490          * Remove pathname below localRoot IFF handler downloads files
 491          * to the local filesystem. Never remove anything from media.
 492          *
 493          * If pathname denotes a directory it is recursively removed.
 494          * If pathname is empty or '/' everything below the localRoot
 495          * is recursively removed.
 496          * If pathname denotes a file it is unlinked.
 497          *
 498          * \throws MediaException
 499          *
 500          **/
 501         void releasePath( Pathname pathname ) const;
 502
 503     public:
 504
 505         /**
 506          * Return content of directory on media via retlist. If dots is false
 507          * entries starting with '.' are not reported.
 508          *
 509          * The request is forwarded to the concrete handler,
 510          * which may atempt to retieve the content e.g. via 'readdir'
 511          *
 512          * <B>Caution:</B> This is not supported by all media types.
 513          * Be prepared to handle E_not_supported_by_media.
 514          *
 515          * \throws MediaException
 516          *
 517          **/
 518         void dirInfo( std::list<std::string> & retlist,
 519                       const Pathname & dirname, bool dots = true ) const;
 520
 521         /**
 522          * Basically the same as dirInfo above. The content is returned as
 523          * filesystem::DirContent, which includes name and filetype of each directory
 524          * entry. Retrieving the filetype usg. requires an additional ::stat call for
 525          * each entry, thus it's more expensive than a simple readdir.
 526          *
 527          * <B>Caution:</B> This is not supported by all media types.
 528          * Be prepared to handle E_not_supported_by_media.
 529          *
 530          * \throws MediaException
 531          *
 532          **/
 533         void dirInfo( filesystem::DirContent & retlist,
 534                       const Pathname & dirname, bool dots = true ) const;
 535 };
 536
 537 ///////////////////////////////////////////////////////////////////
 538
 539 #define MEDIA_HANDLER_API                                               \
 540     protected:                                                          \
 541         virtual void attachTo (bool next = false);                      \
 542         virtual void releaseFrom( bool eject );                 \
 543         virtual void getFile( const Pathname & filename ) const;        \
 544         virtual void getDir( const Pathname & dirname, bool recurse_r ) const;  \
 545         virtual void getDirInfo( std::list<std::string> & retlist,      \
 546                                     const Pathname & dirname, bool dots = true ) const; \
 547         virtual void getDirInfo( filesystem::DirContent & retlist,      \
 548                                     const Pathname & dirname, bool dots = true ) const;
 549
 550   } // namespace media
 551 } // namespace zypp
 552
 553
 554 #endif // ZYPP_MEDIA_MEDIAHANDLERL_H
 555
 556