zypp::Fetcher Class Reference

This class allows to retrieve a group of files in a confortable way, providing some smartness that does not belong to the media layer like:. More...

#include <Fetcher.h>

Inheritance diagram for zypp::Fetcher:

[legend]

List of all members.

Classes

class Impl

Fetcher implementation. More...

Public Types

enum Option { AutoAddContentFileIndexes = 0x0001, AutoAddSha1sumsIndexes = 0x0002, AutoAddIndexes = 0x0001 | 0x0002 }

Various option flags to change behavior. More...

Public Member Functions

ZYPP_DECLARE_FLAGS (Options, Option)

Fetcher ()

Default ctor.

virtual ~Fetcher ()

Dtor.

void setOptions (Options options)

Set the Fetcher options.

Options options () const

Get current options.

void addIndex (const OnMediaLocation &resource)

Adds an index containing metadata (for example checksums ) that will be retrieved and read before the job processing starts.

void enqueue (const OnMediaLocation &resource, const FileChecker &checker=FileChecker())

Enqueue a object for transferal, they will not be transfered until start() is called.

void enqueueDigested (const OnMediaLocation &resource, const FileChecker &checker=FileChecker())

Enqueue a object for transferal, they will not be transfered until start() is called.

void enqueueDir (const OnMediaLocation &resource, bool recursive=false, const FileChecker &checker=FileChecker())

Enqueue a directory.

void enqueueDigestedDir (const OnMediaLocation &resource, bool recursive=false, const FileChecker &checker=FileChecker())

Enqueue a directory and always check for checksums.

void addCachePath (const Pathname &cache_dir)

adds a directory to the list of directories where to look for cached files

void reset ()

Reset the transfer (jobs) list.

void start (const Pathname &dest_dir, MediaSetAccess &media, const ProgressData::ReceiverFnc &progress=ProgressData::ReceiverFnc())

start the transfer to a destination directory dest_dir You have to provde a media set access media to get the files from The file tree will be replicated inside this directory

Private Attributes

RWCOW_pointer< Impl > _pimpl

Pointer to implementation.

Friends

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

Detailed Description

This class allows to retrieve a group of files in a confortable way, providing some smartness that does not belong to the media layer like:.

Configurable local caches to retrieve already donwloaded files.
File checkers that can check for right checksums digital signatures, etc.

 MediaSetAccess access(url, path);
 Fetcher fetcher;
 fetcher.enqueue( OnMediaLocation().setLocation("/somefile") );
 fetcher.addCachePath("/tmp/cache")
 fetcher.start( "/download-dir, access );
 fetcher.reset();

To use the checkers. just create a functor implementing bool operator()(const Pathname &file)

See also:: FileChecker. Pass the necessary validation data in the constructor of the functor, and pass the object to the enqueue method.

 ChecksumFileChecker checker(CheckSum("sha1", "....");
 fetcher.enqueue( location, checker);

If you need to use more than one checker

See also:: CompositeFileChecker

Additionally, you can automatically enqueue a job with a checksum checker by using enqueueDigested which will use the OnMediaLocation checksum automatically.

 location.setChecksum(CheckSum("sha1", "...."));
 fetcher.enqueueDigested(location);

Note:: If the checksum of the location is empty, but enqueueDigested is used, then the user will get a warning that the file has no checksum.

Additionally, Fetcher supports checking the downloaded content by using signed indexes on the remote side.

 MediaSetAccess access(url, path);
 Fetcher fetcher;
 fetcher.addIndex(OnMediaLocation("/content"));
 fetcher.enqueue( OnMediaLocation().setLocation("/somefile") );
 fetcher.start( "/download-dir, access );
 fetcher.reset();

Indexes are supported in SHA1SUMS format (simple text file) with sha1sums and file name, or content file, whith HASH SHA1 line entries.

Note:: The indexes file names are relative to the directory where the index is.

Definition at line 98 of file Fetcher.h.

Member Enumeration Documentation

enum zypp::Fetcher::Option

Various option flags to change behavior.

Enumerator:

AutoAddContentFileIndexes	If a content file is found, it is downloaded and read.
AutoAddSha1sumsIndexes	If a SHA1SUMS file is found, it is downloaded and read.
AutoAddIndexes	If a content or SHA1SUMS file is found, it is downloaded and read.

Definition at line 110 of file Fetcher.h.

Constructor & Destructor Documentation

zypp::Fetcher::Fetcher ( )

Default ctor.

Definition at line 846 of file Fetcher.cc.

zypp::Fetcher::~Fetcher ( ) [virtual]

Dtor.

Definition at line 850 of file Fetcher.cc.

Member Function Documentation

zypp::Fetcher::ZYPP_DECLARE_FLAGS	(	Options	,
		Option
	)

void zypp::Fetcher::setOptions ( Options options )

Set the Fetcher options.

See also:: Fetcher::Options

Fetcher::Options zypp::Fetcher::options ( ) const

Get current options.

See also:: Fetcher::Options

Definition at line 858 of file Fetcher.cc.

References _pimpl.

void zypp::Fetcher::addIndex ( const OnMediaLocation & resource )

Adds an index containing metadata (for example checksums ) that will be retrieved and read before the job processing starts.

Nothing will be transfered or checked until start() is called.

The index is relative to the media path, and the listed files too.

Indexes in the SHA1SUM format, and YaST content file

The file has to be signed or the user will be warned that the file is unsigned. You can place the signature next to the file adding the .asc extension.

If you expect the key to not to be in the target system, then you can place it next to the index using adding the .key extension.

Definition at line 883 of file Fetcher.cc.

References _pimpl.

void zypp::Fetcher::enqueue	(	const OnMediaLocation &	resource,
		const FileChecker &	checker = `FileChecker()`
	)

Enqueue a object for transferal, they will not be transfered until start() is called.

Definition at line 889 of file Fetcher.cc.

References _pimpl.

Referenced by zypp::repo::yum::Downloader::download(), zypp::repo::susetags::Downloader::download(), zypp::Fetcher::Impl::downloadIndex(), zypp::repo::downloadMediaInfo(), and zypp::repo::RepoMediaAccess::provideFile().

void zypp::Fetcher::enqueueDigested	(	const OnMediaLocation &	resource,
		const FileChecker &	checker = `FileChecker()`
	)

Enqueue a object for transferal, they will not be transfered until start() is called.

Note:: As OnMediaLocation contains the digest information, a ChecksumFileChecker is automatically added to the transfer job, so make sure you don't add another one or the user could be asked twice.

Todo:: FIXME implement checker == operator to avoid this.

Definition at line 863 of file Fetcher.cc.

References _pimpl.

Referenced by zypp::repo::susetags::Downloader::download(), and zypp::repo::yum::Downloader::repomd_Callback().

void zypp::Fetcher::enqueueDir	(	const OnMediaLocation &	resource,
		bool	recursive = `false`,
		const FileChecker &	checker = `FileChecker()`
	)

Enqueue a directory.

As the files to be enqueued are not known in advance, all files whose checksum can be found in some index are enqueued with checksum checking. Otherwise they are not.

Some index may provide the checksums, either by addIndex or using AutoAddIndexes flag.

Files are checked by providing a SHA1SUMS or content file listing <checksum> filename and a respective SHA1SUMS.asc/content.asc which has the signature for the checksums.

If you expect the user to not have the key of the signature either in the trusted or untrusted keyring, you can offer it as SHA1SUMS.key (or content.key)

Parameters:

recursive

True if the complete tree should be enqueued.

Note:

As checksums are read from the index, a ChecksumFileChecker is automatically added to transfer jobs having a checksum available, so make sure you don't add another one or the user could be asked twice.

The format of the file SHA1SUMS is the output of: ls | grep -v SHA1SUMS | xargs sha1sum > SHA1SUMS in each subdirectory.

Every file SHA1SUMS.* except of SHA1SUMS.(asc|key|(void)) will not be transfered and will be ignored.

Definition at line 868 of file Fetcher.cc.

References _pimpl.

void zypp::Fetcher::enqueueDigestedDir	(	const OnMediaLocation &	resource,
		bool	recursive = `false`,
		const FileChecker &	checker = `FileChecker()`
	)

Enqueue a directory and always check for checksums.

As the files to be enqueued are not known in advance, all files are enqueued with checksum checking. If the checksum of some file is not in some index, then there will be a verification warning ( DigestReport ).

Therefore some index will need to provide the checksums, either by addIndex or using AutoAddIndexes flag.

Files are checked by providing a SHA1SUMS or content file listing <checksum> filename and a respective SHA1SUMS.asc/content.asc which has the signature for the checksums.

If you expect the user to not have the key of the signature either in the trusted or untrusted keyring, you can offer it as SHA1SUMS.key (or content.key)

Parameters:

recursive

True if the complete tree should be enqueued.

Note:

As checksums are read from the index, a ChecksumFileChecker is automatically added to every transfer job, so make sure you don't add another one or the user could be asked twice.

The format of the file SHA1SUMS is the output of: ls | grep -v SHA1SUMS | xargs sha1sum > SHA1SUMS in each subdirectory.

Every file SHA1SUMS.* except of SHA1SUMS.(asc|key|(void)) will not be transfered and will be ignored.

Definition at line 875 of file Fetcher.cc.

References _pimpl.

void zypp::Fetcher::addCachePath ( const Pathname & cache_dir )

adds a directory to the list of directories where to look for cached files

Definition at line 894 of file Fetcher.cc.

References _pimpl.

Referenced by zypp::repo::RepoMediaAccess::provideFile().

void zypp::Fetcher::reset ( )

Reset the transfer (jobs) list.

Note:: It does not reset the cache directory list

Definition at line 899 of file Fetcher.cc.

References _pimpl, and zypp::RWCOW_pointer< _D, _Traits >::reset().

Referenced by zypp::repo::yum::Downloader::download(), zypp::repo::susetags::Downloader::download(), zypp::Fetcher::Impl::downloadIndex(), and zypp::repo::downloadMediaInfo().

void zypp::Fetcher::start	(	const Pathname &	dest_dir,
		MediaSetAccess &	media,
		const ProgressData::ReceiverFnc &	progress = `ProgressData::ReceiverFnc()`
	)

start the transfer to a destination directory dest_dir You have to provde a media set access media to get the files from The file tree will be replicated inside this directory

Definition at line 904 of file Fetcher.cc.

References _pimpl.

Referenced by zypp::repo::yum::Downloader::download(), zypp::repo::susetags::Downloader::download(), zypp::Fetcher::Impl::downloadIndex(), zypp::repo::downloadMediaInfo(), zypp::repo::RepoMediaAccess::provideFile(), and zypp::repo::yum::Downloader::repomd_Callback().

Friends And Related Function Documentation

std::ostream & operator<<	(	std::ostream &	str,
		const Fetcher &	obj
	)			`[friend]`

Stream output

Definition at line 911 of file Fetcher.cc.

Member Data Documentation

RWCOW_pointer<Impl> zypp::Fetcher::_pimpl [private]

Pointer to implementation.

Definition at line 312 of file Fetcher.h.

Referenced by addCachePath(), addIndex(), enqueue(), enqueueDigested(), enqueueDigestedDir(), enqueueDir(), zypp::operator<<(), options(), reset(), and start().

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

zypp/Fetcher.h
zypp/Fetcher.cc


Classes
class	Impl
	Fetcher implementation. More...
Public Types
enum	Option { AutoAddContentFileIndexes = 0x0001, AutoAddSha1sumsIndexes = 0x0002, AutoAddIndexes = 0x0001 \| 0x0002 }
	Various option flags to change behavior. More...
Public Member Functions
	ZYPP_DECLARE_FLAGS (Options, Option)
	Fetcher ()
	Default ctor.
virtual	~Fetcher ()
	Dtor.
void	setOptions (Options options)
	Set the Fetcher options.
Options	options () const
	Get current options.
void	addIndex (const OnMediaLocation &resource)
	Adds an index containing metadata (for example checksums ) that will be retrieved and read before the job processing starts.
void	enqueue (const OnMediaLocation &resource, const FileChecker &checker=FileChecker())
	Enqueue a object for transferal, they will not be transfered until start() is called.
void	enqueueDigested (const OnMediaLocation &resource, const FileChecker &checker=FileChecker())
	Enqueue a object for transferal, they will not be transfered until start() is called.
void	enqueueDir (const OnMediaLocation &resource, bool recursive=false, const FileChecker &checker=FileChecker())
	Enqueue a directory.
void	enqueueDigestedDir (const OnMediaLocation &resource, bool recursive=false, const FileChecker &checker=FileChecker())
	Enqueue a directory and always check for checksums.
void	addCachePath (const Pathname &cache_dir)
	adds a directory to the list of directories where to look for cached files
void	reset ()
	Reset the transfer (jobs) list.
void	start (const Pathname &dest_dir, MediaSetAccess &media, const ProgressData::ReceiverFnc &progress=ProgressData::ReceiverFnc())
	start the transfer to a destination directory dest_dir You have to provde a media set access media to get the files from The file tree will be replicated inside this directory
Private Attributes
RWCOW_pointer< Impl >	_pimpl
	Pointer to implementation.
Friends
std::ostream &	operator<< (std::ostream &str, const Fetcher &obj)