Job::MakeImageDl Class Reference

MakeImageDl: Everything related to downloads. More...

#include <makeimagedl.hh>

Inheritance diagram for Job::MakeImageDl:


Public Types
enum	State { DOWNLOADING_JIGDO, DOWNLOADING_TEMPLATE, FINAL_STATE, ERROR }
enum	{ B, B_, I, I_, TT, TT_, U, U_, BIG, BIG_, SMALL, SMALL_, BR }
	Helper enum for the offsets above. More...
typedef IList< ChildListBase >	ChildList
Public Member Functions
	MakeImageDl (const string &jigdoUri, const string &destination)
	Return the string "Cache entry %1 -- %2" or an equivalent localized string.
	~MakeImageDl ()
	Destroy this MakeImageDl and all its children.
void	killAllChildren ()
	Destroy all children.
void	run ()
	Start downloading.
const string &	jigdoUri () const
State	state () const
	Return current state of object.
const string &	tmpDir () const
	Return name of temporary directory.
void	generateError (const string &message, State newState=ERROR)
	Set state to ERROR and call io->job_failed.
bool	finalState () const
	Return true if current state is final.
void	childFailed (Child *childDl)
	As above, but notify this object that the download has failed: Not all bytes have been received, or another error (e.g.
void	setImageSection (string imageName, string imageInfo, string imageShortInfo, PartUrlMapping templateUrls, MD5 **templateMd5)
	Is called by a child JigdoIO once the [Image] section has been seen.
bool	haveImageSection () const
	Has setImageSection() already been called? (=>is imageName non-empty?).
Child *	childFor (const string &url, const MD5 md=0, string leafnameOut=0, Child *reuseChild=0)
	Return child download object which contains a DataSource which produces the data of the requested URL.
Child *	childFor (PartUrlMapping urls, const MD5 md=0)
	As above, but instead of providing a single URL, a number of alternative URLs is given.
const ChildList &	children () const
	Return the list of Child objects owned by this MakeImageDl.
const string &	imageName () const
	Return info about the first image section, or empty strings if none encountered so far.
const string &	imageShortInfo () const
const MD5 *	templateMd5 () const
void	imageInfo (string output, bool escapedText, const char subst[13]) const
	This one is special: The contents of ImageInfo are an XML-style string, with markup containing tags named: b i tt u big small br p.
const string &	imageInfoOrig () const
	Return ImageInfo as it appears in the .jigdo file.
void	jigdoFinished ()
	To be called by JigdoIO only.
Public Attributes
IOSource< IO >	io
UrlMap	urlMap
	Graph structure describing the contents of the .jigdo file.
Static Public Attributes
static const int	MAX_INCLUDES = 100
	Maximum allowed [Include] directives in a .jigdo file and the files it includes.
Friends
class	Child
Classes
class	Child
	Each Child object stands for one DataSource (i.e. SingleUrl/CachedUrl) which the MakeImageDl starts as a "child download" of itself. More...
class	ChildListBase
	Child objects are in two lists, need this to disambiguate them. More...
class	IO
	User interaction for MakeImageDl. More...
class	JigdoDownload
	Private class of MakeImageDl: Object extending a SingleUrl and used to retrieve the data of the .jigdo file. More...

Detailed Description

MakeImageDl: Everything related to downloads.

Downloads and interprets .jigdo file contents
Downloads .template via SingleURL, notifies MakeImage once done
"Owner" of the layout of the temporary directory, only component that directly makes modifications to this dir. (MakeImage only writes to the image file.)
Does simple cache management; if requested file already downloaded, immediately returns its data, or does an If-Modified-Since request; if partially downloaded, resumes.
Starts further SingleURLs for download of individual parts.
Automatic server selection: For servers which were rated equally acceptable by the user, measures their speed, then prefers the faster ones (but does not completely stop using the slower ones).

See comments in makeimage.hh for the big picture.

Member Typedef Documentation

typedef IList<ChildListBase> Job::MakeImageDl::ChildList

Member Enumeration Documentation

enum Job::MakeImageDl::State

Enumerator:

DOWNLOADING_JIGDO
DOWNLOADING_TEMPLATE
FINAL_STATE
ERROR

anonymous enum

Helper enum for the offsets above.

E.g. TT is <tt>, TT_ is </tt>

Enumerator:

B
B_
I
I_
TT
TT_
U
U_
BIG
BIG_
SMALL
SMALL_
BR

Constructor & Destructor Documentation

MakeImageDl::MakeImageDl	(	const string &	jigdoUri,
		const string &	destination
	)

Return the string "Cache entry %1 -- %2" or an equivalent localized string.

This is used for the destination description of children. Prepare object. No download is started yet.

Parameters:

	jigdoUri	URL of top-level .jigdo
	destination	Name of directory to create tmp directory in, for storing data during the download.

References childFor(), Job::DataSource::io, Job::DataSource::run(), and Job::MakeImageDl::Child::source().

Job::MakeImageDl::~MakeImageDl ( )

Destroy this MakeImageDl and all its children.

Member Function Documentation

void Job::MakeImageDl::killAllChildren ( )

Destroy all children.

References debug.

Referenced by GtkMakeImage::~GtkMakeImage().

void MakeImageDl::run ( )

Start downloading.

First creates a new download for the .jigdo data, then the .template data, etc.

References _, Assert, compat_mkdir(), error(), finalState(), generateError(), msg, subst, and tmpDir().

Referenced by GtkMakeImage::run().

const string & Job::MakeImageDl::jigdoUri ( ) const [inline]

Referenced by GtkMakeImage::run().

Job::MakeImageDl::State Job::MakeImageDl::state ( ) const [inline]

Return current state of object.

Referenced by finalState().

const string & Job::MakeImageDl::tmpDir ( ) const [inline]

Return name of temporary directory.

This is a subdir of "destination" (ctor arg), contains a hash of the jigdoUri. Never ends in '/'.

Referenced by run().

void Job::MakeImageDl::generateError	(	const string &	message,
		State	newState = `ERROR`
	)			`[inline]`

Set state to ERROR and call io->job_failed.

References finalState(), io, and IOSOURCE_SEND.

Referenced by run().

bool Job::MakeImageDl::finalState ( ) const [inline]

Return true if current state is final.

References FINAL_STATE, and state().

Referenced by generateError(), and run().

void MakeImageDl::childFailed ( Child * childDl )

As above, but notify this object that the download has failed: Not all bytes have been received, or another error (e.g.

while gunzipping the .jigdo file) occurred. If there are several alternative download URLs for this child, the next one will be tried, otherwise the entire MakeImageDl fails.

References Job::DataSource::location(), msg, and Job::MakeImageDl::Child::source().

void MakeImageDl::setImageSection	(	string *	imageName,
		string *	imageInfo,
		string *	imageShortInfo,
		PartUrlMapping *	templateUrls,
		MD5 **	templateMd5
	)

Is called by a child JigdoIO once the [Image] section has been seen.

The arguments are modified!

References haveImageSection(), and Paranoid.

Referenced by testImageInfo().

bool Job::MakeImageDl::haveImageSection ( ) const [inline]

Has setImageSection() already been called? (=>is imageName non-empty?).

Referenced by setImageSection().

MakeImageDl::Child * MakeImageDl::childFor	(	const string &	url,
		const MD5 *	md = `0`,
		string *	leafnameOut = `0`,
		Child *	reuseChild = `0`
	)

Return child download object which contains a DataSource which produces the data of the requested URL.

That returned object is usually a newly started download, except if the file (or its beginning) was already downloaded. The filename is based on either the base64ified md checksum, or (if that is 0), the b64ied md5 checksum of the url.

This method will call makeImageDl_new() for all listeners to the io object, to make them register their own child listeners with the new Child object.

Parameters:

	url	URL to download
	md	Expected checksum of downloaded data, null if unknown
	leafnameOut	If non-null, string is overwritten with file's leafname in cache on exit.
	reuseChild	For internal use only, should usually be set to null. If non-null, no new Child is allocated, instead the passed object is reused. However, some data members are not reset - this is used by the second childFor() below to try out all alternatives.

Returns:: New object, or null if error (and io->job_failed was called). If non-null, returned object will be deleted from this MakeImageDl's dtor (unless it is deleted earlier).

References Assert, c, Child, and www.

Referenced by childFor(), MakeImageDl(), testLoop(), testMinimal(), testNoMD5(), and testSimple().

Job::MakeImageDl::Child * Job::MakeImageDl::childFor	(	PartUrlMapping *	urls,
		const MD5 *	md = `0`
	)			`[inline]`

As above, but instead of providing a single URL, a number of alternative URLs is given.

The Child will only fail after all of them have been tried unsuccessfully.

References c, childFor(), PartUrlMapping::enumerate(), Job::MakeImageDl::Child::lastUrl, and Job::MakeImageDl::Child::urls.

const Job::MakeImageDl::ChildList & Job::MakeImageDl::children ( ) const [inline]

Return the list of Child objects owned by this MakeImageDl.

Referenced by memData().

const string& Job::MakeImageDl::imageName ( ) const [inline]

Return info about the first image section, or empty strings if none encountered so far.

const string& Job::MakeImageDl::imageShortInfo ( ) const [inline]

const MD5* Job::MakeImageDl::templateMd5 ( ) const [inline]

void MakeImageDl::imageInfo	(	string *	output,
		bool	escapedText,
		const char *	subst[13]
	)			const

This one is special: The contents of ImageInfo are an XML-style string, with markup containing tags named: b i tt u big small br p.

When getting the string, the frontend must specify what strings the respective begin and end tags should be replaced with. The default args turn the string into plain UTF-8 without markup. This call is fairly expensive, you may want to cache the returned string.

If there in an error parsing the XML, the string from the ImageInfo entry is either returned unchanged (if !escapedText), or all "dangerous" characters are escaped (if escapedText == true);

If there is no error, escapedText==true means that any "<" in the normal text should be kept escaped as "<". escapedText=false will unescape the "<" to "<".

Parameters:

	subst	The subst argument is of the form: `{ "", "", // <b>, </b> "", "", // <i>, </i> "", "", // <tt>, </tt> "", "", // <u>, </u> "", "", // <big>, </big> "", "", // <small>, </small> "", "", // <br/> };`
	output	String to append image info to
	escapedText	true if the characters <>& should be escaped as <, > &

References debug, Paranoid, parseComment(), parseEndElem(), parseStartElem(), and parseText().

Referenced by testImageInfo().

const string& Job::MakeImageDl::imageInfoOrig ( ) const [inline]

Return ImageInfo as it appears in the .jigdo file.

The value has *not* been checked for validity (correct tag nesting etc).

void MakeImageDl::jigdoFinished ( )

To be called by JigdoIO only.

Called to notify the MakeImageDl that the last JigdoIO has successfully finished. Called just after childSucceeded() for that JigdoIO.

References debug.