libzypp: zypp::MediaSetAccess Class Reference

libzypp 17.25.10

Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Types | Protected Member Functions | Private Types | Private Attributes | Friends | Related Functions | List of all members
zypp::MediaSetAccess Class Reference

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 <MediaSetAccess.h>`

Inheritance diagram for zypp::MediaSetAccess:
[legend]

## Classes
struct | ReleaseFileGuard

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

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

## Static Public Member Functions
static ManagedFile | provideFileFromUrl (const Url &file_url, ProvideFileOptions options=PROVIDE_DEFAULT)
| Provides file from url. More...
static ManagedFile | provideOptionalFileFromUrl (const Url &file_url)
| Provides an optional file from url. More...
static Url | rewriteUrl (const Url &url_r, const media::MediaNr medianr)
| Replaces media number in specified url with given medianr. More...
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. More...
static void | release (const ReferenceCounted *ptr_r)
| Called by zypp::intrusive_ptr to add a reference. More...

## Protected Types
typedef function< void(media::MediaAccessId, const Pathname &)> | ProvideOperation

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

## Private Types
typedef std::map< media::MediaNr, media::MediaAccessId > | MediaMap
typedef std::map< media::MediaNr, media::MediaVerifierRef > | VerifierMap

## Private Attributes
Url | _url
| Media or media set URL. More...
Pathname | _prefAttachPoint
| Prefered mount point. More...
std::string | _label
MediaMap | _medias
| Mapping between media number and Media Access ID. More...
VerifierMap | _verifiers
| Mapping between media number and corespondent verifier. More...

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

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

## 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);
url
Url url
Definition: MediaCurl.cc:66
zypp::MediaSetAccess::MediaSetAccess
MediaSetAccess(const Url &url, const Pathname &prefered_attach_point="")
Creates a callback enabled media access for specified url.
Definition: MediaSetAccess.cc:32
zypp::misc::testcase::TestcaseRepoType::Url
@ Url

Definition at line 80 of file MediaSetAccess.h.

## Member Typedef Documentation

## ◆ ProvideOperation

typedef function<void( media::MediaAccessId, const Pathname & )> zypp::MediaSetAccess::ProvideOperation
| protected

Definition at line 342 of file MediaSetAccess.h.

## ◆ MediaMap

typedef std::map<media::MediaNr, media::MediaAccessId> zypp::MediaSetAccess::MediaMap
| private

Definition at line 363 of file MediaSetAccess.h.

## ◆ VerifierMap

typedef std::map<media::MediaNr, media::MediaVerifierRef > zypp::MediaSetAccess::VerifierMap
| private

Definition at line 364 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 114 of file MediaSetAccess.h.

## Constructor & Destructor Documentation

## ◆ MediaSetAccess() [1/2]

zypp::MediaSetAccess::MediaSetAccess | ( | const Url & | url,
|  | const 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 32 of file MediaSetAccess.cc.

## ◆ MediaSetAccess() [2/2]

zypp::MediaSetAccess::MediaSetAccess | ( | const std::string & | label_r,
|  | const Url & | url,
|  | const Pathname & | prefered_attach_point = `""`
| ) |  |

Definition at line 38 of file MediaSetAccess.cc.

## ◆ ~MediaSetAccess()

zypp::MediaSetAccess::~MediaSetAccess | ( |  | ) |

Definition at line 46 of file MediaSetAccess.cc.

## Member Function Documentation

## ◆ setVerifier()

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

Sets a MediaVerifier verifier for given media number.

Definition at line 58 of file MediaSetAccess.cc.

## ◆ label()

Also taking a ref zypp::MediaSetAccess::label | ( |  | ) | const
| inline

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 105 of file MediaSetAccess.h.

## ◆ setLabel()

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

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

Definition at line 111 of file MediaSetAccess.h.

## ◆ ZYPP_DECLARE_FLAGS()

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

## ◆ provideFile() [1/2]

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

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 161 of file MediaSetAccess.cc.

## ◆ provideFile() [2/2]

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 169 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 178 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 194 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 212 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 77 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 82 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 389 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 225 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 97 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 485 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 442 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 | ( | ProvideOperation | op,
|  | const OnMediaLocation & | resource,
|  | ProvideFileOptions | options,
|  | const Pathname & | deltafile
| ) |  |
| protected

Definition at line 234 of file MediaSetAccess.cc.

## ◆ getMediaAccessId()

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

Definition at line 407 of file MediaSetAccess.cc.

## ◆ dumpOn()

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

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

Reimplemented from zypp::base::ReferenceCounted.

Definition at line 493 of file MediaSetAccess.cc.

## Friends And Related Function Documentation

## ◆ 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
| ) |  |
| related

Stream output.

Definition at line 375 of file MediaSetAccess.h.

## Member Data Documentation

## ◆ _url

Url zypp::MediaSetAccess::_url
| private

Media or media set URL.

Definition at line 351 of file MediaSetAccess.h.

## ◆ _prefAttachPoint

Pathname zypp::MediaSetAccess::_prefAttachPoint
| private

Prefered mount point.

See also
  MediaManager::open(Url,Pathname)
  MediaHandler::_attachPoint

Definition at line 359 of file MediaSetAccess.h.

## ◆ _label

std::string zypp::MediaSetAccess::_label
| private

Definition at line 361 of file MediaSetAccess.h.

## ◆ _medias

MediaMap zypp::MediaSetAccess::_medias
| private

Mapping between media number and Media Access ID.

Definition at line 367 of file MediaSetAccess.h.

## ◆ _verifiers

VerifierMap zypp::MediaSetAccess::_verifiers
| private

Mapping between media number and corespondent verifier.

Definition at line 369 of file MediaSetAccess.h.

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

- zypp/MediaSetAccess.h
- zypp/MediaSetAccess.cc