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>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.
287 * "nfs://nfs-server/exported/path"
288 * "nfs://nfs-server/exported/path?mountoptions=ro"
290 * - Query parameters:
291 * - <tt>mountoptions</tt>:
292 * The mount options separated by comma ','.
293 * Default is the "ro" option.
295 * The authority component has to provide a hostname.
296 * Username, password and port are currently ignored.
298 * Mandatory URL component, that specifies the exported
299 * (sub-)directory on the NFS server, where the desired
302 * \subsection MediaCIFS_Url MediaCIFS - CIFS/SMB directory tree (cifs, smb)
303 * The access handler for media in a CIFS/SMB shared directory tree.
309 * "cifs://servername/share/path/on/the/share"
310 * "cifs://username:passwd@servername/share/path/on/the/share?mountoptions=ro"
311 * "smb://servername/share/path/on/the/share"
312 * "smb://username:passwd@servername/share/path/on/the/share?mountoptions=ro"
314 * Note: There is no difference between cifs and smb scheme
315 * (any more). In both cases the 'cifs' filesystem is used.
316 * - Query parameters:
317 * - <tt>mountoptions</tt>:
318 * The mount options separated by a comma ','. Default are the
319 * "ro" and "guest" options.
320 * - <tt>workgroup</tt>:
321 * The name of the workgroup.
322 * - <tt>username</tt>:
323 * Alternative username to username in URL authority.
324 * - <tt>password</tt>:
325 * Alternative password to password in URL authority.
327 * Alternative username (cifs specific variant?)
329 * Alternative password (cifs specific variant?)
331 * The authority component has to provide a hostname. Optionally
332 * also a username and password.
334 * Mandatory URL component, that specifies the share name with
335 * optional subdirectory, where the desired files are located.
337 * \subsection MediaCurl_Url MediaCurl - FTP/HTTP directory tree (ftp, http, https)
338 * The access handler to media directory tree on a ftp/http server.
345 * "ftp://server/relative/path/to/media/dir"
346 * "ftp://server/%2fabsolute/path/to/media/dir"
348 * "ftp://user:pass@server/path/to/media/dir"
349 * "ftp://user:pass@server/%2f/home/user/path/to/media/dir"
351 * "http://server/path/on/server"
352 * "http://user:pass@server/path"
353 * "https://user:pass@server/path?proxy=foo&proxyuser=me&proxypass=pw"
355 * Note: The "ftp" url scheme supports absolute and relative
356 * paths to the default ftp server directory
357 * (<a href="http://rfc.net/rfc1738.html">RFC1738, Section 3.2.2</a>).<br>
358 * To use an absolute path, you have to prepend the path with an
359 * additional slash, what results in a "/%2f" combination
360 * (second "/" encoded to "%2f") at the begin of the URL path.
362 * This is important, especially in user authenticated ftp,
363 * where the users home is usually the default directory of the
364 * server (except when the server chroots into the users home
367 * For example, if the user "user" has a home directory
368 * "/home/user", you can use either an URL with a relative path
369 * to the home directory "ftp://user:pass@server/path/to/media"
370 * or the absolute path
371 * "ftp://user:pass@server/%2fhome/user/path/to/media" -- both
372 * URLs points to the same directory on the server.
373 * - Query parameters:
375 * A proxy hostname or hostname and port separated by ':'.
376 * - <tt>proxyport</tt>:
377 * Alternative way to provide the proxy port.
378 * - <tt>proxyuser</tt>:
379 * The proxy username.
380 * - <tt>proxypass</tt>:
381 * The proxy password.
382 * - <tt>ssl_capath</tt>:
383 * The absolute CA directory to use, default is /etc/ssl/certs.
384 * - <tt>ssl_verify</tt>: Flag to modify the ssl verify behaviour.
385 * Valid values are: 'yes', 'no' and a comma separated list of
386 * 'host' and 'peer' flags.
388 * disables ssl verify
390 * enables ssl verify, this is the default
391 * and is equivalent to 'host,peer'.
392 * - 'host': The server is considered the intended one, when the
393 * 'Common Name' field or a 'Subject Alternate Name' field in
394 * the certificate matches the host name in the URL.
395 * - 'peer': Verifies whether the certificate provided by the
396 * server is authentic against the chain of digital signatures
397 * found in <tt>ssl_capath</tt>.
398 * - <tt>timeout</tt>:
399 * Transfer timeout in seconds between 0 and 3600, 0 disables
400 * the timeout, default timeout is 180 seconds.
401 * - <tt>auth</tt>: A comma separated list of http authentication
402 * method names to use: 'basic', 'digest', 'ntlm', 'negotiate',
403 * 'spnego', 'gssnego'.
404 * Note, that this list depends on the list of methods supported
405 * by the curl library.
407 * The authority component has to provide a hostname. Optionally
408 * also a username and password. In case of the 'ftp' scheme,
409 * username and password defaults to 'anonymous' and 'yast2@'.
411 * Mandatory URL component, that specifies the path name on the
412 * server, where the desired files are located.
414 * Proxy settings: If no proxy settings are present in tha URLs
415 * query parameters, the media handler reads the system wide proxy
416 * settings from the <tt>/etc/sysconfig/proxy</tt> file.
417 * If a proxy setting was present, but the proxy password not,
418 * it attempts to read the <tt>proxy-user</tt> variable from the
419 * <tt>~/.curlrc</tt> (<tt>/root/.curlrc</tt>) file.
421 * If no proxy setting was present, then libzypp does not pass any
422 * proxy settings to curl, but curl fallbacks to use the content of
423 * the <tt>http_proxy</tt>, <tt>ftp_proxy</tt>, etc environment
426 class MediaManager: private zypp::base::NonCopyable
430 * Creates a MediaManager envelope instance.
432 * In the case, that the inner implementation is not already
433 * allocated, and the MediaManager constructor was unable to
434 * allocate it, a std::bad_alloc exception is thrown.
436 * All further instances increase the use counter only.
438 * \throws std::bad_alloc
443 * Destroys MediaManager envelope instance.
444 * Decreases the use counter of the inner implementation.
449 * Opens the media access for specified with the url.
451 * If the \p preferred_attach_point parameter does not
452 * point to a usable attach point directory, the media
453 * manager automatically creates a temporary attach
454 * point in a default directory. This default directory
455 * can be changed using setAttachPrefix() function.
457 * Remember to close() each id you've opened and not
458 * need any more. It is like a new and delete!
460 * \param url The \ref MediaAccessUrl.
461 * \param preferred_attach_point The preferred, already
462 * existing directory, where the media should be
464 * \return a new media access id.
465 * \throws std::bad_alloc
466 * \throws MediaException
469 open(const Url &url, const Pathname & preferred_attach_point = "");
472 * Close the media access with specified id.
473 * \param accessId The media access id to close.
476 close(MediaAccessId accessId);
479 * Query if the media access is open / exists.
481 * \param accessId The media access id to query.
482 * \return true, if access id is known and open.
485 isOpen(MediaAccessId accessId) const;
488 * Query the protocol name used by the media access
489 * handler. Similar to url().getScheme().
491 * \param accessId The media access id to query.
492 * \return The protocol name used by the media access
493 * handler, otherwise 'unknown'.
494 * \throws MediaNotOpenException for invalid access id.
497 protocol(MediaAccessId accessId) const;
500 * Hint if files are downloaded or not.
501 * \param accessId The media access id to query.
502 * \return True, if provideFile downloads files.
505 downloads(MediaAccessId accessId) const;
508 * Hint if files will be downloaded when using the
509 * specified media \p url.
511 * @note This hint is based on the \p url scheme
512 * only and does not imply, that the URL is valid.
514 * @param url The media URL to check.
515 * @return True, if the files are downloaded.
518 downloads(const Url &url);
521 * Returns the \ref MediaAccessUrl of the media access id.
523 * \param accessId The media access id to query.
524 * \return The \ref MediaAccessUrl used by the media access id.
525 * \throws MediaNotOpenException for invalid access id.
528 url(MediaAccessId accessId) const;
532 * Add verifier implementation for the specified media id.
533 * By default, the NoVerifier is used.
535 * \param accessId A media access id.
536 * \param verifier The new verifier.
537 * \throws MediaNotOpenException for invalid access id.
540 addVerifier(MediaAccessId accessId,
541 const MediaVerifierRef &verifier);
544 * Remove verifier for specified media id.
545 * It resets the verifier to NoVerifier.
547 * \param accessId A media access id.
548 * \throws MediaNotOpenException for invalid access id.
551 delVerifier(MediaAccessId accessId);
555 * Set or resets the directory name, where the media manager
556 * handlers create their temporary attach points (see open()
558 * It has effect to newly created temporary attach points only.
560 * \param attach_prefix The new prefix for temporary attach
561 * points, or empty pathname to reset to defaults.
562 * \return True on success, false if the \p attach_prefix
563 * parameters contains a path name, that does not
564 * point to a writable directory.
567 setAttachPrefix(const Pathname &attach_prefix);
570 * Attach the media using the concrete handler.
572 * Remember to release() or close() each id you've attached
573 * and not need any more. Attach is like an open of a file!
575 * \param accessId A media access id.
576 * \param next Whether to try the next drive if avaliable.
577 * \throws MediaNotOpenException for invalid access id.
578 * \deprecated in favor of attachDesiredMedia(MediaAccessId) which looks
579 * for a desirable media on all available devices.
582 attach(MediaAccessId accessId, bool next = false) ZYPP_DEPRECATED;
585 attachDesiredMedia(MediaAccessId accessId);
588 * Release the attached media and optionally eject.
590 * If the \p ejectDev parameter is not empty all other access
591 * id's are released and the specified drive (CD/DVD drive) is
594 * \param accessId A media access id.
595 * \param ejectDev Device to eject. None if empty.
596 * \throws MediaNotOpenException for invalid access id.
599 release(MediaAccessId accessId, const std::string & ejectDev = "");
602 * Release all attached media.
608 * Disconnect a remote media.
610 * This is useful for media which e.g. holds open a connection
611 * to a server like FTP. After calling disconnect() the media
612 * object (attach point) is still valid and files are present.
614 * But after calling disconnect() it's not possible to call
615 * fetch more data using the provideFile() or provideDir()
618 * \param accessId A media access id.
619 * \throws MediaNotOpenException for invalid access id.
622 disconnect(MediaAccessId accessId);
625 * Check if media is attached or not.
627 * \param accessId A media access id.
628 * \return True if media is attached.
629 * \throws MediaNotOpenException for invalid access id.
632 isAttached(MediaAccessId accessId) const;
635 * Returns information if media is on a shared
636 * physical device or not.
638 * \param accessId A media access id.
639 * \return True if it is shared, false if not.
640 * \throws MediaNotOpenException for invalid access id.
643 isSharedMedia(MediaAccessId accessId) const;
646 * Ask the registered verifier if the attached
647 * media is the desired one or not.
649 * \param accessId A media access id.
650 * \return True if media is attached and desired
651 * according to the actual verifier.
652 * \throws MediaNotOpenException for invalid access id.
655 isDesiredMedia(MediaAccessId accessId) const;
658 * Ask the specified verifier if the attached
659 * media is the desired one or not.
661 * \param accessId A media access id.
662 * \param verifier A verifier to use.
663 * \return True if media is attached and desired
664 * according to the specified verifier.
665 * \throws MediaNotOpenException for invalid access id.
668 isDesiredMedia(MediaAccessId accessId,
669 const MediaVerifierRef &verifier) const;
672 * Simple check, based on media's URL scheme, telling whether the
673 * it is possible to physically change the media inside its drive, like
674 * CDs or DVDs. Useful to decide whether to request media change from
677 * \param accessId The media access id.
678 * \return <tt>false</tt> if the media is not changeable,
679 * <tt>true</tt> otherwise.
680 * \throws MediaNotOpenException for invalid access id.
683 isChangeable(MediaAccessId accessId);
686 * Return the local directory that corresponds to medias url,
687 * no matter if media isAttached or not. Files requested will
688 * be available at 'localRoot() + filename' or even better
689 * 'localPath( filename )'
691 * \param accessId A media access id.
692 * \returns The directory name pointing to the media root
693 * in local filesystem or an empty pathname if the
694 * media is not attached.
695 * \throws MediaNotOpenException for invalid access id.
698 localRoot(MediaAccessId accessId) const;
701 * Shortcut for 'localRoot() + pathname', but returns an empty
702 * pathname if media is not attached.
703 * Files provided will be available at 'localPath(filename)'.
705 * \param accessId A media access id.
706 * \param pathname A path name relative to the localRoot().
707 * \returns The directory name in local filesystem pointing
708 * to the desired relative pathname on the media
709 * or an empty pathname if the media is not attached.
710 * \throws MediaNotOpenException for invalid access id.
713 localPath(MediaAccessId accessId, const Pathname & pathname) const;
717 * Provide provide file denoted by relative path below of the
718 * 'attach point' of the specified media and the path prefix
721 * \param accessId The media access id to use.
722 * \param filename The filename to provide, relative to localRoot().
724 * \throws MediaNotOpenException in case of invalid access id.
725 * \throws MediaNotAttachedException in case, that the media is not attached.
726 * \throws MediaNotDesiredException in case, that the media verification failed.
727 * \throws MediaNotAFileException in case, that the requested filename is not a file.
728 * \throws MediaFileNotFoundException in case, that the requested filenamedoes not exists.
729 * \throws MediaWriteException in case, that the file can't be copied from from remote source.
730 * \throws MediaSystemException in case a system operation fails.
731 * \throws MediaException derived exception, depending on the url (handler).
735 provideFile(MediaAccessId accessId,
736 const Pathname &filename ) const;
739 * FIXME: see MediaAccess class.
742 provideDir(MediaAccessId accessId,
743 const Pathname &dirname) const;
746 * FIXME: see MediaAccess class.
749 provideDirTree(MediaAccessId accessId,
750 const Pathname &dirname) const;
753 * FIXME: see MediaAccess class.
756 releaseFile(MediaAccessId accessId,
757 const Pathname &filename) const;
760 * FIXME: see MediaAccess class.
763 releaseDir(MediaAccessId accessId,
764 const Pathname &dirname) const;
767 * FIXME: see MediaAccess class.
770 releasePath(MediaAccessId accessId,
771 const Pathname &pathname) const;
774 * FIXME: see MediaAccess class.
777 dirInfo(MediaAccessId accessId,
778 std::list<std::string> &retlist,
779 const Pathname &dirname,
780 bool dots = true) const;
783 * FIXME: see MediaAccess class.
786 dirInfo(MediaAccessId accessId,
787 filesystem::DirContent &retlist,
788 const Pathname &dirname,
789 bool dots = true) const;
792 * FIXME: see MediaAccess class.
794 bool doesFileExist(MediaAccessId accessId,
795 const Pathname & filename ) const;
798 * Fill in a vector of detected ejectable devices and the index of the
799 * currently attached device within the vector. The contents of the vector
800 * are the device names (/dev/cdrom and such).
802 * \param accessId Medium id.
803 * \param devices vector to load with the device names
804 * \param index index of the currently used device in the devices vector
807 getDetectedDevices(MediaAccessId accessId,
808 std::vector<std::string> & devices,
809 unsigned int & index) const;
813 * Get the modification time of the /etc/mtab file.
814 * \return Modification time of the /etc/mtab file.
817 getMountTableMTime();
820 * Get current mount entries from /etc/mtab file.
821 * \return Current mount entries from /etc/mtab file.
823 static std::vector<MountEntry>
827 * Check if the specified \p path is useable as
830 * \param path The attach point to check.
831 * \param mtab Whether to check against the mtab, too.
832 * \return True, if it is a directory and there are
833 * no another attach points bellow of it.
836 isUseableAttachPoint(const Pathname &path,
837 bool mtab=true) const;
840 friend class MediaHandler;
844 * Return the attached media reference of the specified
845 * media access id. Used to resolve nested attachments
846 * as used in the MediaISO (iso-loop) handler.
847 * Causes temporary creation of a shared attachment
848 * (increases reference counters on attachedMedia).
849 * \param media A media access id.
852 getAttachedMedia(MediaAccessId &accessId) const;
856 * Called by media handler in while attach() to retrieve
857 * attached media reference matching the specified media
859 * Causes temporary creation of a shared attachment
860 * (increases reference counters on attachedMedia).
861 * \param media The media source reference to search for.
864 findAttachedMedia(const MediaSourceRef &media) const;
868 * Called by media handler in case of relase(eject=true)
869 * to release all access id's using the specified media.
870 * Causes temporary creation of a shared attachment
871 * (increases reference counters on attachedMedia).
872 * \param media The media source reference to release.
875 forceReleaseShared(const MediaSourceRef &media);
879 * Static reference to the implementation (singleton).
881 static zypp::RW_pointer<MediaManager_Impl> m_impl;
885 //////////////////////////////////////////////////////////////////
887 ////////////////////////////////////////////////////////////////////
889 ////////////////////////////////////////////////////////////////////
891 //////////////////////////////////////////////////////////////////////
893 #endif // ZYPP_MEDIA_MEDIAMANAGER_H
896 ** vim: set ts=2 sts=2 sw=2 ai et: