1 /*---------------------------------------------------------------------\
3 | |__ / \ / / . \ . \ |
8 \---------------------------------------------------------------------*/
9 /** \file zypp/media/MediaManager.h
12 #ifndef ZYPP_MEDIA_MEDIAMANAGER_H
13 #define ZYPP_MEDIA_MEDIAMANAGER_H
15 #include <zypp/media/MediaAccess.h>
17 #include <zypp/base/Deprecated.h>
18 #include <zypp/base/NonCopyable.h>
19 #include <zypp/base/PtrTypes.h>
20 #include <zypp/Pathname.h>
26 //////////////////////////////////////////////////////////////////////
28 { ////////////////////////////////////////////////////////////////////
30 ////////////////////////////////////////////////////////////////////
32 { //////////////////////////////////////////////////////////////////
35 ///////////////////////////////////////////////////////////////////
36 typedef zypp::RW_pointer<MediaAccess> MediaAccessRef;
39 typedef MediaAccessId MediaId;
40 typedef unsigned int MediaNr;
43 ///////////////////////////////////////////////////////////////////
44 // forward declaration
46 class MediaManager_Impl;
48 ///////////////////////////////////////////////////////////////////
50 // CLASS NAME : MediaVerifierBase
53 * Interface to implement a media verifier.
55 class MediaVerifierBase //: private zypp::NonCopyable
66 * Returns a string with some info about the verifier.
67 * By default, the type info name is returned.
73 ** Check if the specified attached media contains
74 ** the desired media (e.g. SLES10 CD1).
77 isDesiredMedia(const MediaAccessRef &ref) = 0;
81 ///////////////////////////////////////////////////////////////////
83 // CLASS NAME : NoVerifier
86 * Dummy default media verifier, which is always happy.
88 class NoVerifier : public MediaVerifierBase
91 NoVerifier(): MediaVerifierBase()
99 * Returns the "zypp::media::NoVerifier" string.
105 ** Don't check if the specified attached media contains
106 ** the desired media number. Always return true.
109 isDesiredMedia(const MediaAccessRef &ref)
117 ///////////////////////////////////////////////////////////////////
119 // CLASS NAME : MediaVerifierRef
122 * A shared reference to the MediaVerifier implementation.
124 typedef zypp::RW_pointer<MediaVerifierBase> MediaVerifierRef;
127 ///////////////////////////////////////////////////////////////////
129 // CLASS NAME : MediaManager
132 * Manages access to the 'physical' media, e.g CDROM drives,
133 * Disk volumes, directory trees, etc, using \ref MediaAccessUrl's.
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
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.
147 * All URL's may contain following query parameters, that are
148 * reserved by the Source classes and unused/ignored by the media
150 * - <tt>alias</tt>: A source specific media alias string.
152 * Currently, following access handlers (backends) are implemented:
154 * - \ref MediaDISK_Url
156 * - \ref MediaISO_Url
157 * - \ref MediaDIR_Url
159 * - \ref MediaNFS_Url
160 * - \ref MediaCIFS_Url
161 * - \ref MediaCurl_Url
163 * \subsection MediaCD_Url MediaCD - CD/DVD drives (cd, dvd)
164 * The access handler for media on CD / DVD drives.
166 * - <b>cd</b>: Requires a drive supporting CD media.
167 * - <b>dvd</b>: Prefers a drive supporting DVD media.
171 * "cd:/?devices=/dev/hda,/dev/hdb"
172 * "cd:/subdir?devices=/dev/hda,/dev/hdb"
175 * "dvd:/?devices=/dev/hda,/dev/hdb"
176 * "dvd:/subdir?devices=/dev/hda,/dev/hdb"
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".
185 * The device names will be verified using a HAL query. If one
186 * of the provided devices is not usable (not a block device,
187 * or does not support required media type), an exception is
190 * If the devices parameter is not provided (or empty), all
191 * avaliable CD/DVD drives 'detected' using a HAL query. The
192 * preferred drive (used as first drive) is the drive pointed
193 * to by the symlink "/dev/dvd" ("dvd" scheme only) or
196 * A non-empty authority URL component (e.g. containing a host
197 * name) is not allowed.
199 * Mandatory URL component, that specifies a subdirectory on the
200 * CD/DVD, where the desired files are located.
202 * \subsection MediaDISK_Url MediaDISK - HD disk volumes (hd)
203 * The access handler for media on a disk volume (partition).
208 * "hd:/?device=/dev/hda1"
209 * "hd:/subdir?device=/dev/sda1"
210 * "hd:/subdir?device=/dev/sda1&filesystem=reiserfs"
212 * Note: You can use either "hd:/" (just path, no authority)
213 * or "hd:///" (path and empty authority).
214 * - Query parameters:
216 * Mandatory parameter specifying the name of the block device of
217 * the partition to mount.
218 * - <tt>filesystem</tt>:
219 * The name of the filesystem. Defaults to "auto".
221 * A non-empty authority URL component is not allowed.
223 * Mandatory URL component, that specifies a subdirectory on the disk
224 * partition, where the desired files are located.
226 * \subsection MediaDIR_Url MediaDIR - Local directory tree (dir, file)
227 * The access handler to media stored in a local directory tree.
233 * "dir:/directory/name"
234 * "file:/directory/name"
236 * - Query parameters:
239 * A non-empty authority URL component (e.g. containing
240 * a host name) is not allowed.
242 * Mandatory URL component, that specifies a directory, where
243 * the desired files are located.
245 * \subsection MediaISO_Url MediaISO - Loopback ISO images (iso)
246 * The access handler for media in a ISO image (loopback mount).
251 * "iso:/?iso=/path/to/CD1.iso"
252 * "iso:/?iso=CD1.iso&url=dir:/path/to"
254 * "iso:/?iso=CD1.iso&url=nfs://server/path/to/media"
255 * "iso:/?iso=CD1.iso&url=hd:/?device=/dev/hda"
257 * "iso:/subdir?iso=DVD1.iso&url=nfs://nfs-server/directory&mnt=/nfs/attach/point&filesystem=udf"
259 * - Query parameters:
261 * Mandatory parameter specifying the name of the iso file.<br>
262 * If the url parameter is missed, the iso parameter has to contain
263 * an absolute iso file name.
265 * Optional parameter specifying the URL to the directory containing
267 * The supported URL schemes are: <i><b>hd</b>, <b>dir</b>,
268 * <b>file</b>, <b>nfs</b>, <b>nfs4</b>, <b>smb</b>, <b>cifs</b>.</i>
270 * Optional parameter specifying the prefered attach point for the
272 * - <tt>filesystem</tt>:
273 * Optional name of the filesystem used in the iso file. Defaults
276 * A non-empty authority URL component is not allowed.
278 * Mandatory URL component, that specifies a subdirectory inside of
279 * the iso file, where the desired files are located.
281 * \subsection MediaNFS_Url MediaNFS - NFS directory tree (nfs)
282 * The access handler for media on NFS exported directory tree.
288 * "nfs://nfs-server/exported/path"
289 * "nfs://nfs-server/exported/path?mountoptions=ro"
290 * "nfs://nfs-server/exported/path&type=nfs4"
291 * "nfs4://nfs-server/exported/path"
293 * - Query parameters:
294 * - <tt>mountoptions</tt>:
295 * The mount options separated by comma ','.
296 * Default is the "ro" option.
297 * - <tt>type=nfs4</tt>:
298 * Whether to mount as nfs4. This is the default for scheme nfs4.
300 * The authority component has to provide a hostname.
301 * Username, password and port are currently ignored.
303 * Mandatory URL component, that specifies the exported
304 * (sub-)directory on the NFS server, where the desired
307 * \subsection MediaCIFS_Url MediaCIFS - CIFS/SMB directory tree (cifs, smb)
308 * The access handler for media in a CIFS/SMB shared directory tree.
314 * "cifs://servername/share/path/on/the/share"
315 * "cifs://username:passwd@servername/share/path/on/the/share?mountoptions=ro"
316 * "smb://servername/share/path/on/the/share"
317 * "smb://username:passwd@servername/share/path/on/the/share?mountoptions=ro"
319 * Note: There is no difference between cifs and smb scheme
320 * (any more). In both cases the 'cifs' filesystem is used.
321 * - Query parameters:
322 * - <tt>mountoptions</tt>:
323 * The mount options separated by a comma ','. Default are the
324 * "ro" and "guest" options.
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.
332 * Alternative username (cifs specific variant)
334 * Alternative password (cifs specific variant)
336 * The authority component has to provide a hostname. Optionally
337 * also a username and password.
339 * Mandatory URL component, that specifies the share name with
340 * optional subdirectory, where the desired files are located.
342 * \subsection MediaCurl_Url MediaCurl - FTP/HTTP directory tree (ftp, http, https)
343 * The access handler to media directory tree on a ftp/http server.
350 * "ftp://server/relative/path/to/media/dir"
351 * "ftp://server/%2fabsolute/path/to/media/dir"
353 * "ftp://user:pass@server/path/to/media/dir"
354 * "ftp://user:pass@server/%2f/home/user/path/to/media/dir"
356 * "http://server/path/on/server"
357 * "http://user:pass@server/path"
358 * "https://user:pass@server/path?proxy=foo&proxyuser=me&proxypass=pw"
360 * Note: The "ftp" url scheme supports absolute and relative
361 * paths to the default ftp server directory
362 * (<a href="http://rfc.net/rfc1738.html">RFC1738, Section 3.2.2</a>).<br>
363 * To use an absolute path, you have to prepend the path with an
364 * additional slash, what results in a "/%2f" combination
365 * (second "/" encoded to "%2f") at the begin of the URL path.
367 * This is important, especially in user authenticated ftp,
368 * where the users home is usually the default directory of the
369 * server (except when the server chroots into the users home
372 * For example, if the user "user" has a home directory
373 * "/home/user", you can use either an URL with a relative path
374 * to the home directory "ftp://user:pass@server/path/to/media"
375 * or the absolute path
376 * "ftp://user:pass@server/%2fhome/user/path/to/media" -- both
377 * URLs points to the same directory on the server.
378 * - Query parameters:
380 * A proxy hostname or hostname and port separated by ':'.
381 * - <tt>proxyport</tt>:
382 * Alternative way to provide the proxy port.
383 * - <tt>proxyuser</tt>:
384 * The proxy username.
385 * - <tt>proxypass</tt>:
386 * The proxy password.
387 * - <tt>ssl_capath</tt>:
388 * The absolute CA directory to use, default is /etc/ssl/certs.
389 * - <tt>ssl_verify</tt>: Flag to modify the ssl verify behaviour.
390 * Valid values are: 'yes', 'no' and a comma separated list of
391 * 'host' and 'peer' flags.
393 * disables ssl verify
395 * enables ssl verify, this is the default
396 * and is equivalent to 'host,peer'.
397 * - 'host': The server is considered the intended one, when the
398 * 'Common Name' field or a 'Subject Alternate Name' field in
399 * the certificate matches the host name in the URL.
400 * - 'peer': Verifies whether the certificate provided by the
401 * server is authentic against the chain of digital signatures
402 * found in <tt>ssl_capath</tt>.
403 * - <tt>timeout</tt>:
404 * Transfer timeout in seconds between 0 and 3600, 0 disables
405 * the timeout, default timeout is 180 seconds.
406 * - <tt>auth</tt>: A comma separated list of http authentication
407 * method names to use: 'basic', 'digest', 'ntlm', 'negotiate',
408 * 'spnego', 'gssnego'.
409 * Note, that this list depends on the list of methods supported
410 * by the curl library.
412 * The authority component has to provide a hostname. Optionally
413 * also a username and password. In case of the 'ftp' scheme,
414 * username and password defaults to 'anonymous' and 'yast2@'.
416 * Mandatory URL component, that specifies the path name on the
417 * server, where the desired files are located.
419 * Proxy settings: If no proxy settings are present in tha URLs
420 * query parameters, the media handler reads the system wide proxy
421 * settings from the <tt>/etc/sysconfig/proxy</tt> file.
422 * If a proxy setting was present, but the proxy password not,
423 * it attempts to read the <tt>proxy-user</tt> variable from the
424 * <tt>~/.curlrc</tt> (<tt>/root/.curlrc</tt>) file.
426 * If no proxy setting was present, then libzypp does not pass any
427 * proxy settings to curl, but curl fallbacks to use the content of
428 * the <tt>http_proxy</tt>, <tt>ftp_proxy</tt>, etc environment
431 class MediaManager: private zypp::base::NonCopyable
435 * Creates a MediaManager envelope instance.
437 * In the case, that the inner implementation is not already
438 * allocated, and the MediaManager constructor was unable to
439 * allocate it, a std::bad_alloc exception is thrown.
441 * All further instances increase the use counter only.
443 * \throws std::bad_alloc
448 * Destroys MediaManager envelope instance.
449 * Decreases the use counter of the inner implementation.
454 * Opens the media access for specified with the url.
456 * If the \p preferred_attach_point parameter does not
457 * point to a usable attach point directory, the media
458 * manager automatically creates a temporary attach
459 * point in a default directory. This default directory
460 * can be changed using setAttachPrefix() function.
462 * Remember to close() each id you've opened and not
463 * need any more. It is like a new and delete!
465 * \param url The \ref MediaAccessUrl.
466 * \param preferred_attach_point The preferred, already
467 * existing directory, where the media should be
469 * \return a new media access id.
470 * \throws std::bad_alloc
471 * \throws MediaException
474 open(const Url &url, const Pathname & preferred_attach_point = "");
477 * Close the media access with specified id.
478 * \param accessId The media access id to close.
481 close(MediaAccessId accessId);
484 * Query if the media access is open / exists.
486 * \param accessId The media access id to query.
487 * \return true, if access id is known and open.
490 isOpen(MediaAccessId accessId) const;
493 * Query the protocol name used by the media access
494 * handler. Similar to url().getScheme().
496 * \param accessId The media access id to query.
497 * \return The protocol name used by the media access
498 * handler, otherwise 'unknown'.
499 * \throws MediaNotOpenException for invalid access id.
502 protocol(MediaAccessId accessId) const;
505 * Hint if files are downloaded or not.
506 * \param accessId The media access id to query.
507 * \return True, if provideFile downloads files.
510 downloads(MediaAccessId accessId) const;
512 /** \deprecated Use \ref Url::schemeIsDownloading */
514 ZYPP_DEPRECATED bool downloads(const Url &url)
515 { return url.schemeIsDownloading(); }
518 * Returns the \ref MediaAccessUrl of the media access id.
520 * \param accessId The media access id to query.
521 * \return The \ref MediaAccessUrl used by the media access id.
522 * \throws MediaNotOpenException for invalid access id.
525 url(MediaAccessId accessId) const;
529 * Add verifier implementation for the specified media id.
530 * By default, the NoVerifier is used.
532 * \param accessId A media access id.
533 * \param verifier The new verifier.
534 * \throws MediaNotOpenException for invalid access id.
537 addVerifier(MediaAccessId accessId,
538 const MediaVerifierRef &verifier);
541 * Remove verifier for specified media id.
542 * It resets the verifier to NoVerifier.
544 * \param accessId A media access id.
545 * \throws MediaNotOpenException for invalid access id.
548 delVerifier(MediaAccessId accessId);
552 * Set or resets the directory name, where the media manager
553 * handlers create their temporary attach points (see open()
555 * It has effect to newly created temporary attach points only.
557 * \param attach_prefix The new prefix for temporary attach
558 * points, or empty pathname to reset to defaults.
559 * \return True on success, false if the \p attach_prefix
560 * parameters contains a path name, that does not
561 * point to a writable directory.
564 setAttachPrefix(const Pathname &attach_prefix);
567 * Attach the media using the concrete handler (checks all devices).
569 * Remember to release() or close() each id you've attached
570 * and not need any more. Attach is like an open of a file!
572 * \param accessId A media access id.
573 * \throws MediaNotOpenException for invalid access id.
576 attach(MediaAccessId accessId);
578 /** \deprecated Simply use \ref attach. */
579 ZYPP_DEPRECATED void attachDesiredMedia(MediaAccessId accessId)
580 { attach( accessId ); }
583 * Release the attached media and optionally eject.
585 * If the \p ejectDev parameter is not empty all other access
586 * id's are released and the specified drive (CD/DVD drive) is
589 * \param accessId A media access id.
590 * \param ejectDev Device to eject. None if empty.
591 * \throws MediaNotOpenException for invalid access id.
594 release(MediaAccessId accessId, const std::string & ejectDev = "");
597 * Release all attached media.
603 * Disconnect a remote media.
605 * This is useful for media which e.g. holds open a connection
606 * to a server like FTP. After calling disconnect() the media
607 * object (attach point) is still valid and files are present.
609 * But after calling disconnect() it's not possible to call
610 * fetch more data using the provideFile() or provideDir()
613 * \param accessId A media access id.
614 * \throws MediaNotOpenException for invalid access id.
617 disconnect(MediaAccessId accessId);
620 * Check if media is attached or not.
622 * \param accessId A media access id.
623 * \return True if media is attached.
624 * \throws MediaNotOpenException for invalid access id.
627 isAttached(MediaAccessId accessId) const;
630 * Returns information if media is on a shared
631 * physical device or not.
633 * \param accessId A media access id.
634 * \return True if it is shared, false if not.
635 * \throws MediaNotOpenException for invalid access id.
638 isSharedMedia(MediaAccessId accessId) const;
641 * Ask the registered verifier if the attached
642 * media is the desired one or not.
644 * \param accessId A media access id.
645 * \return True if media is attached and desired
646 * according to the actual verifier.
647 * \throws MediaNotOpenException for invalid access id.
650 isDesiredMedia(MediaAccessId accessId) const;
653 * Ask the specified verifier if the attached
654 * media is the desired one or not.
656 * \param accessId A media access id.
657 * \param verifier A verifier to use.
658 * \return True if media is attached and desired
659 * according to the specified verifier.
660 * \throws MediaNotOpenException for invalid access id.
663 isDesiredMedia(MediaAccessId accessId,
664 const MediaVerifierRef &verifier) const;
667 * Simple check, based on media's URL scheme, telling whether the
668 * it is possible to physically change the media inside its drive, like
669 * CDs or DVDs. Useful to decide whether to request media change from
672 * \param accessId The media access id.
673 * \return <tt>false</tt> if the media is not changeable,
674 * <tt>true</tt> otherwise.
675 * \throws MediaNotOpenException for invalid access id.
678 isChangeable(MediaAccessId accessId);
681 * Return the local directory that corresponds to medias url,
682 * no matter if media isAttached or not. Files requested will
683 * be available at 'localRoot() + filename' or even better
684 * 'localPath( filename )'
686 * \param accessId A media access id.
687 * \returns The directory name pointing to the media root
688 * in local filesystem or an empty pathname if the
689 * media is not attached.
690 * \throws MediaNotOpenException for invalid access id.
693 localRoot(MediaAccessId accessId) const;
696 * Shortcut for 'localRoot() + pathname', but returns an empty
697 * pathname if media is not attached.
698 * Files provided will be available at 'localPath(filename)'.
700 * \param accessId A media access id.
701 * \param pathname A path name relative to the localRoot().
702 * \returns The directory name in local filesystem pointing
703 * to the desired relative pathname on the media
704 * or an empty pathname if the media is not attached.
705 * \throws MediaNotOpenException for invalid access id.
708 localPath(MediaAccessId accessId, const Pathname & pathname) const;
712 * Provide provide file denoted by relative path below of the
713 * 'attach point' of the specified media and the path prefix
716 * \param accessId The media access id to use.
717 * \param filename The filename to provide, relative to localRoot().
719 * \throws MediaNotOpenException in case of invalid access id.
720 * \throws MediaNotAttachedException in case, that the media is not attached.
721 * \throws MediaNotDesiredException in case, that the media verification failed.
722 * \throws MediaNotAFileException in case, that the requested filename is not a file.
723 * \throws MediaFileNotFoundException in case, that the requested filenamedoes not exists.
724 * \throws MediaWriteException in case, that the file can't be copied from from remote source.
725 * \throws MediaSystemException in case a system operation fails.
726 * \throws MediaException derived exception, depending on the url (handler).
730 provideFile(MediaAccessId accessId,
731 const Pathname &filename ) const;
734 * FIXME: see MediaAccess class.
737 provideDir(MediaAccessId accessId,
738 const Pathname &dirname) const;
741 * FIXME: see MediaAccess class.
744 provideDirTree(MediaAccessId accessId,
745 const Pathname &dirname) const;
748 * FIXME: see MediaAccess class.
751 releaseFile(MediaAccessId accessId,
752 const Pathname &filename) const;
755 * FIXME: see MediaAccess class.
758 releaseDir(MediaAccessId accessId,
759 const Pathname &dirname) const;
762 * FIXME: see MediaAccess class.
765 releasePath(MediaAccessId accessId,
766 const Pathname &pathname) const;
769 * FIXME: see MediaAccess class.
772 dirInfo(MediaAccessId accessId,
773 std::list<std::string> &retlist,
774 const Pathname &dirname,
775 bool dots = true) const;
778 * FIXME: see MediaAccess class.
781 dirInfo(MediaAccessId accessId,
782 filesystem::DirContent &retlist,
783 const Pathname &dirname,
784 bool dots = true) const;
787 * FIXME: see MediaAccess class.
789 bool doesFileExist(MediaAccessId accessId,
790 const Pathname & filename ) const;
793 * Fill in a vector of detected ejectable devices and the index of the
794 * currently attached device within the vector. The contents of the vector
795 * are the device names (/dev/cdrom and such).
797 * \param accessId Medium id.
798 * \param devices vector to load with the device names
799 * \param index index of the currently used device in the devices vector
802 getDetectedDevices(MediaAccessId accessId,
803 std::vector<std::string> & devices,
804 unsigned int & index) const;
808 * Get the modification time of the /etc/mtab file.
809 * \return Modification time of the /etc/mtab file.
812 getMountTableMTime();
815 * Get current mount entries from /etc/mtab file.
816 * \return Current mount entries from /etc/mtab file.
818 static std::vector<MountEntry>
822 * Check if the specified \p path is useable as
825 * \param path The attach point to check.
826 * \param mtab Whether to check against the mtab, too.
827 * \return True, if it is a directory and there are
828 * no another attach points bellow of it.
831 isUseableAttachPoint(const Pathname &path,
832 bool mtab=true) const;
835 friend class MediaHandler;
839 * Return the attached media reference of the specified
840 * media access id. Used to resolve nested attachments
841 * as used in the MediaISO (iso-loop) handler.
842 * Causes temporary creation of a shared attachment
843 * (increases reference counters on attachedMedia).
844 * \param media A media access id.
847 getAttachedMedia(MediaAccessId &accessId) const;
851 * Called by media handler in while attach() to retrieve
852 * attached media reference matching the specified media
854 * Causes temporary creation of a shared attachment
855 * (increases reference counters on attachedMedia).
856 * \param media The media source reference to search for.
859 findAttachedMedia(const MediaSourceRef &media) const;
863 * Called by media handler in case of relase(eject=true)
864 * to release all access id's using the specified media.
865 * Causes temporary creation of a shared attachment
866 * (increases reference counters on attachedMedia).
867 * \param media The media source reference to release.
870 forceReleaseShared(const MediaSourceRef &media);
874 * Static reference to the implementation (singleton).
876 static zypp::RW_pointer<MediaManager_Impl> m_impl;
880 //////////////////////////////////////////////////////////////////
882 ////////////////////////////////////////////////////////////////////
884 ////////////////////////////////////////////////////////////////////
886 //////////////////////////////////////////////////////////////////////
888 #endif // ZYPP_MEDIA_MEDIAMANAGER_H
891 ** vim: set ts=2 sts=2 sw=2 ai et: