Media access layer responsible for handling files distributed on a set of media with media change and abort/retry/ingore user callback handling. More...

#include <zypp/MediaSetAccess.h>

Inheritance diagram for zypp::MediaSetAccess:

[legend]

Classes
class	Impl
struct	ReleaseFileGuard

Public Types
enum	ProvideFileOption { PROVIDE_DEFAULT = 0x0 , PROVIDE_NON_INTERACTIVE = 0x1 }

Public Member Functions
	MediaSetAccess (Url url, Pathname prefered_attach_point="")
	Creates a callback enabled media access for specified url.
	MediaSetAccess (std::string label_r, Url url, Pathname prefered_attach_point="")
	MediaSetAccess (MirroredOrigin origin, Pathname prefered_attach_point="")
	Creates a callback enabled media access for specified url.
	MediaSetAccess (std::string label_r, MirroredOrigin origin, Pathname prefered_attach_point="")
	MediaSetAccess (const MediaSetAccess &)=delete
	MediaSetAccess (MediaSetAccess &&)=delete
MediaSetAccess &	operator= (const MediaSetAccess &)=delete
MediaSetAccess &	operator= (MediaSetAccess &&)=delete
	~MediaSetAccess () override
void	setVerifier (unsigned media_nr, const media::MediaVerifierRef &verifier)
	Sets a MediaVerifier verifier for given media number.
const std::string &	label () const
	The label identifing this media set and to be sent in a media change request.
void	setLabel (const std::string &label_r)
	Set the label identifing this media set and to be sent in a media change request.
	ZYPP_DECLARE_FLAGS (ProvideFileOptions, ProvideFileOption)
void	precacheFiles (const std::vector< OnMediaLocation > &files)
	Tries to fetch the given files and precaches them.
Pathname	provideFile (const OnMediaLocation &resource, ProvideFileOptions options=PROVIDE_DEFAULT)
	Provides a file from a media location.
ZYPP_DEPRECATED Pathname	provideFile (const OnMediaLocation &resource, ProvideFileOptions options, const Pathname &deltafile)
Pathname	provideFile (const Pathname &file, unsigned media_nr=1, ProvideFileOptions options=PROVIDE_DEFAULT)
	Provides file from media media_nr.
Pathname	provideOptionalFile (const Pathname &file, unsigned media_nr=1)
	Provides an optional file from media media_nr.
void	releaseFile (const OnMediaLocation &resource)
	Release file from media.
void	releaseFile (const Pathname &file, unsigned media_nr=1)
	Release file from media.
Pathname	provideDir (const Pathname &dir, bool recursive, unsigned media_nr=1, ProvideFileOptions options=PROVIDE_DEFAULT)
	Provides direcotry dir from media number media_nr.
bool	doesFileExist (const Pathname &file, unsigned media_nr=1)
	Checks if a file exists on the specified media, with user callbacks.
void	dirInfo (filesystem::DirContent &retlist, const Pathname &dirname, bool dots=true, unsigned media_nr=1)
	Fills retlist with directory information.
void	release ()
	Release all attached media of this set.
Public Member Functions inherited from zypp::base::ReferenceCounted
	ReferenceCounted ()
	Default ctor.
	ReferenceCounted (const ReferenceCounted &rhs)
	Copy ctor.
virtual	~ReferenceCounted ()
	Dtor.
ReferenceCounted &	operator= (const ReferenceCounted &)
	Assignment.
unsigned	refCount () const
	Return reference counter value.
void	ref () const
	Add a reference.
void	unref () const
	Release a reference.

Static Public Member Functions
static ManagedFile	provideFileFromUrl (const Url &file_url, ProvideFileOptions options=PROVIDE_DEFAULT)
	Provides file from url.
static ManagedFile	provideOptionalFileFromUrl (const Url &file_url)
	Provides an optional file from url.
static Url	rewriteUrl (const Url &url_r, const media::MediaNr medianr)
	Replaces media number in specified url with given medianr.
Static Public Member Functions inherited from zypp::base::ReferenceCounted
static void	add_ref (const ReferenceCounted *ptr_r)
	Called by zypp::intrusive_ptr to add a reference.
static void	release (const ReferenceCounted *ptr_r)
	Called by zypp::intrusive_ptr to add a reference.

Protected Types
using	ProvideOperation = function<void (media::MediaAccessId, const OnMediaLocation &)>

Protected Member Functions
Pathname	provideFileInternal (const OnMediaLocation &resource, ProvideFileOptions options)
	Provides the file from medium number media_nr and returns its local path.
void	provide (const ProvideOperation &op, const OnMediaLocation &resource, ProvideFileOptions options)
media::MediaAccessId	getMediaAccessId (media::MediaNr medianr)
std::ostream &	dumpOn (std::ostream &str) const override
	Overload to realize std::ostream & operator<<.
Protected Member Functions inherited from zypp::base::ReferenceCounted
virtual void	ref_to (unsigned) const
	Trigger derived classes after refCount was increased.
virtual void	unref_to (unsigned) const
	Trigger derived classes after refCount was decreased.

Private Attributes
std::unique_ptr< Impl >	_pimpl
	Pointer to implementation.

Friends
std::ostream &	operator<< (std::ostream &str, const MediaSetAccess &obj)

Related Symbols
(Note that these are not member symbols.)
std::ostream &	operator<< (std::ostream &str, const MediaSetAccess &obj)
	Stream output.
Related Symbols inherited from zypp::base::ReferenceCounted
void	intrusive_ptr_add_ref (const ReferenceCounted *ptr_r)
	intrusive_ptr hook to add_ref.
void	intrusive_ptr_release (const ReferenceCounted *ptr_r)
	intrusive_ptr hook to release.
std::ostream &	operator<< (std::ostream &str, const ReferenceCounted &obj)
	Stream output.

Detailed Description

Media access layer responsible for handling files distributed on a set of media with media change and abort/retry/ingore user callback handling.

This is provided as a means to handle CD or DVD sets accessible through dir, iso, nfs or other URL schemes other than cd/dvd (see MediaManager for info on different implemented media backends). Currently it handles URLs ending on (case insensitive ) CD#, DVD# or MEDIA#, where # is the number of a particular medium in the set.

Examples:

"iso:/?iso=/path/to/iso/images/openSUSE-10.3-Alpha2plus-DVD-x86_64-DVD1.iso"

"dir:/path/to/cdset/sources/openSUSE-10.3/Alpha2plus/CD1"

MediaSetAccess accesses files on the desired medium by rewriting the original URL, replacing the digit (usually) 1 with requested media number and uses MediaManager to get the files from the new URL.

NOTE: Access to medium #1 always uses the url passed to the CTOR!

Additionaly, each media number can be assinged a media verifier which checks if the media we are trying to access is the desired one. See MediaVerifierBase for more info.

Code example:

Url url("dir:/path/to/cdset/sources/openSUSE-10.3/Alpha2plus/CD1");
 
MediaSetAccess access(url);
 
access.setVerifier(1, media1VerifierRef);
access.setVerifier(2, media2VerifierRef);
 
Pathname file1 = "/some/file/on/media1";
Pathname providedfile1 = access.provideFile(file1, 1);
Pathname file2 = "/some/file/on/media2";
Pathname providedfile2 = access.provideFile(file1, 2);

Definition at line 81 of file MediaSetAccess.h.

Member Typedef Documentation

◆ ProvideOperation

using zypp::MediaSetAccess::ProvideOperation = function<void (media::MediaAccessId, const OnMediaLocation &)>

protected

Definition at line 376 of file MediaSetAccess.h.

Member Enumeration Documentation

◆ ProvideFileOption

enum zypp::MediaSetAccess::ProvideFileOption

Enumerator
PROVIDE_DEFAULT	The user is not asked anything, and the error exception is just propagated.
PROVIDE_NON_INTERACTIVE

Definition at line 131 of file MediaSetAccess.h.

Constructor & Destructor Documentation

◆ MediaSetAccess() [1/6]

zypp::MediaSetAccess::MediaSetAccess	(	Url	url,
		Pathname	prefered_attach_point = "" )

Creates a callback enabled media access for specified url.

Parameters

url
prefered_attach_point	Prefered attach (mount) point. Use, if you want to mount the media to a specific directory.

Definition at line 73 of file MediaSetAccess.cc.

◆ MediaSetAccess() [2/6]

zypp::MediaSetAccess::MediaSetAccess	(	std::string	label_r,
		Url	url,
		Pathname	prefered_attach_point = "" )

Definition at line 77 of file MediaSetAccess.cc.

◆ MediaSetAccess() [3/6]

zypp::MediaSetAccess::MediaSetAccess	(	MirroredOrigin	origin,
		Pathname	prefered_attach_point = "" )

Creates a callback enabled media access for specified url.

Parameters

urls
prefered_attach_point	Prefered attach (mount) point. Use, if you want to mount the media to a specific directory.

Definition at line 81 of file MediaSetAccess.cc.

◆ MediaSetAccess() [4/6]

zypp::MediaSetAccess::MediaSetAccess	(	std::string	label_r,
		MirroredOrigin	origin,
		Pathname	prefered_attach_point = "" )

Definition at line 85 of file MediaSetAccess.cc.

◆ MediaSetAccess() [5/6]

zypp::MediaSetAccess::MediaSetAccess ( const MediaSetAccess & )

delete

◆ MediaSetAccess() [6/6]

zypp::MediaSetAccess::MediaSetAccess ( MediaSetAccess && )

delete

◆ ~MediaSetAccess()

zypp::MediaSetAccess::~MediaSetAccess ( )

override

Definition at line 89 of file MediaSetAccess.cc.

Member Function Documentation

◆ operator=() [1/2]

MediaSetAccess & zypp::MediaSetAccess::operator= ( const MediaSetAccess & )

delete

◆ operator=() [2/2]

MediaSetAccess & zypp::MediaSetAccess::operator= ( MediaSetAccess && )

delete

◆ setVerifier()

void zypp::MediaSetAccess::setVerifier	(	unsigned	media_nr,
		const media::MediaVerifierRef &	verifier )

Sets a MediaVerifier verifier for given media number.

Definition at line 101 of file MediaSetAccess.cc.

◆ label()

const std::string & zypp::MediaSetAccess::label ( ) const

The label identifing this media set and to be sent in a media change request.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 120 of file MediaSetAccess.cc.

◆ setLabel()

void zypp::MediaSetAccess::setLabel ( const std::string & label_r )

Set the label identifing this media set and to be sent in a media change request.

Definition at line 123 of file MediaSetAccess.cc.

◆ ZYPP_DECLARE_FLAGS()

zypp::MediaSetAccess::ZYPP_DECLARE_FLAGS	(	ProvideFileOptions	,
		ProvideFileOption	)

◆ precacheFiles()

void zypp::MediaSetAccess::precacheFiles ( const std::vector< OnMediaLocation > & files )

Tries to fetch the given files and precaches them.

Those files need to be queried using provideFile and can be read from the cache directly. The implementation is not allowed to block but needs to use seperate means to download the files concurrently. A backend can choose to completely ignore this functionaly, the default implementation does nothing.

Parameters

files List of files that should be precached

Definition at line 280 of file MediaSetAccess.cc.

◆ provideFile() [1/3]

Pathname zypp::MediaSetAccess::provideFile	(	const OnMediaLocation &	resource,
		ProvideFileOptions	options = PROVIDE_DEFAULT )

Provides a file from a media location.

Parameters

resource location of the file on media

Returns: local pathname of the requested file

Exceptions

MediaException	if a problem occured and user has chosen to abort the operation. The calling code should take care to quit the current operation.
SkipRequestException	if a problem occured and user has chosen to skip the current operation. The calling code should continue with the next one, if possible.

If the resource is marked as optional, no Exception is thrown and Pathname() is returned

the optional deltafile argument describes a file that can be used for delta download algorithms.

Note: interaction with the user does not ocurr if ProvideFileOptions::NON_INTERACTIVE is set.; OnMediaLocation::optional() hint has no effect on the transfer.

See also: zypp::media::MediaManager::provideFile()

Definition at line 207 of file MediaSetAccess.cc.

◆ provideFile() [2/3]

Pathname zypp::MediaSetAccess::provideFile	(	const OnMediaLocation &	resource,
		ProvideFileOptions	options,
		const Pathname &	deltafile )

Deprecated: The deltafile argument is part of the OnMediaLocation now, use the version of provideFile( const OnMediaLocation & resource, ProvideFileOptions options )

Definition at line 214 of file MediaSetAccess.cc.

◆ provideFile() [3/3]

Pathname zypp::MediaSetAccess::provideFile	(	const Pathname &	file,
		unsigned	media_nr = 1,
		ProvideFileOptions	options = PROVIDE_DEFAULT )

Provides file from media media_nr.

Parameters

file	path to the file relative to media URL
media_nr	the media number in the media set

Returns: local pathname of the requested file

Note: interaction with the user does not ocurr if ProvideFileOptions::NON_INTERACTIVE is set.; OnMediaLocation::optional() hint has no effect on the transfer.

Exceptions

MediaException	if a problem occured and user has chosen to abort the operation. The calling code should take care to quit the current operation.
SkipRequestException	if a problem occured and user has chosen to skip the current operation. The calling code should continue with the next one, if possible.

See also: zypp::media::MediaManager::provideFile()

Definition at line 219 of file MediaSetAccess.cc.

◆ provideOptionalFile()

Pathname zypp::MediaSetAccess::provideOptionalFile	(	const Pathname &	file,
		unsigned	media_nr = 1 )

Provides an optional file from media media_nr.

Like provideFile (NON_INTERACTIVE), but return an empty Pathname rather than throwing a MediaException if the file is not present on the media.

Definition at line 224 of file MediaSetAccess.cc.

◆ provideFileFromUrl()

ManagedFile zypp::MediaSetAccess::provideFileFromUrl	(	const Url &	file_url,
		ProvideFileOptions	options = PROVIDE_DEFAULT )

static

Provides file from url.

Parameters

absolute url to the file

Returns: local pathname of the requested file

Note: interaction with the user does not ocurr if ProvideFileOptions::NON_INTERACTIVE is set.

Exceptions

MediaException	if a problem occured and user has chosen to abort the operation. The calling code should take care to quit the current operation.
SkipRequestException	if a problem occured and user has chosen to skip the current operation. The calling code should continue with the next one, if possible.

See also: zypp::media::MediaManager::provideFile()

Definition at line 239 of file MediaSetAccess.cc.

◆ provideOptionalFileFromUrl()

ManagedFile zypp::MediaSetAccess::provideOptionalFileFromUrl ( const Url & file_url )

static

Provides an optional file from url.

Like provideFileFromUrl( NON_INTERACTIVE ), but return an empty Pathname rather than throwing a MediaException if the file is not present on the media.

Definition at line 259 of file MediaSetAccess.cc.

◆ releaseFile() [1/2]

void zypp::MediaSetAccess::releaseFile ( const OnMediaLocation & resource )

Release file from media.

This signal that file is not needed anymore.

Parameters

resource location of the file on media

Definition at line 126 of file MediaSetAccess.cc.

◆ releaseFile() [2/2]

void zypp::MediaSetAccess::releaseFile	(	const Pathname &	file,
		unsigned	media_nr = 1 )

Release file from media.

This signal that file is not needed anymore.

Parameters

file	path to the file relative to media URL
media_nr	the media number in the media set

Definition at line 131 of file MediaSetAccess.cc.

◆ provideDir()

Pathname zypp::MediaSetAccess::provideDir	(	const Pathname &	dir,
		bool	recursive,
		unsigned	media_nr = 1,
		ProvideFileOptions	options = PROVIDE_DEFAULT )

Provides direcotry dir from media number media_nr.

Parameters

dir	path to the directory relative to media URL
recursive	whether to provide the whole directory subtree
media_nr	the media number in the media set

Returns: local pathname of the requested directory

Exceptions

MediaException if a problem occured and user has chosen to abort the operation. The calling code should take care to quit the current operation.

Todo: throw SkipRequestException if a problem occured and user has chosen to skip the current operation. The calling code should continue with the next one, if possible.

See also: zypp::media::MediaManager::provideDir(); zypp::media::MediaManager::provideDirTree()

Definition at line 443 of file MediaSetAccess.cc.

◆ doesFileExist()

bool zypp::MediaSetAccess::doesFileExist	(	const Pathname &	file,
		unsigned	media_nr = 1 )

Checks if a file exists on the specified media, with user callbacks.

Parameters

file	file to check
media_nr	Media number

Exceptions

MediaException	if a problem occured and user has chosen to abort the operation. The calling code should take care to quit the current operation.
SkipRequestException	if a problem occured and user has chosen to skip the current operation. The calling code should continue with the next one, if possible.

See also: zypp::media::MediaManager::doesFileExist(MediaAccessId,const Pathname&)

Definition at line 272 of file MediaSetAccess.cc.

◆ dirInfo()

void zypp::MediaSetAccess::dirInfo	(	filesystem::DirContent &	retlist,
		const Pathname &	dirname,
		bool	dots = true,
		unsigned	media_nr = 1 )

Fills retlist with directory information.

Definition at line 144 of file MediaSetAccess.cc.

◆ release()

void zypp::MediaSetAccess::release ( )

Release all attached media of this set.

Exceptions

MediaNotOpenException for invalid access IDs.

Definition at line 543 of file MediaSetAccess.cc.

◆ rewriteUrl()

Url zypp::MediaSetAccess::rewriteUrl	(	const Url &	url_r,
		const media::MediaNr	medianr )

static

Replaces media number in specified url with given medianr.

Media number in the URL is searched for with regex "^(.*(cd|dvd|media))([0-9]+)(\\.iso)$" for iso scheme and with "^(.*(cd|dvd|media))([0-9]+)(/?)$" for other schemes.

For cd and dvd scheme it returns the original URL, as well as for URL which do not match the above regexes.

Parameters

url_r	original URL
medianr	requested media number

Returns: rewritten URL if applicable, the original URL otherwise

Definition at line 500 of file MediaSetAccess.cc.

◆ provideFileInternal()

Pathname zypp::MediaSetAccess::provideFileInternal	(	const OnMediaLocation &	resource,
		ProvideFileOptions	options )

protected

Provides the file from medium number media_nr and returns its local path.

Note: The method must not throw if checkonly is true.

Exceptions

MediaException	checkonly is false and a problem occured and user has chosen to abort the operation. The calling code should take care to quit the current operation.
SkipRequestException	checkonly is false and a problem occured and user has chosen to skip the current operation. The calling code should continue with the next one, if possible.

◆ provide()

void zypp::MediaSetAccess::provide	(	const ProvideOperation &	op,
		const OnMediaLocation &	resource,
		ProvideFileOptions	options )

protected

Definition at line 300 of file MediaSetAccess.cc.

◆ getMediaAccessId()

media::MediaAccessId zypp::MediaSetAccess::getMediaAccessId ( media::MediaNr medianr )

protected

Definition at line 460 of file MediaSetAccess.cc.

◆ dumpOn()

std::ostream & zypp::MediaSetAccess::dumpOn ( std::ostream & str ) const

overrideprotectedvirtual

Overload to realize std::ostream & operator<<.

Reimplemented from zypp::base::ReferenceCounted.

Definition at line 551 of file MediaSetAccess.cc.

◆ operator<< [1/2]

std::ostream & operator<<	(	std::ostream &	str,
		const MediaSetAccess &	obj )

friend

◆ operator<<() [2/2]

std::ostream & operator<<	(	std::ostream &	str,
		const MediaSetAccess &	obj )

Stream output.

Definition at line 392 of file MediaSetAccess.h.

Member Data Documentation

◆ _pimpl

std::unique_ptr<Impl> zypp::MediaSetAccess::_pimpl

private

Pointer to implementation.

Definition at line 386 of file MediaSetAccess.h.

The documentation for this class was generated from the following files:

zypp/MediaSetAccess.h
zypp/MediaSetAccess.cc

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Private Attributes

Friends

Related Symbols

Detailed Description

Member Typedef Documentation

◆ ProvideOperation

Member Enumeration Documentation

◆ ProvideFileOption

Constructor & Destructor Documentation

◆ MediaSetAccess() [1/6]

◆ MediaSetAccess() [2/6]

◆ MediaSetAccess() [3/6]

◆ MediaSetAccess() [4/6]

◆ MediaSetAccess() [5/6]

◆ MediaSetAccess() [6/6]

◆ ~MediaSetAccess()

Member Function Documentation

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ setVerifier()

◆ label()

◆ setLabel()

◆ ZYPP_DECLARE_FLAGS()

◆ precacheFiles()

◆ provideFile() [1/3]

◆ provideFile() [2/3]

◆ provideFile() [3/3]

◆ provideOptionalFile()

◆ provideFileFromUrl()

◆ provideOptionalFileFromUrl()

◆ releaseFile() [1/2]

◆ releaseFile() [2/2]

◆ provideDir()

◆ doesFileExist()

◆ dirInfo()

◆ release()

◆ rewriteUrl()

◆ provideFileInternal()

◆ provide()

◆ getMediaAccessId()

◆ dumpOn()

Friends And Related Symbol Documentation

◆ operator<< [1/2]

◆ operator<<() [2/2]

Member Data Documentation

◆ _pimpl