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 (checks all devices).
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 * \throws MediaNotOpenException for invalid access id.
579 attach(MediaAccessId accessId);
581 /** \deprecated Simply use \ref attach. */
582 ZYPP_DEPRECATED void attachDesiredMedia(MediaAccessId accessId)
583 { attach( accessId ); }
586 * Release the attached media and optionally eject.
588 * If the \p ejectDev parameter is not empty all other access
589 * id's are released and the specified drive (CD/DVD drive) is
592 * \param accessId A media access id.
593 * \param ejectDev Device to eject. None if empty.
594 * \throws MediaNotOpenException for invalid access id.
597 release(MediaAccessId accessId, const std::string & ejectDev = "");
600 * Release all attached media.
606 * Disconnect a remote media.
608 * This is useful for media which e.g. holds open a connection
609 * to a server like FTP. After calling disconnect() the media
610 * object (attach point) is still valid and files are present.
612 * But after calling disconnect() it's not possible to call
613 * fetch more data using the provideFile() or provideDir()
616 * \param accessId A media access id.
617 * \throws MediaNotOpenException for invalid access id.
620 disconnect(MediaAccessId accessId);
623 * Check if media is attached or not.
625 * \param accessId A media access id.
626 * \return True if media is attached.
627 * \throws MediaNotOpenException for invalid access id.
630 isAttached(MediaAccessId accessId) const;
633 * Returns information if media is on a shared
634 * physical device or not.
636 * \param accessId A media access id.
637 * \return True if it is shared, false if not.
638 * \throws MediaNotOpenException for invalid access id.
641 isSharedMedia(MediaAccessId accessId) const;
644 * Ask the registered verifier if the attached
645 * media is the desired one or not.
647 * \param accessId A media access id.
648 * \return True if media is attached and desired
649 * according to the actual verifier.
650 * \throws MediaNotOpenException for invalid access id.
653 isDesiredMedia(MediaAccessId accessId) const;
656 * Ask the specified verifier if the attached
657 * media is the desired one or not.
659 * \param accessId A media access id.
660 * \param verifier A verifier to use.
661 * \return True if media is attached and desired
662 * according to the specified verifier.
663 * \throws MediaNotOpenException for invalid access id.
666 isDesiredMedia(MediaAccessId accessId,
667 const MediaVerifierRef &verifier) const;
670 * Simple check, based on media's URL scheme, telling whether the
671 * it is possible to physically change the media inside its drive, like
672 * CDs or DVDs. Useful to decide whether to request media change from
675 * \param accessId The media access id.
676 * \return <tt>false</tt> if the media is not changeable,
677 * <tt>true</tt> otherwise.
678 * \throws MediaNotOpenException for invalid access id.
681 isChangeable(MediaAccessId accessId);
684 * Return the local directory that corresponds to medias url,
685 * no matter if media isAttached or not. Files requested will
686 * be available at 'localRoot() + filename' or even better
687 * 'localPath( filename )'
689 * \param accessId A media access id.
690 * \returns The directory name pointing to the media root
691 * in local filesystem or an empty pathname if the
692 * media is not attached.
693 * \throws MediaNotOpenException for invalid access id.
696 localRoot(MediaAccessId accessId) const;
699 * Shortcut for 'localRoot() + pathname', but returns an empty
700 * pathname if media is not attached.
701 * Files provided will be available at 'localPath(filename)'.
703 * \param accessId A media access id.
704 * \param pathname A path name relative to the localRoot().
705 * \returns The directory name in local filesystem pointing
706 * to the desired relative pathname on the media
707 * or an empty pathname if the media is not attached.
708 * \throws MediaNotOpenException for invalid access id.
711 localPath(MediaAccessId accessId, const Pathname & pathname) const;
715 * Provide provide file denoted by relative path below of the
716 * 'attach point' of the specified media and the path prefix
719 * \param accessId The media access id to use.
720 * \param filename The filename to provide, relative to localRoot().
722 * \throws MediaNotOpenException in case of invalid access id.
723 * \throws MediaNotAttachedException in case, that the media is not attached.
724 * \throws MediaNotDesiredException in case, that the media verification failed.
725 * \throws MediaNotAFileException in case, that the requested filename is not a file.
726 * \throws MediaFileNotFoundException in case, that the requested filenamedoes not exists.
727 * \throws MediaWriteException in case, that the file can't be copied from from remote source.
728 * \throws MediaSystemException in case a system operation fails.
729 * \throws MediaException derived exception, depending on the url (handler).
733 provideFile(MediaAccessId accessId,
734 const Pathname &filename ) const;
737 * FIXME: see MediaAccess class.
740 provideDir(MediaAccessId accessId,
741 const Pathname &dirname) const;
744 * FIXME: see MediaAccess class.
747 provideDirTree(MediaAccessId accessId,
748 const Pathname &dirname) const;
751 * FIXME: see MediaAccess class.
754 releaseFile(MediaAccessId accessId,
755 const Pathname &filename) const;
758 * FIXME: see MediaAccess class.
761 releaseDir(MediaAccessId accessId,
762 const Pathname &dirname) const;
765 * FIXME: see MediaAccess class.
768 releasePath(MediaAccessId accessId,
769 const Pathname &pathname) const;
772 * FIXME: see MediaAccess class.
775 dirInfo(MediaAccessId accessId,
776 std::list<std::string> &retlist,
777 const Pathname &dirname,
778 bool dots = true) const;
781 * FIXME: see MediaAccess class.
784 dirInfo(MediaAccessId accessId,
785 filesystem::DirContent &retlist,
786 const Pathname &dirname,
787 bool dots = true) const;
790 * FIXME: see MediaAccess class.
792 bool doesFileExist(MediaAccessId accessId,
793 const Pathname & filename ) const;
796 * Fill in a vector of detected ejectable devices and the index of the
797 * currently attached device within the vector. The contents of the vector
798 * are the device names (/dev/cdrom and such).
800 * \param accessId Medium id.
801 * \param devices vector to load with the device names
802 * \param index index of the currently used device in the devices vector
805 getDetectedDevices(MediaAccessId accessId,
806 std::vector<std::string> & devices,
807 unsigned int & index) const;
811 * Get the modification time of the /etc/mtab file.
812 * \return Modification time of the /etc/mtab file.
815 getMountTableMTime();
818 * Get current mount entries from /etc/mtab file.
819 * \return Current mount entries from /etc/mtab file.
821 static std::vector<MountEntry>
825 * Check if the specified \p path is useable as
828 * \param path The attach point to check.
829 * \param mtab Whether to check against the mtab, too.
830 * \return True, if it is a directory and there are
831 * no another attach points bellow of it.
834 isUseableAttachPoint(const Pathname &path,
835 bool mtab=true) const;
838 friend class MediaHandler;
842 * Return the attached media reference of the specified
843 * media access id. Used to resolve nested attachments
844 * as used in the MediaISO (iso-loop) handler.
845 * Causes temporary creation of a shared attachment
846 * (increases reference counters on attachedMedia).
847 * \param media A media access id.
850 getAttachedMedia(MediaAccessId &accessId) const;
854 * Called by media handler in while attach() to retrieve
855 * attached media reference matching the specified media
857 * Causes temporary creation of a shared attachment
858 * (increases reference counters on attachedMedia).
859 * \param media The media source reference to search for.
862 findAttachedMedia(const MediaSourceRef &media) const;
866 * Called by media handler in case of relase(eject=true)
867 * to release all access id's using the specified media.
868 * Causes temporary creation of a shared attachment
869 * (increases reference counters on attachedMedia).
870 * \param media The media source reference to release.
873 forceReleaseShared(const MediaSourceRef &media);
877 * Static reference to the implementation (singleton).
879 static zypp::RW_pointer<MediaManager_Impl> m_impl;
883 //////////////////////////////////////////////////////////////////
885 ////////////////////////////////////////////////////////////////////
887 ////////////////////////////////////////////////////////////////////
889 //////////////////////////////////////////////////////////////////////
891 #endif // ZYPP_MEDIA_MEDIAMANAGER_H
894 ** vim: set ts=2 sts=2 sw=2 ai et: