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/APIConfig.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     class MediaManager_Impl;
  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        * Returns a string with some info about the verifier.
  67        * By default, the type info name is returned.
  68        */
  69       virtual std::string
  70       info() const;
  71
  72       /*
  73       ** Check if the specified attached media contains
  74       ** the desired media (e.g. SLES10 CD1).
  75       */
  76       virtual bool
  77       isDesiredMedia(const MediaAccessRef &ref) = 0;
  78     };
  79
  80
  81     ///////////////////////////////////////////////////////////////////
  82     //
  83     // CLASS NAME : NoVerifier
  84     //
  85     /**
  86      * Dummy default media verifier, which is always happy.
  87      */
  88     class NoVerifier : public MediaVerifierBase
  89     {
  90     public:
  91       NoVerifier(): MediaVerifierBase()
  92       {}
  93
  94       virtual
  95       ~NoVerifier()
  96       {}
  97
  98       /**
  99        * Returns the "zypp::media::NoVerifier" string.
 100        */
 101       virtual std::string
 102       info() const;
 103
 104       /*
 105       ** Don't check if the specified attached media contains
 106       ** the desired media number. Always return true.
 107       */
 108       virtual bool
 109       isDesiredMedia(const MediaAccessRef &ref)
 110       {
 111         (void)ref;
 112         return true;
 113       }
 114     };
 115
 116
 117     ///////////////////////////////////////////////////////////////////
 118     //
 119     // CLASS NAME : MediaVerifierRef
 120     //
 121     /**
 122      * A shared reference to the MediaVerifier implementation.
 123      */
 124     typedef zypp::RW_pointer<MediaVerifierBase> MediaVerifierRef;
 125
 126
 127     ///////////////////////////////////////////////////////////////////
 128     //
 129     // CLASS NAME : MediaManager
 130     //
 131     /**
 132      * Manages access to the 'physical' media, e.g CDROM drives,
 133      * Disk volumes, directory trees, etc, using \ref MediaAccessUrl's.
 134      *
 135      * \note The MediaManager class is just an envelope around an
 136      *       inner singleton like implementation.<br>
 137      *       That is, you can create as many managers as you want,
 138      *       also temporary in a function call.<br>
 139      *       But <b>don't</b> declare static MediaManager instances,
 140      *       unless you want to force (mutex) initialization order
 141      *       problems!
 142      *
 143      * \section MediaAccessUrl Media Access Url
 144      * The MediaManager uses several media access handlers (backends),
 145      * that can be specified by a Media Access URL in its open() method.
 146      *
 147      * All URLs may contain following query parameters, that are
 148      * reserved by the Source classes and unused/ignored by the media
 149      * manager:
 150      * - <tt>alias</tt>: A source specific media alias string.
 151      *
 152      * Currently, following access handlers (backends) are implemented:
 153      *   - \ref MediaCD_Url
 154      *   - \ref MediaDISK_Url
 155      * .
 156      *   - \ref MediaISO_Url
 157      *   - \ref MediaDIR_Url
 158      * .
 159      *   - \ref MediaNFS_Url
 160      *   - \ref MediaCIFS_Url
 161      *   - \ref MediaCurl_Url
 162      *
 163      * \subsection MediaCD_Url MediaCD - CD/DVD drives (cd, dvd)
 164      * The access handler for media on CD / DVD drives.
 165      *   - Scheme:
 166      *     - <b>cd</b>: Requires a drive supporting CD media.
 167      *     - <b>dvd</b>: Prefers a drive supporting DVD media.
 168      *   - Examples:
 169      *     \code
 170      *       "cd:/"
 171      *       "cd:/?devices=/dev/hda,/dev/hdb"
 172      *       "cd:/subdir?devices=/dev/hda,/dev/hdb"
 173      *
 174      *       "dvd:/"
 175      *       "dvd:/?devices=/dev/hda,/dev/hdb"
 176      *       "dvd:/subdir?devices=/dev/hda,/dev/hdb"
 177      *     \endcode
 178      *     Note: You can use either "dvd:/" (just path, no authority)
 179      *           or "dvd:///" (path and empty authority).
 180      *   - Query parameters:
 181      *     - <tt>devices</tt>:
 182      *       Optional parameter, containing a comma separated list of
 183      *       block device names to use, e.g.: "/dev/sr0,/dev/sr1".
 184      *       <br>
 185      *       The device names will be verified. If one of the provided
 186      *       devices is not usable (not a block device, or does not
 187      *       support required media type), an exception is thrown.
 188      *       <br>
 189      *       If the devices parameter is not provided (or empty), available
 190      *       CD/DVD drives will be auto-detected. The preferred device is
 191      *       the one denoted by "/dev/dvd" ("dvd" scheme only) or "/dev/cdrom".
 192      *   - Authority:
 193      *     A non-empty authority URL component (e.g. containing a host
 194      *     name) is not allowed.
 195      *   - Path name:
 196      *     Mandatory URL component, that specifies a subdirectory on the
 197      *     CD/DVD, where the desired files are located.
 198      *
 199      * \subsection MediaDISK_Url MediaDISK - HD disk volumes (hd)
 200      * The access handler for media on a disk volume (partition).
 201      *   - Scheme:
 202      *     - <b>hd</b>
 203      *   - Examples:
 204      *     \code
 205      *       "hd:/?device=/dev/hda1"
 206      *       "hd:/subdir?device=/dev/sda1"
 207      *       "hd:/subdir?device=/dev/sda1&filesystem=reiserfs"
 208      *     \endcode
 209      *     Note: You can use either "hd:/" (just path, no authority)
 210      *     or "hd:///" (path and empty authority).
 211      *   - Query parameters:
 212      *     - <tt>device</tt>:
 213      *       Mandatory parameter specifying the name of the block device of
 214      *       the partition to mount.
 215      *     - <tt>filesystem</tt>:
 216      *       The name of the filesystem. Defaults to "auto".
 217      *   - Authority:
 218      *     A non-empty authority URL component is not allowed.
 219      *   - Path name:
 220      *     Mandatory URL component, that specifies a subdirectory on the disk
 221      *     partition, where the desired files are located.
 222      *
 223      * \subsection MediaDIR_Url MediaDIR - Local directory tree (dir, file)
 224      * The access handler to media stored in a local directory tree.
 225      *   - Scheme:
 226      *     - <b>dir</b>
 227      *     - <b>file</b>
 228      *   - Examples:
 229      *     \code
 230      *       "dir:/directory/name"
 231      *       "file:/directory/name"
 232      *     \endcode
 233      *   - Query parameters:
 234      *     none
 235      *   - Authority:
 236      *     A non-empty authority URL component (e.g. containing
 237      *     a host name) is not allowed.
 238      *   - Path name:
 239      *     Mandatory URL component, that specifies a directory, where
 240      *     the desired files are located.
 241      *
 242      * \subsection MediaISO_Url MediaISO - Loopback ISO images (iso)
 243      * The access handler for media in a ISO image (loopback mount).
 244      *   - Scheme:
 245      *     - <b>iso</b>
 246      *   - Examples:
 247      *     \code
 248      *       "iso:/?iso=/path/to/CD1.iso"
 249      *       "iso:/?iso=CD1.iso&url=dir:/path/to"
 250      *
 251      *       "iso:/?iso=CD1.iso&url=nfs://server/path/to/media"
 252      *       "iso:/?iso=CD1.iso&url=hd:/?device=/dev/hda"
 253      *
 254      *        "iso:/subdir?iso=DVD1.iso&url=nfs://nfs-server/directory&mnt=/nfs/attach/point&filesystem=udf"
 255      *     \endcode
 256      *   - Query parameters:
 257      *     - <tt>iso</tt>:
 258      *       Mandatory parameter specifying the name of the iso file.<br>
 259      *       If the url parameter is missed, the iso parameter has to contain
 260      *       an absolute iso file name.
 261      *     - <tt>url</tt>:
 262      *       Optional parameter specifying the URL to the directory containing
 263      *       the iso file.<br>
 264      *       The supported URL schemes are: <i><b>hd</b>, <b>dir</b>,
 265      *       <b>file</b>, <b>nfs</b>, <b>nfs4</b>, <b>smb</b>, <b>cifs</b>.</i>
 266      *     - <tt>mnt</tt>:
 267      *       Optional parameter specifying the prefered attach point for the
 268      *       source media url.
 269      *     - <tt>filesystem</tt>:
 270      *       Optional name of the filesystem used in the iso file. Defaults
 271      *       to "auto".
 272      *   - Authority:
 273      *     A non-empty authority URL component is not allowed.
 274      *   - Path name:
 275      *     Mandatory URL component, that specifies a subdirectory inside of
 276      *     the iso file, where the desired files are located.
 277      *
 278      * \subsection MediaNFS_Url MediaNFS  - NFS directory tree (nfs)
 279      * The access handler for media on NFS exported directory tree.
 280      *   - Scheme:
 281      *     - <b>nfs</b>
 282      *     - <b>nfs</b>
 283      *   - Examples:
 284      *     \code
 285      *        "nfs://nfs-server/exported/path"
 286      *        "nfs://nfs-server/exported/path?mountoptions=ro"
 287      *        "nfs://nfs-server/exported/path&type=nfs4"
 288      *        "nfs4://nfs-server/exported/path"
 289      *     \endcode
 290      *   - Query parameters:
 291      *     - <tt>mountoptions</tt>:
 292      *       The mount options separated by comma ','.
 293      *       Default is the "ro" option.
 294      *     - <tt>type=nfs4</tt>:
 295      *       Whether to mount as nfs4. This is the default for scheme nfs4.
 296       *   - Authority:
 297      *     The authority component has to provide a hostname.
 298      *     Username, password and port are currently ignored.
 299      *   - Path name:
 300      *     Mandatory URL component, that specifies the exported
 301      *     (sub-)directory on the NFS server, where the desired
 302      *     files are located.
 303      *
 304      * \subsection MediaCIFS_Url MediaCIFS - CIFS/SMB directory tree (cifs, smb)
 305      * The access handler for media in a CIFS/SMB shared directory tree.
 306      *   - Scheme:
 307      *     - <b>cifs</b>
 308      *     - <b>smb</b>
 309      *   - Examples:
 310      *     \code
 311      *       "cifs://servername/share/path/on/the/share"
 312      *       "cifs://username:passwd@servername/share/path/on/the/share?mountoptions=ro"
 313      *       "cifs://username:passwd@servername/share/path/on/the/share?mountoptions=noguest"
 314      *       "smb://servername/share/path/on/the/share"
 315      *       "smb://username:passwd@servername/share/path/on/the/share?mountoptions=ro"
 316      *     \endcode
 317      *     Note: There is no difference between cifs and smb scheme
 318      *     (any more). In both cases the 'cifs' filesystem is used.
 319      *   - Query parameters:
 320      *     - <tt>mountoptions</tt>:
 321      *       The mount options separated by a comma ','. Default are the
 322      *       "ro" and "guest" options. Specify "noguest" to turn off
 323      *       "guest". This is necessary if Samba is configured to reject
 324      *       guest connections.
 325      *     - <tt>workgroup</tt> or <tt>domain</tt>:
 326      *       The name of the workgroup.
 327      *     - <tt>username</tt>:
 328      *       Alternative username to username in URL authority.
 329      *     - <tt>password</tt>:
 330      *       Alternative password to password in URL authority.
 331      *     - <tt>user</tt>:
 332      *       Alternative username (cifs specific variant)
 333      *     - <tt>pass</tt>:
 334      *       Alternative password (cifs specific variant)
 335      *   - Authority:
 336      *     The authority component has to provide a hostname. Optionally
 337      *     also a username and password.
 338      *   - Path name:
 339      *     Mandatory URL component, that specifies the share name with
 340      *     optional subdirectory, where the desired files are located.
 341      *
 342      * \subsection MediaCurl_Url MediaCurl - FTP/HTTP directory tree (ftp, tftp, http, https)
 343      * The access handler to media directory tree on a ftp/http server.
 344      *   - Scheme:
 345      *     - <b>ftp</b>
 346      *     - <b>tftp</b>
 347      *     - <b>http</b>
 348      *     - <b>https</b>
 349      *   - Examples:
 350      *     \code
 351      *       "ftp://server/relative/path/to/media/dir"
 352      *       "ftp://server/%2fabsolute/path/to/media/dir"
 353      *
 354      *       "ftp://user:pass@server/path/to/media/dir"
 355      *       "ftp://user:pass@server/%2f/home/user/path/to/media/dir"
 356      *
 357      *       "http://server/path/on/server"
 358      *       "http://user:pass@server/path"
 359      *       "https://user:pass@server/path?proxy=foo&proxyuser=me&proxypass=pw"
 360      *     \endcode
 361      *     Note: The "ftp" url scheme supports absolute and relative
 362      *     paths to the default ftp server directory
 363      *     (<a href="http://rfc.net/rfc1738.html">RFC1738, Section 3.2.2</a>).<br>
 364      *     To use an absolute path, you have to prepend the path with an
 365      *     additional slash, what results in a "/%2f" combination
 366      *     (second "/" encoded to "%2f") at the begin of the URL path.
 367      *     <br>
 368      *     This is important, especially in user authenticated ftp,
 369      *     where the users home is usually the default directory of the
 370      *     server (except when the server chroots into the users home
 371      *     directory).
 372      *     <br>
 373      *     For example, if the user "user" has a home directory
 374      *     "/home/user", you can use either an URL with a relative path
 375      *     to the home directory "ftp://user:pass@server/path/to/media"
 376      *     or the absolute path
 377      *     "ftp://user:pass@server/%2fhome/user/path/to/media" -- both
 378      *     URLs points to the same directory on the server.
 379      *   - Query parameters:
 380      *     - <tt>cookies</tt>:
 381      *       Turn off using cookies by setting it to "0" (or false, no, off).
 382      *     - <tt>proxy</tt>:
 383      *       A proxy hostname or hostname and port separated by ':'.
 384      *       Setting the hostname to '_none_' explicitly disables the use of a
 385      *       proxy even if configured in /etc/sysconfig/proxy or the environment.
 386      *     - <tt>proxyport</tt>:
 387      *       Alternative way to provide the proxy port.
 388      *     - <tt>proxyuser</tt>:
 389      *       The proxy username.
 390      *     - <tt>proxypass</tt>:
 391      *       The proxy password.
 392      *     - <tt>ssl_capath</tt>:
 393      *       The absolute CA directory to use, default is /etc/ssl/certs.
 394      *     - <tt>ssl_verify</tt>: Flag to modify the ssl verify behaviour.
 395      *       Valid values are: 'yes', 'no' and a comma separated list of
 396      *       'host' and 'peer' flags.
 397      *       - 'no':
 398      *         disables ssl verify
 399      *       - 'yes':
 400      *         enables ssl verify, this is the default
 401      *         and is equivalent to 'host,peer'.
 402      *       - 'host': The server is considered the intended one, when the
 403      *         'Common Name' field or a 'Subject Alternate Name' field in
 404      *         the certificate matches the host name in the URL.
 405      *       - 'peer': Verifies whether the certificate provided by the
 406      *         server is authentic against the chain of digital signatures
 407      *         found in <tt>ssl_capath</tt>.
 408      *     - <tt>ssl_clientcert</tt>
 409      *       Path to the ssl client certificate for authentication to a repo (CURLOPT_SSLCERT).
 410      *     - <tt>ssl_clientkey</tt>
 411      *       Path to the ssl client key for authentication to a repo (CURLOPT_SSLKEY).
 412      *     - <tt>timeout</tt>:
 413      *       Transfer timeout in seconds between 0 and 3600, 0 disables
 414      *       the timeout, default timeout is 180 seconds.
 415      *     - <tt>auth</tt>: A comma separated list of http authentication
 416      *       method names to use: 'basic', 'digest', 'ntlm', 'negotiate',
 417      *       'spnego', 'gssnego'.
 418      *       Note, that this list depends on the list of methods supported
 419      *       by the curl library.
 420      *     - <tt>mediahandler</tt>: Set the mediahandler for this url
 421      *     Valid values are: 'curl', 'multicurl'
 422      *   - Authority:
 423      *     The authority component has to provide a hostname. Optionally
 424      *     also a username and password. In case of the 'ftp' scheme,
 425      *     username and password defaults to 'anonymous' and 'yast2@'.
 426      *   - Path name:
 427      *     Mandatory URL component, that specifies the path name on the
 428      *     server, where the desired files are located.
 429      *
 430      *   Proxy settings: If no proxy settings are present in tha URLs
 431      *   query parameters, the media handler reads the system wide proxy
 432      *   settings from the <tt>/etc/sysconfig/proxy</tt> file.
 433      *   If a proxy setting was present, but the proxy password not,
 434      *   it attempts to read the <tt>proxy-user</tt> variable from the
 435      *   <tt>~/.curlrc</tt> (<tt>/root/.curlrc</tt>) file.
 436      *   <br>
 437      *   If no proxy setting was present, then libzypp does not pass any
 438      *   proxy settings to curl, but curl fallbacks to use the content of
 439      *   the <tt>http_proxy</tt>, <tt>ftp_proxy</tt>, etc environment
 440      *   variables.
 441      *
 442      * \subsection MediaPlugin_Url MediaPlugin - custom media handler
 443      * Media access is delegated to a script located in the libzypp
 444      * media plugin directory. The URLs query options are translated
 445      * into commandline arguments passed to the script.
 446      *   - Scheme:
 447      *     - <b>plugin</b>
 448      *   - Examples:
 449      *     \code
 450      *       "plugin:script?loptv=lvalue&v=optv&lopt=&o&=foo"
 451      *                      \__________/ \____/ \___/ | \_/
 452      *                __________/__    ____/_    _|_  \   \___
 453      *              /              \ /       \ /    \ /\ /    \
 454      *       script --loptv "lvalue" -v "optv" --lopt -o -- foo
 455      *     \endcode
 456      *   - Query parameters:
 457      *     - The URLs query options are translated into commandline
 458      *       arguments passed to the script.
 459      *     - \b Note: No option may appear twice, as the <tt>(option,value)</tt>
 460      *       pairs are stored in a hash.
 461      *     - \b Note: The order in which the query options are passes to the
 462      *       script is arbitrary, except for an option with an empty key, which
 463      *       is translated into <tt>'-- value'</tt> and passed as final option.
 464      *     - <tt>'c[=[value]]'</tt> ist passed as <tt>'-c [value]'</tt>
 465      *     - <tt>'word[=[value]]'</tt> ist passed as <tt>'--word [value]'</tt>
 466      *     - <tt>'[=value]'</tt> ist passed as last args as <tt>'-- [value]'</tt>
 467      *   - \c script<->libzypp communication:
 468      *     - \TODO to be documented.
 469      */
 470     class MediaManager: private zypp::base::NonCopyable
 471     {
 472     public:
 473       /**
 474        * Creates a MediaManager envelope instance.
 475        *
 476        * In the case, that the inner implementation is not already
 477        * allocated, and the MediaManager constructor was unable to
 478        * allocate it, a std::bad_alloc exception is thrown.
 479        *
 480        * All further instances increase the use counter only.
 481        *
 482        * \throws std::bad_alloc
 483        */
 484       MediaManager();
 485
 486       /**
 487        * Destroys MediaManager envelope instance.
 488        * Decreases the use counter of the inner implementation.
 489        */
 490       ~MediaManager();
 491
 492       /**
 493        * Opens the media access for specified with the url.
 494        *
 495        * If the \p preferred_attach_point parameter does not
 496        * point to a usable attach point directory, the media
 497        * manager automatically creates a temporary attach
 498        * point in a default directory. This default directory
 499        * can be changed using setAttachPrefix() function.
 500        *
 501        * Remember to close() each id you've opened and not
 502        * need any more. It is like a new and delete!
 503        *
 504        * \param  url The \ref MediaAccessUrl.
 505        * \param  preferred_attach_point The preferred, already
 506        *         existing directory, where the media should be
 507        *         attached.
 508        * \return a new media access id.
 509        * \throws std::bad_alloc
 510        * \throws MediaException
 511        */
 512       MediaAccessId
 513       open(const Url &url, const Pathname & preferred_attach_point = "");
 514
 515       /**
 516        * Close the media access with specified id.
 517        * \param accessId The media access id to close.
 518        */
 519       void
 520       close(MediaAccessId accessId);
 521
 522       /**
 523        * Query if the media access is open / exists.
 524        *
 525        * \param accessId The media access id to query.
 526        * \return true, if access id is known and open.
 527        */
 528       bool
 529       isOpen(MediaAccessId accessId) const;
 530
 531       /**
 532        * Query the protocol name used by the media access
 533        * handler. Similar to url().getScheme().
 534        *
 535        * \param accessId The media access id to query.
 536        * \return The protocol name used by the media access
 537        *         handler, otherwise 'unknown'.
 538        * \throws MediaNotOpenException for invalid access id.
 539        */
 540       std::string
 541       protocol(MediaAccessId accessId) const;
 542
 543       /**
 544        * Hint if files are downloaded or not.
 545        * \param accessId The media access id to query.
 546        * \return True, if provideFile downloads files.
 547        */
 548       bool
 549       downloads(MediaAccessId accessId) const;
 550
 551       /**
 552        * Returns the \ref MediaAccessUrl of the media access id.
 553        *
 554        * \param accessId The media access id to query.
 555        * \return The \ref MediaAccessUrl used by the media access id.
 556        * \throws MediaNotOpenException for invalid access id.
 557        */
 558       Url
 559       url(MediaAccessId accessId) const;
 560
 561     public:
 562       /**
 563        * Add verifier implementation for the specified media id.
 564        * By default, the NoVerifier is used.
 565        *
 566        * \param accessId A media access id.
 567        * \param verifier The new verifier.
 568        * \throws MediaNotOpenException for invalid access id.
 569        */
 570       void
 571       addVerifier(MediaAccessId accessId,
 572                   const MediaVerifierRef &verifier);
 573
 574       /**
 575        * Remove verifier for specified media id.
 576        * It resets the verifier to NoVerifier.
 577        *
 578        * \param accessId A media access id.
 579        * \throws MediaNotOpenException for invalid access id.
 580        */
 581       void
 582       delVerifier(MediaAccessId accessId);
 583
 584     public:
 585       /**
 586        * Set or resets the directory name, where the media manager
 587        * handlers create their temporary attach points (see open()
 588        * function).
 589        * It has effect to newly created temporary attach points only.
 590        *
 591        * \param attach_prefix The new prefix for temporary attach
 592        *        points, or empty pathname to reset to defaults.
 593        * \return True on success, false if the \p attach_prefix
 594        *         parameters contains a path name, that does not
 595        *         point to a writable directory.
 596        */
 597       bool
 598       setAttachPrefix(const Pathname &attach_prefix);
 599
 600       /**
 601        * Attach the media using the concrete handler (checks all devices).
 602        *
 603        * Remember to release() or close() each id you've attached
 604        * and not need any more. Attach is like an open of a file!
 605        *
 606        * \param accessId A media access id.
 607        * \throws MediaNotOpenException for invalid access id.
 608        */
 609       void
 610       attach(MediaAccessId accessId);
 611
 612       /**
 613        * Release the attached media and optionally eject.
 614        *
 615        * If the \p ejectDev parameter is not empty all other access
 616        * id's are released and the specified drive (CD/DVD drive) is
 617        * ejected.
 618        *
 619        * \param accessId A media access id.
 620        * \param ejectDev Device to eject. None if empty.
 621        * \throws MediaNotOpenException for invalid access id.
 622        */
 623       void
 624       release(MediaAccessId accessId, const std::string & ejectDev = "");
 625
 626       /**
 627        * Release all attached media.
 628        */
 629       void
 630       releaseAll();
 631
 632       /**
 633        * Disconnect a remote media.
 634        *
 635        * This is useful for media which e.g. holds open a connection
 636        * to a server like FTP. After calling disconnect() the media
 637        * object (attach point) is still valid and files are present.
 638        *
 639        * But after calling disconnect() it's not possible to call
 640        * fetch more data using the provideFile() or provideDir()
 641        * functions anymore.
 642        *
 643        * \param accessId A media access id.
 644        * \throws MediaNotOpenException for invalid access id.
 645        */
 646       void
 647       disconnect(MediaAccessId accessId);
 648
 649       /**
 650        * Check if media is attached or not.
 651        *
 652        * \param accessId A media access id.
 653        * \return True if media is attached.
 654        * \throws MediaNotOpenException for invalid access id.
 655        */
 656       bool
 657       isAttached(MediaAccessId accessId) const;
 658
 659       /**
 660        * Returns information if media is on a shared
 661        * physical device or not.
 662        *
 663        * \param accessId A media access id.
 664        * \return True if it is shared, false if not.
 665        * \throws MediaNotOpenException for invalid access id.
 666        */
 667       bool
 668       isSharedMedia(MediaAccessId accessId) const;
 669
 670       /**
 671        * Ask the registered verifier if the attached
 672        * media is the desired one or not.
 673        *
 674        * \param accessId A media access id.
 675        * \return True if media is attached and desired
 676        *         according to the actual verifier.
 677        * \throws MediaNotOpenException for invalid access id.
 678        */
 679       bool
 680       isDesiredMedia(MediaAccessId accessId) const;
 681
 682       /**
 683        * Ask the specified verifier if the attached
 684        * media is the desired one or not.
 685        *
 686        * \param accessId A media access id.
 687        * \param verifier A verifier to use.
 688        * \return True if media is attached and desired
 689        *         according to the specified verifier.
 690        * \throws MediaNotOpenException for invalid access id.
 691        */
 692       bool
 693       isDesiredMedia(MediaAccessId           accessId,
 694                      const MediaVerifierRef &verifier) const;
 695
 696       /**
 697        * Simple check, based on media's URL scheme, telling whether the
 698        * it is possible to physically change the media inside its drive, like
 699        * CDs or DVDs. Useful to decide whether to request media change from
 700        * user or not.
 701        *
 702        * \param accessId The media access id.
 703        * \return <tt>false</tt> if the media is not changeable,
 704        *         <tt>true</tt> otherwise.
 705        * \throws MediaNotOpenException for invalid access id.
 706        */
 707       bool
 708       isChangeable(MediaAccessId accessId);
 709
 710       /**
 711        * Return the local directory that corresponds to medias url,
 712        * no matter if media isAttached or not. Files requested will
 713        * be available at 'localRoot() + filename' or even better
 714        * 'localPath( filename )'
 715        *
 716        * \param accessId A media access id.
 717        * \returns The directory name pointing to the media root
 718        *          in local filesystem or an empty pathname if the
 719        *          media is not attached.
 720        * \throws MediaNotOpenException for invalid access id.
 721        */
 722       Pathname
 723       localRoot(MediaAccessId accessId) const;
 724
 725       /**
 726        * Shortcut for 'localRoot() + pathname', but returns an empty
 727        * pathname if media is not attached.
 728        * Files provided will be available at 'localPath(filename)'.
 729        *
 730        * \param accessId A media access id.
 731        * \param pathname A path name relative to the localRoot().
 732        * \returns The directory name in local filesystem pointing
 733        *          to the desired relative pathname on the media
 734        *          or an empty pathname if the media is not attached.
 735        * \throws MediaNotOpenException for invalid access id.
 736        */
 737       Pathname
 738       localPath(MediaAccessId accessId, const Pathname & pathname) const;
 739
 740     public:
 741       /**
 742        * Provide provide file denoted by relative path below of the
 743        * 'attach point' of the specified media and the path prefix
 744        * on the media.
 745        *
 746        * \param accessId  The media access id to use.
 747        * \param filename  The filename to provide, relative to localRoot().
 748        * \param expectedFileSize The expected filesize, download will stop if it is exceeded
 749        *
 750        * \throws MediaNotOpenException in case of invalid access id.
 751        * \throws MediaNotAttachedException in case, that the media is not attached.
 752        * \throws MediaNotDesiredException in case, that the media verification failed.
 753        * \throws MediaNotAFileException in case, that the requested filename is not a file.
 754        * \throws MediaFileNotFoundException in case, that the requested filenamedoes not exists.
 755        * \throws MediaWriteException in case, that the file can't be copied from from remote source.
 756        * \throws MediaSystemException in case a system operation fails.
 757        * \throws MediaException derived exception, depending on the url (handler).
 758        */
 759
 760       void
 761       provideFile(MediaAccessId accessId,
 762                   const Pathname &filename,
 763                   const ByteCount &expectedFileSize) const;
 764
 765       void
 766       provideFile(MediaAccessId   accessId,
 767                   const Pathname &filename ) const;
 768
 769       /**
 770        * FIXME: see MediaAccess class.
 771        */
 772       void
 773       provideDir(MediaAccessId   accessId,
 774                  const Pathname &dirname) const;
 775
 776       /**
 777        * FIXME: see MediaAccess class.
 778        */
 779       void
 780       provideDirTree(MediaAccessId  accessId,
 781                      const Pathname &dirname) const;
 782
 783       /**
 784        * FIXME: see MediaAccess class.
 785        */
 786       void
 787       releaseFile(MediaAccessId   accessId,
 788                   const Pathname &filename) const;
 789
 790       /**
 791        * FIXME: see MediaAccess class.
 792        */
 793       void
 794       releaseDir(MediaAccessId   accessId,
 795                  const Pathname &dirname) const;
 796
 797       /**
 798        * FIXME: see MediaAccess class.
 799        */
 800       void
 801       releasePath(MediaAccessId   accessId,
 802                   const Pathname &pathname) const;
 803
 804       /**
 805        * FIXME: see MediaAccess class.
 806        */
 807       void
 808       dirInfo(MediaAccessId           accessId,
 809               std::list<std::string> &retlist,
 810               const Pathname         &dirname,
 811               bool                    dots = true) const;
 812
 813       /**
 814        * FIXME: see MediaAccess class.
 815        */
 816       void
 817       dirInfo(MediaAccessId           accessId,
 818               filesystem::DirContent &retlist,
 819               const Pathname         &dirname,
 820               bool                   dots = true) const;
 821
 822       /**
 823        * FIXME: see MediaAccess class.
 824        */
 825       bool doesFileExist(MediaAccessId  accessId,
 826                          const Pathname & filename ) const;
 827
 828       /**
 829        * Fill in a vector of detected ejectable devices and the index of the
 830        * currently attached device within the vector. The contents of the vector
 831        * are the device names (/dev/cdrom and such).
 832        *
 833        * \param accessId Medium id.
 834        * \param devices  vector to load with the device names
 835        * \param index    index of the currently used device in the devices vector
 836        */
 837       void
 838       getDetectedDevices(MediaAccessId accessId,
 839                          std::vector<std::string> & devices,
 840                          unsigned int & index) const;
 841
 842       void
 843       setDeltafile(MediaAccessId   accessId,
 844                   const Pathname &filename ) const;
 845
 846     public:
 847       /**
 848        * Get the modification time of the /etc/mtab file.
 849        * \return Modification time of the /etc/mtab file.
 850        */
 851       static time_t
 852       getMountTableMTime();
 853
 854       /**
 855        * Get current mount entries from /etc/mtab file.
 856        * \return Current mount entries from /etc/mtab file.
 857        */
 858       static std::vector<MountEntry>
 859       getMountEntries();
 860
 861       /**
 862        * Check if the specified \p path is useable as
 863        * attach point.
 864        *
 865        * \param path The attach point to check.
 866        * \param mtab Whether to check against the mtab, too.
 867        * \return True, if it is a directory and there are
 868        *         no another attach points bellow of it.
 869        */
 870       bool
 871       isUseableAttachPoint(const Pathname &path,
 872                            bool            mtab=true) const;
 873
 874     private:
 875       friend class MediaHandler;
 876
 877       /**
 878        * \internal
 879        * Return the attached media reference of the specified
 880        * media access id. Used to resolve nested attachments
 881        * as used in the MediaISO (iso-loop) handler.
 882        * Causes temporary creation of a shared attachment
 883        * (increases reference counters on attachedMedia).
 884        * \param media A media access id.
 885        */
 886       AttachedMedia
 887       getAttachedMedia(MediaAccessId &accessId) const;
 888
 889       /**
 890        * \internal
 891        * Called by media handler in while attach() to retrieve
 892        * attached media reference matching the specified media
 893        * source reference.
 894        * Causes temporary creation of a shared attachment
 895        * (increases reference counters on attachedMedia).
 896        * \param media The media source reference to search for.
 897        */
 898       AttachedMedia
 899       findAttachedMedia(const MediaSourceRef &media) const;
 900
 901       /**
 902        * \internal
 903        * Called by media handler in case of relase(eject=true)
 904        * to release all access id's using the specified media.
 905        * Causes temporary creation of a shared attachment
 906        * (increases reference counters on attachedMedia).
 907        * \param media The media source reference to release.
 908        */
 909       void
 910       forceReleaseShared(const MediaSourceRef &media);
 911
 912     private:
 913       /**
 914        * Static reference to the implementation (singleton).
 915        */
 916       static zypp::RW_pointer<MediaManager_Impl> m_impl;
 917     };
 918
 919
 920     //////////////////////////////////////////////////////////////////
 921   } // namespace media
 922   ////////////////////////////////////////////////////////////////////
 923
 924   ////////////////////////////////////////////////////////////////////
 925 } // namespace zypp
 926 //////////////////////////////////////////////////////////////////////
 927
 928 #endif // ZYPP_MEDIA_MEDIAMANAGER_H
 929
 930 /*
 931 ** vim: set ts=2 sts=2 sw=2 ai et:
 932 */