zypp::media::MediaManager Class Reference

Manages access to the 'physical' media, e.g CDROM drives, Disk volumes, directory trees, etc, using Media Access Url's. More...

#include <MediaManager.h>

Inheritance diagram for zypp::media::MediaManager:

NonCopyable List of all members.

Public Member Functions

 MediaManager ()
 Creates a MediaManager envelope instance.
 ~MediaManager ()
 Destroys MediaManager envelope instance.
MediaAccessId open (const Url &url, const Pathname &preferred_attach_point="")
 Opens the media access for specified with the url.
void close (MediaAccessId accessId)
 Close the media access with specified id.
bool isOpen (MediaAccessId accessId) const
 Query if the media access is open / exists.
std::string protocol (MediaAccessId accessId) const
 Query the protocol name used by the media access handler.
bool downloads (MediaAccessId accessId) const
 Hint if files are downloaded or not.
Url url (MediaAccessId accessId) const
 Returns the Media Access Url of the media access id.
void addVerifier (MediaAccessId accessId, const MediaVerifierRef &verifier)
 Add verifier implementation for the specified media id.
void delVerifier (MediaAccessId accessId)
 Remove verifier for specified media id.
bool setAttachPrefix (const Pathname &attach_prefix)
 Set or resets the directory name, where the media manager handlers create their temporary attach points (see open() function).
void attach (MediaAccessId accessId, bool next=false)
 Attach the media using the concrete handler.
void release (MediaAccessId accessId, bool eject=false)
 Release the attached media and optionally eject.
void disconnect (MediaAccessId accessId)
 Disconnect a remote media.
bool isAttached (MediaAccessId accessId) const
 Check if media is attached or not.
bool isSharedMedia (MediaAccessId accessId) const
 Returns information if media is on a shared physical device or not.
bool isDesiredMedia (MediaAccessId accessId) const
 Ask the registered verifier if the attached media is the desired one or not.
bool isDesiredMedia (MediaAccessId accessId, const MediaVerifierRef &verifier) const
 Ask the specified verifier if the attached media is the desired one or not.
Pathname localRoot (MediaAccessId accessId) const
 Return the local directory that corresponds to medias url, no matter if media isAttached or not.
Pathname localPath (MediaAccessId accessId, const Pathname &pathname) const
 Shortcut for 'localRoot() + pathname', but returns an empty pathname if media is not attached.
void provideFile (MediaAccessId accessId, const Pathname &filename, bool cached=false, bool checkonly=false) const
 Provide provide file denoted by relative path below of the 'attach point' of the specified media and the path prefix on the media.
void provideDir (MediaAccessId accessId, const Pathname &dirname) const
 FIXME: see MediaAccess class.
void provideDirTree (MediaAccessId accessId, const Pathname &dirname) const
 FIXME: see MediaAccess class.
void releaseFile (MediaAccessId accessId, const Pathname &filename) const
 FIXME: see MediaAccess class.
void releaseDir (MediaAccessId accessId, const Pathname &dirname) const
 FIXME: see MediaAccess class.
void releasePath (MediaAccessId accessId, const Pathname &pathname) const
 FIXME: see MediaAccess class.
void dirInfo (MediaAccessId accessId, std::list< std::string > &retlist, const Pathname &dirname, bool dots=true) const
 FIXME: see MediaAccess class.
void dirInfo (MediaAccessId accessId, filesystem::DirContent &retlist, const Pathname &dirname, bool dots=true) const
 FIXME: see MediaAccess class.
bool isUseableAttachPoint (const Pathname &path, bool mtab=true) const
 Check if the specified path is useable as attach point.

Static Public Member Functions

static bool downloads (const Url &url)
 Hint if files will be downloaded when using the specified media url.
static time_t getMountTableMTime ()
 Get the modification time of the /etc/mtab file.
static std::vector< MountEntrygetMountEntries ()
 Get current mount entries from /etc/mtab file.

Private Member Functions

AttachedMedia getAttachedMedia (MediaAccessId &accessId) const
AttachedMedia findAttachedMedia (const MediaSourceRef &media) const
void forceReleaseShared (const MediaSourceRef &media)

Static Private Attributes

static zypp::RW_pointer< MediaManager_Implm_impl
 Static reference to the implementation (singleton).

Friends

class MediaHandler

Detailed Description

Manages access to the 'physical' media, e.g CDROM drives, Disk volumes, directory trees, etc, using Media Access Url's.

Note:
The MediaManager class is just an envelope around an inner singleton like implementation.
That is, you can create as many managers as you want, also temporary in a function call.
But don't declare static MediaManager instances, unless you want to force (mutex) initialization order problems!

Media Access Url

The MediaManager uses several media access handlers (backends), that can be specified by a Media Access URL in its open() method.

All URL's may contain following query parameters, that are reserved by the Source classes and unused/ignored by the media manager:

Currently, following access handlers (backends) are implemented:

MediaCD - CD/DVD drives (cd, dvd)

The access handler for media on CD / DVD drives.

MediaDISK - HD disk volumes (hd)

The access handler for media on a disk volume (partition).

MediaDIR - Local directory tree (dir, file)

The access handler to media stored in a local directory tree.

MediaISO - Loopback ISO images (iso)

The access handler for media in a ISO image (loopback mount).

MediaNFS - NFS directory tree (nfs)

The access handler for media on NFS exported directory tree.

MediaCIFS - CIFS/SMB directory tree (cifs, smb)

The access handler for media in a CIFS/SMB shared directory tree.

MediaCurl - FTP/HTTP directory tree (ftp, http, https)

The access handler to media directory tree on a ftp/http server.

Proxy settings: If no proxy settings are present in tha URLs query parameters, the media handler reads the system wide proxy settings from the /etc/sysconfig/proxy file. If a proxy setting was present, but the proxy password not, it attempts to read the proxy-user variable from the ~/.curlrc (/root/.curlrc) file.
If no proxy setting was present, then libzypp does not pass any proxy settings to curl, but curl fallbacks to use the content of the http_proxy, ftp_proxy, etc environment variables.

Definition at line 426 of file MediaManager.h.


Constructor & Destructor Documentation

zypp::media::MediaManager::MediaManager  ) 
 

Creates a MediaManager envelope instance.

In the case, that the inner implementation is not already allocated, and the MediaManager constructor was unable to allocate it, a std::bad_alloc exception is thrown.

All further instances increase the use counter only.

Exceptions:
std::bad_alloc 

Definition at line 389 of file MediaManager.cc.

References zypp::media::g_Mutex, m_impl, and zypp::RW_pointer< _D, _Traits >::reset().

zypp::media::MediaManager::~MediaManager  ) 
 

Destroys MediaManager envelope instance.

Decreases the use counter of the inner implementation.

Definition at line 399 of file MediaManager.cc.


Member Function Documentation

MediaAccessId zypp::media::MediaManager::open const Url url,
const Pathname preferred_attach_point = ""
 

Opens the media access for specified with the url.

If the preferred_attach_point parameter does not point to a usable attach point directory, the media manager automatically creates a temporary attach point in a default directory. This default directory can be changed using setAttachPrefix() function.

Remember to close() each id you've opened and not need any more. It is like a new and delete!

Parameters:
url The Media Access Url.
preferred_attach_point The preferred, already existing directory, where the media should be attached.
Returns:
a new media access id.
Exceptions:
std::bad_alloc 
MediaException 

Definition at line 405 of file MediaManager.cc.

References zypp::Url::asString(), DBG, zypp::media::g_Mutex, handler, m_impl, url(), and verifier.

Referenced by zypp::SourceFactory::createFrom(), zypp::SourceFactory::listProducts(), and zypp::source::SourceImpl::redirect().

void zypp::media::MediaManager::close MediaAccessId  accessId  ) 
 

Close the media access with specified id.

Parameters:
accessId The media access id to close.

Definition at line 427 of file MediaManager.cc.

References zypp::media::g_Mutex, m_impl, and ZYPP_THROW.

Referenced by zypp::source::MediaSet::redirect(), zypp::source::MediaSet::reset(), zypp::media::MediaISO::~MediaISO(), and zypp::source::MediaSet::~MediaSet().

bool zypp::media::MediaManager::isOpen MediaAccessId  accessId  )  const
 

Query if the media access is open / exists.

Parameters:
accessId The media access id to query.
Returns:
true, if access id is known and open.

Definition at line 463 of file MediaManager.cc.

References zypp::media::g_Mutex, and m_impl.

Referenced by zypp::source::MediaSet::redirect(), zypp::source::MediaSet::reset(), and zypp::media::MediaISO::~MediaISO().

std::string zypp::media::MediaManager::protocol MediaAccessId  accessId  )  const
 

Query the protocol name used by the media access handler.

Similar to url().getScheme().

Parameters:
accessId The media access id to query.
Returns:
The protocol name used by the media access handler, otherwise 'unknown'.
Exceptions:
MediaNotOpenException for invalid access id.

Definition at line 474 of file MediaManager.cc.

References zypp::media::g_Mutex, and m_impl.

bool zypp::media::MediaManager::downloads MediaAccessId  accessId  )  const
 

Hint if files are downloaded or not.

Parameters:
accessId The media access id to query.
Returns:
True, if provideFile downloads files.

Definition at line 485 of file MediaManager.cc.

References zypp::media::g_Mutex, and m_impl.

Referenced by zypp::source::SourceImpl::remote().

bool zypp::media::MediaManager::downloads const Url url  )  [static]
 

Hint if files will be downloaded when using the specified media url.

Note:
This hint is based on the url scheme only and does not imply, that the URL is valid.
Parameters:
url The media URL to check.
Returns:
True, if the files are downloaded.

Definition at line 497 of file MediaManager.cc.

References zypp::media::MediaAccess::downloads(), and url().

Url zypp::media::MediaManager::url MediaAccessId  accessId  )  const
 

Returns the Media Access Url of the media access id.

Parameters:
accessId The media access id to query.
Returns:
The Media Access Url used by the media access id.
Exceptions:
MediaNotOpenException for invalid access id.

Definition at line 504 of file MediaManager.cc.

References zypp::media::g_Mutex, and m_impl.

Referenced by zypp::source::SourceImpl::changeMedia(), downloads(), zypp::source::SourceImpl::factoryCtor(), open(), and zypp::source::MediaSet::reattach().

void zypp::media::MediaManager::addVerifier MediaAccessId  accessId,
const MediaVerifierRef verifier
 

Add verifier implementation for the specified media id.

By default, the NoVerifier is used.

Parameters:
accessId A media access id.
verifier The new verifier.
Exceptions:
MediaNotOpenException for invalid access id.

Definition at line 515 of file MediaManager.cc.

References DBG, zypp::media::g_Mutex, m_impl, verifier, and ZYPP_THROW.

Referenced by zypp::SourceFactory::createFrom(), and zypp::source::SourceImpl::resetMediaVerifier().

void zypp::media::MediaManager::delVerifier MediaAccessId  accessId  ) 
 

Remove verifier for specified media id.

It resets the verifier to NoVerifier.

Parameters:
accessId A media access id.
Exceptions:
MediaNotOpenException for invalid access id.

Definition at line 534 of file MediaManager.cc.

References DBG, zypp::media::g_Mutex, m_impl, and verifier.

Referenced by zypp::source::SourceImpl::resetMediaVerifier().

bool zypp::media::MediaManager::setAttachPrefix const Pathname attach_prefix  ) 
 

Set or resets the directory name, where the media manager handlers create their temporary attach points (see open() function).

It has effect to newly created temporary attach points only.

Parameters:
attach_prefix The new prefix for temporary attach points, or empty pathname to reset to defaults.
Returns:
True on success, false if the attach_prefix parameters contains a path name, that does not point to a writable directory.

Definition at line 550 of file MediaManager.cc.

References zypp::media::g_Mutex, and zypp::media::MediaHandler::setAttachPrefix().

Referenced by zypp::source::MediaSet::reattach().

void zypp::media::MediaManager::attach MediaAccessId  accessId,
bool  next = false
 

Attach the media using the concrete handler.

Remember to release() or close() each id you've attached and not need any more. Attach is like an open of a file!

Parameters:
accessId A media access id.
next Whether to try the next drive if avaliable.
Exceptions:
MediaNotOpenException for invalid access id.

Definition at line 559 of file MediaManager.cc.

References DBG, zypp::media::g_Mutex, and m_impl.

Referenced by zypp::SourceFactory::createFrom(), zypp::source::MediaSet::getMediaAccessId(), zypp::SourceFactory::listProducts(), and zypp::source::MediaSet::reattach().

void zypp::media::MediaManager::release MediaAccessId  accessId,
bool  eject = false
 

Release the attached media and optionally eject.

If the eject parameter is set to true and there is currently an attached drive, all other access id's are released and the drive (CD/DVD drive) is ejected. In case that there is currently no attached drive, a eject set to true causes to eject all drives that are _not_ used by another access id's.

Parameters:
accessId A media access id.
eject Whether to eject the drive.
Exceptions:
MediaNotOpenException for invalid access id.

Definition at line 571 of file MediaManager.cc.

References DBG, zypp::media::g_Mutex, m_impl, and ZYPP_CAUGHT.

Referenced by zypp::SourceFactory::listProducts(), zypp::source::SourceImpl::provideDirTree(), zypp::source::SourceImpl::provideJustFile(), zypp::source::MediaSet::reattach(), zypp::source::MediaSet::release(), and zypp::source::SourceImpl::~SourceImpl().

void zypp::media::MediaManager::disconnect MediaAccessId  accessId  ) 
 

Disconnect a remote media.

This is useful for media which e.g. holds open a connection to a server like FTP. After calling disconnect() the media object (attach point) is still valid and files are present.

But after calling disconnect() it's not possible to call fetch more data using the provideFile() or provideDir() functions anymore.

Parameters:
accessId A media access id.
Exceptions:
MediaNotOpenException for invalid access id.

Definition at line 612 of file MediaManager.cc.

References zypp::media::g_Mutex, and m_impl.

bool zypp::media::MediaManager::isAttached MediaAccessId  accessId  )  const
 

Check if media is attached or not.

Parameters:
accessId A media access id.
Returns:
True if media is attached.
Exceptions:
MediaNotOpenException for invalid access id.

Definition at line 623 of file MediaManager.cc.

References zypp::media::g_Mutex, and m_impl.

Referenced by zypp::source::MediaSet::getMediaAccessId(), and zypp::source::MediaSet::release().

bool zypp::media::MediaManager::isSharedMedia MediaAccessId  accessId  )  const
 

Returns information if media is on a shared physical device or not.

Parameters:
accessId A media access id.
Returns:
True if it is shared, false if not.
Exceptions:
MediaNotOpenException for invalid access id.

Definition at line 633 of file MediaManager.cc.

References zypp::media::g_Mutex, and m_impl.

bool zypp::media::MediaManager::isDesiredMedia MediaAccessId  accessId  )  const
 

Ask the registered verifier if the attached media is the desired one or not.

Parameters:
accessId A media access id.
Returns:
True if media is attached and desired according to the actual verifier.
Exceptions:
MediaNotOpenException for invalid access id.

Definition at line 644 of file MediaManager.cc.

References zypp::media::g_Mutex, and m_impl.

bool zypp::media::MediaManager::isDesiredMedia MediaAccessId  accessId,
const MediaVerifierRef verifier
const
 

Ask the specified verifier if the attached media is the desired one or not.

Parameters:
accessId A media access id.
verifier A verifier to use.
Returns:
True if media is attached and desired according to the specified verifier.
Exceptions:
MediaNotOpenException for invalid access id.

Definition at line 673 of file MediaManager.cc.

References desired, zypp::media::g_Mutex, m_impl, verifier, and ZYPP_THROW.

Pathname zypp::media::MediaManager::localRoot MediaAccessId  accessId  )  const
 

Return the local directory that corresponds to medias url, no matter if media isAttached or not.

Files requested will be available at 'localRoot() + filename' or even better 'localPath( filename )'

Parameters:
accessId A media access id.
Returns:
The directory name pointing to the media root in local filesystem or an empty pathname if the media is not attached.
Exceptions:
MediaNotOpenException for invalid access id.

Definition at line 704 of file MediaManager.cc.

References zypp::media::g_Mutex, and m_impl.

Pathname zypp::media::MediaManager::localPath MediaAccessId  accessId,
const Pathname pathname
const
 

Shortcut for 'localRoot() + pathname', but returns an empty pathname if media is not attached.

Files provided will be available at 'localPath(filename)'.

Parameters:
accessId A media access id.
pathname A path name relative to the localRoot().
Returns:
The directory name in local filesystem pointing to the desired relative pathname on the media or an empty pathname if the media is not attached.
Exceptions:
MediaNotOpenException for invalid access id.

Definition at line 717 of file MediaManager.cc.

References zypp::media::g_Mutex, and m_impl.

Referenced by zypp::SourceFactory::listProducts(), zypp::source::SourceImpl::provideDirTree(), zypp::source::SourceImpl::provideJustFile(), and zypp::source::SourceImpl::tryToProvideFile().

void zypp::media::MediaManager::provideFile MediaAccessId  accessId,
const Pathname filename,
bool  cached = false,
bool  checkonly = false
const
 

Provide provide file denoted by relative path below of the 'attach point' of the specified media and the path prefix on the media.

Parameters:
accessId The media access id to use.
filename The filename to provide, relative to localRoot().
cached If cached is set to true, the function checks, if the file already exists and doesn't download it again if it does. Currently only the existence is checked, no other file attributes.
checkonly If this and 'cached' are set to true only the existence of the file is checked but it's not downloaded. If 'cached' is unset an errer is returned always.
Exceptions:
MediaNotOpenException in case of invalid access id.
MediaNotAttachedException in case, that the media is not attached.
MediaNotDesiredException in case, that the media verification failed.
MediaNotAFileException in case, that the requested filename is not a file.
MediaFileNotFoundException in case, that the requested filenamedoes not exists.
MediaWriteException in case, that the file can't be copied from from remote source.
MediaSystemException in case a system operation fails.
MediaException derived exception, depending on the url (handler).

Definition at line 731 of file MediaManager.cc.

References zypp::media::g_Mutex, and m_impl.

Referenced by zypp::SourceFactory::listProducts(), zypp::source::SourceImpl::provideJustFile(), and zypp::source::SourceImpl::tryToProvideFile().

void zypp::media::MediaManager::provideDir MediaAccessId  accessId,
const Pathname dirname
const
 

FIXME: see MediaAccess class.

Definition at line 747 of file MediaManager.cc.

References zypp::media::g_Mutex, and m_impl.

void zypp::media::MediaManager::provideDirTree MediaAccessId  accessId,
const Pathname dirname
const
 

FIXME: see MediaAccess class.

Definition at line 761 of file MediaManager.cc.

References zypp::media::g_Mutex, and m_impl.

Referenced by zypp::source::SourceImpl::provideDirTree().

void zypp::media::MediaManager::releaseFile MediaAccessId  accessId,
const Pathname filename
const
 

FIXME: see MediaAccess class.

Definition at line 775 of file MediaManager.cc.

References zypp::media::g_Mutex, and m_impl.

Referenced by zypp::source::SourceImpl::releaseFile().

void zypp::media::MediaManager::releaseDir MediaAccessId  accessId,
const Pathname dirname
const
 

FIXME: see MediaAccess class.

Definition at line 789 of file MediaManager.cc.

References zypp::media::g_Mutex, and m_impl.

Referenced by zypp::source::SourceImpl::releaseDir().

void zypp::media::MediaManager::releasePath MediaAccessId  accessId,
const Pathname pathname
const
 

FIXME: see MediaAccess class.

Definition at line 804 of file MediaManager.cc.

References zypp::media::g_Mutex, and m_impl.

Referenced by zypp::source::SourceImpl::releaseDir().

void zypp::media::MediaManager::dirInfo MediaAccessId  accessId,
std::list< std::string > &  retlist,
const Pathname dirname,
bool  dots = true
const
 

FIXME: see MediaAccess class.

Definition at line 818 of file MediaManager.cc.

References zypp::media::g_Mutex, and m_impl.

Referenced by zypp::source::SourceImpl::dirInfo().

void zypp::media::MediaManager::dirInfo MediaAccessId  accessId,
filesystem::DirContent retlist,
const Pathname dirname,
bool  dots = true
const
 

FIXME: see MediaAccess class.

Definition at line 835 of file MediaManager.cc.

References zypp::media::g_Mutex, and m_impl.

time_t zypp::media::MediaManager::getMountTableMTime  )  [static]
 

Get the modification time of the /etc/mtab file.

Returns:
Modification time of the /etc/mtab file.

Definition at line 853 of file MediaManager.cc.

References zypp::media::g_Mutex, and zypp::media::MediaManager_Impl::getMountTableMTime().

Referenced by zypp::media::MediaHandler::checkAttached().

MountEntries zypp::media::MediaManager::getMountEntries  )  [static]
 

Get current mount entries from /etc/mtab file.

Returns:
Current mount entries from /etc/mtab file.

Definition at line 862 of file MediaManager.cc.

References zypp::media::g_Mutex, and zypp::media::MediaManager_Impl::getMountEntries().

Referenced by zypp::media::MediaHandler::checkAttached(), and zypp::media::MediaHandler::forceRelaseAllMedia().

bool zypp::media::MediaManager::isUseableAttachPoint const Pathname path,
bool  mtab = true
const
 

Check if the specified path is useable as attach point.

Parameters:
path The attach point to check.
mtab Whether to check against the mtab, too.
Returns:
True, if it is a directory and there are no another attach points bellow of it.

Definition at line 871 of file MediaManager.cc.

References zypp::filesystem::Pathname::asString(), zypp::filesystem::Pathname::empty(), zypp::media::g_Mutex, and m_impl.

Referenced by zypp::media::MediaHandler::isUseableAttachPoint().

AttachedMedia zypp::media::MediaManager::getAttachedMedia MediaAccessId accessId  )  const [private]
 

Definition at line 942 of file MediaManager.cc.

References zypp::media::g_Mutex, and m_impl.

Referenced by zypp::media::MediaHandler::dependsOnParent().

AttachedMedia zypp::media::MediaManager::findAttachedMedia const MediaSourceRef media  )  const [private]
 

Definition at line 953 of file MediaManager.cc.

References zypp::media::g_Mutex, m_impl, and zypp::media::AttachedMedia::mediaSource.

void zypp::media::MediaManager::forceReleaseShared const MediaSourceRef media  )  [private]
 

Definition at line 975 of file MediaManager.cc.

References zypp::media::g_Mutex, m_impl, and zypp::media::AttachedMedia::mediaSource.


Friends And Related Function Documentation

friend class MediaHandler [friend]
 

Definition at line 809 of file MediaManager.h.


Member Data Documentation

zypp::RW_pointer< MediaManager_Impl > zypp::media::MediaManager::m_impl [static, private]
 

Static reference to the implementation (singleton).

Definition at line 850 of file MediaManager.h.

Referenced by addVerifier(), attach(), close(), delVerifier(), dirInfo(), disconnect(), downloads(), findAttachedMedia(), forceReleaseShared(), getAttachedMedia(), isAttached(), isDesiredMedia(), isOpen(), isSharedMedia(), isUseableAttachPoint(), localPath(), localRoot(), MediaManager(), open(), protocol(), provideDir(), provideDirTree(), provideFile(), release(), releaseDir(), releaseFile(), releasePath(), and url().


The documentation for this class was generated from the following files:
Generated on Thu Jul 6 00:07:32 2006 for zypp by  doxygen 1.4.6