The SyncDownloadManager class is used to queue and process one or more downloads in a synchronous manner. More...

#include <qx/network/qx-downloadmanager.h>

Collaboration diagram for Qx::SyncDownloadManager:

Public Slots
void	abort ()

Signals
void	authenticationRequired (QString prompt, QAuthenticator *authenticator)

void	downloadFinished (Qx::DownloadOpReport downloadReport)

void	downloadProgress (qint64 bytesCurrent)

void	downloadTotalChanged (quint64 bytesTotal)

void	preSharedKeyAuthenticationRequired (QString prompt, QSslPreSharedKeyAuthenticator *authenticator)

void	proxyAuthenticationRequired (QString prompt, QAuthenticator *authenticator)

void	sslErrors (Qx::Error errorMsg, bool *ignore)

Public Member Functions
	SyncDownloadManager (QObject *parent=nullptr)

void	appendTask (const DownloadTask &task)

void	clearTasks ()

int	enumerationTimeout () const

bool	hasTasks () const

bool	isDeletePartialDownloads () const

bool	isOverwrite () const

bool	isProcessing () const

bool	isSkipEnumeration () const

bool	isStopOnError () const

int	maxSimultaneous () const

DownloadManagerReport	processQueue ()

QNetworkRequest::RedirectPolicy	redirectPolicy () const

void	setDeletePartialDownloads (bool deletePartialDownloads)

void	setEnumerationTimeout (int timeout=500)

void	setMaxSimultaneous (int maxSimultaneous)

void	setOverwrite (bool overwrite)

void	setRedirectPolicy (QNetworkRequest::RedirectPolicy redirectPolicy)

void	setSkipEnumeration (bool skipEnumeration)

void	setStopOnError (bool stopOnError)

void	setTransferTimeout (int timeout=QNetworkRequest::DefaultTransferTimeoutConstant)

void	setVerificationMethod (QCryptographicHash::Algorithm method)

int	taskCount () const

int	transferTimeout () const

QCryptographicHash::Algorithm	verificationMethod () const

Public Member Functions inherited from QObject
	QObject (QObject *parent)

QBindable< QString >	bindableObjectName ()

bool	blockSignals (bool block)

const QObjectList &	children () const const

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const const

void	deleteLater ()

void	destroyed (QObject *obj)

bool	disconnect (const char signal, const QObject receiver, const char *method) const const

bool	disconnect (const QObject receiver, const char method) const const

void	dumpObjectInfo () const const

void	dumpObjectTree () const const

QList< QByteArray >	dynamicPropertyNames () const const

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

T	findChild (QAnyStringView name, Qt::FindChildOptions options) const const

T	findChild (Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const

QList< T >	findChildren (QAnyStringView name, Qt::FindChildOptions options) const const

QList< T >	findChildren (Qt::FindChildOptions options) const const

bool	inherits (const char *className) const const

void	installEventFilter (QObject *filterObj)

bool	isQuickItemType () const const

bool	isWidgetType () const const

bool	isWindowType () const const

void	killTimer (int id)

virtual const QMetaObject *	metaObject () const const

bool	moveToThread (QThread *targetThread)

QString	objectName () const const

void	objectNameChanged (const QString &objectName)

QObject *	parent () const const

QVariant	property (const char *name) const const

	Q_CLASSINFO (Name, Value)

	Q_EMIT Q_EMIT

	Q_ENUM (...)

	Q_ENUM_NS (...)

	Q_ENUMS (...)

	Q_FLAG (...)

	Q_FLAG_NS (...)

	Q_FLAGS (...)

	Q_GADGET Q_GADGET

	Q_GADGET_EXPORT (EXPORT_MACRO)

	Q_INTERFACES (...)

	Q_INVOKABLE Q_INVOKABLE

	Q_MOC_INCLUDE Q_MOC_INCLUDE

	Q_NAMESPACE Q_NAMESPACE

	Q_NAMESPACE_EXPORT (EXPORT_MACRO)

	Q_OBJECT Q_OBJECT

	Q_PROPERTY (...)

	Q_REVISION Q_REVISION

	Q_SET_OBJECT_NAME (Object)

	Q_SIGNAL Q_SIGNAL

	Q_SIGNALS Q_SIGNALS

	Q_SLOT Q_SLOT

	Q_SLOTS Q_SLOTS

T	qobject_cast (const QObject *object)

T	qobject_cast (QObject *object)

	QT_NO_CONTEXTLESS_CONNECT QT_NO_CONTEXTLESS_CONNECT

	QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT

void	removeEventFilter (QObject *obj)

void	setObjectName (const QString &name)

void	setObjectName (QAnyStringView name)

void	setParent (QObject *parent)

bool	setProperty (const char *name, const QVariant &value)

bool	setProperty (const char *name, QVariant &&value)

bool	signalsBlocked () const const

int	startTimer (int interval, Qt::TimerType timerType)

int	startTimer (std::chrono::milliseconds interval, Qt::TimerType timerType)

QThread *	thread () const const

Additional Inherited Members
Static Public Member Functions inherited from QObject
QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject context, Functor functor, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)

bool	disconnect (const QMetaObject::Connection &connection)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

bool	disconnect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method)

QString	tr (const char sourceText, const char disambiguation, int n)

Public Attributes inherited from QObject
typedef	QObjectList

Protected Member Functions inherited from QObject
virtual void	childEvent (QChildEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	customEvent (QEvent *event)

virtual void	disconnectNotify (const QMetaMethod &signal)

bool	isSignalConnected (const QMetaMethod &signal) const const

int	receivers (const char *signal) const const

QObject *	sender () const const

int	senderSignalIndex () const const

virtual void	timerEvent (QTimerEvent *event)

Properties inherited from QObject
	objectName

Detailed Description

A synchronous download manager can process an arbitrary number of download tasks while tracking overall progress, forwarding events that require user interaction, and and mediating connections.

Optional file content verification is available for tasks provided with non-empty checksums, which are compared using the algorithm set via setVerificationMethod().

Note: This class internally spins its own event loop in order to keep signals & slots processing while still blocking execution in the thread that contains the manager.

See also: DownloadTask, AsyncDownloadManager

Constructor & Destructor Documentation

◆ SyncDownloadManager()

Qx::SyncDownloadManager::SyncDownloadManager ( QObject * parent = nullptr )

Constructs an empty synchronous download manager with parent parent.

Member Function Documentation

◆ abort

void Qx::SyncDownloadManager::abort ( )

slot

Aborts all in-progress and remaining downloads immediately.

The outcome of the following manager's report is set to Outcome::Abort.

◆ appendTask()

void Qx::SyncDownloadManager::appendTask ( const DownloadTask & task )

Inserts task into the download queue.

If the same task is already present in the queue then this function does nothing.

Note: Tasks can only be added if the download manager isn't currently processing its queue.

◆ authenticationRequired

void Qx::SyncDownloadManager::authenticationRequired	(	QString	prompt,
		QAuthenticator *	authenticator )

signal

This signal is emitted whenever a final server requests authentication before it delivers the requested contents, with prompt providing user-friendly text that describes the request.

The slot connected to this signal should provide the requested credentials via authenticator, or else the download that requires this authentication will fail with an error. If no slots are connected to this signal then downloads that require authentication will always fail.

The manager caches the provided credentials internally and will send the same values if the server requires authentication again, without emitting the authenticationRequired() signal. If it rejects the credentials, this signal will be emitted again.

Note: It is not possible to use a QueuedConnection to connect to this signal, as the connection will fail if the authenticator has not been filled in with new information when the signal returns.

◆ clearTasks()

void Qx::SyncDownloadManager::clearTasks ( )

Removes all tasks from the download manager queue.

Note: Tasks can only be cleared if the download manager isn't currently processing its queue.

◆ downloadFinished

void Qx::SyncDownloadManager::downloadFinished ( Qx::DownloadOpReport downloadReport )

signal

This signal is emitted when a single download has finished, with downloadReport containing identifying and outcome related info.

◆ downloadProgress

void Qx::SyncDownloadManager::downloadProgress ( qint64 bytesCurrent )

signal

This signal is emitted to indicate the progress of all downloads handled by the manager.

It will always be emitted with a value of 0 when processing is first started in order to induce a busy state in connected progress bars.

The bytesCurrent parameter indicates the total number of bytes received since queue processing was started.

◆ downloadTotalChanged

void Qx::SyncDownloadManager::downloadTotalChanged ( quint64 bytesTotal )

signal

This signal is emitted to indicate that total number of bytes required to complete all downloads has changed, with bytesTotal containing the new value.

This will always be emitted at least twice:

Once with a value of 0 when processing is first started in order to induce a busy state in connected progress bars.
A second time just before the first batch of downloads are started after the size of all downloads in the queue have been enumerated.

It may be emitted again later when a download is started if the initially reported size was determined to be inaccurate.

Note: The potential additional emissions of this signal can cause connected progress indicators to move backwards if there was a discrepancy between the initially reported size of a file and its true size.

◆ enumerationTimeout()

int Qx::SyncDownloadManager::enumerationTimeout ( ) const

Returns the enumeration timeout of the manager, which is how long the initial file size query for a download has to complete before the manager falls back to predicting its size.

The default is 500ms.

See also: setEnumerationTimeout().

◆ hasTasks()

bool Qx::SyncDownloadManager::hasTasks ( ) const

Returns true if the manager has tasks left to process; otherwise returns false.

◆ isDeletePartialDownloads()

bool Qx::SyncDownloadManager::isDeletePartialDownloads ( ) const

Returns true if the manager is configured to remove any incomplete downloads after they fail or are aborted; otherwise, returns false.

The default is false.

See also: setDeletePartialDownloads().

◆ isOverwrite()

bool Qx::SyncDownloadManager::isOverwrite ( ) const

Returns true if the manager is configured to overwrite local files that already exist; otherwise returns false.

The default is false.

See also: setOverwrite().

◆ isProcessing()

bool Qx::SyncDownloadManager::isProcessing ( ) const

Returns true if the manager is currently processing its download queue; otherwise returns false.

◆ isSkipEnumeration()

bool Qx::SyncDownloadManager::isSkipEnumeration ( ) const

Returns true if the manager is configured to query the size of all queued tasks before actually initiating any downloads; otherwise, returns false.

If enumeration is disabled, total download progress reported by the manager will be limited in scope to only active and finished downloads, as the size of future download tasks cannot be determined until they are started. This means that every time a new download is initiated the total byte count reported by the manager will increase, causing all connected progress indicators to move backwards.

For this reason, when enumeration is disabled it is recommended to ignore the size of each download and instead track overall progress by task count only, using either taskCount() or downloadFinished() and comparing to the original queue size of the manager before processing began.

The default is false.

See also: setSkipEnumeration().

◆ isStopOnError()

bool Qx::SyncDownloadManager::isStopOnError ( ) const

Returns true if the manager is configured to automatically halt all downloads if one fails; otherwise returns false.

The default is false.

See also: setStopOnError().

◆ maxSimultaneous()

int Qx::SyncDownloadManager::maxSimultaneous ( ) const

Returns the number of allowed simultaneous downloads.

The default is 3.

See also: setMaxSimultaneous().

◆ preSharedKeyAuthenticationRequired

void Qx::SyncDownloadManager::preSharedKeyAuthenticationRequired	(	QString	prompt,
		QSslPreSharedKeyAuthenticator *	authenticator )

signal

This signal is emitted if a sever SSL/TLS handshake negotiates a PSK ciphersuite, and therefore a PSK authentication is then required. prompt provides a user-friendly text that describes the request.

The slot connected to this signal should provide the requested key via authenticator, or else the download that requires this authentication will fail with an error. If no slots are connected to this signal then downloads that require PSK authentication will always fail.

Note: It is not possible to use a QueuedConnection to connect to this signal, as the connection will fail if the authenticator has not been filled in with new information when the signal returns.

◆ processQueue()

DownloadManagerReport Qx::SyncDownloadManager::processQueue ( )

Starts processing the download queue and returns once the queue has been exhausted, a fatal error has occurred, or the processing has been aborted.

Various signals of this class are used to communicate download progress or issues with downloads during this time.

If the manager's queue is empty or the manager is already processing the queue this function does nothing and a null DownloadManagerReport is returned.

◆ proxyAuthenticationRequired

void Qx::SyncDownloadManager::proxyAuthenticationRequired	(	QString	prompt,
		QAuthenticator *	authenticator )

signal

This signal is emitted whenever a proxy requests authentication, with prompt providing user-friendly text that describes the request.

The slot connected to this signal should provide the requested credentials via authenticator, or else all downloads that rely on the proxy will fail with an error. If no slots are connected to this signal then downloads that involve authenticated proxies will always fail.

The manager caches the provided credentials internally and will send the same values if the proxy requires authentication again, without emitting the proxyAuthenticationRequired() signal. If it rejects the credentials, this signal will be emitted again.

Note: It is not possible to use a QueuedConnection to connect to this signal, as the connection will fail if the authenticator has not been filled in with new information when the signal returns.

◆ redirectPolicy()

QNetworkRequest::RedirectPolicy Qx::SyncDownloadManager::redirectPolicy ( ) const

Returns the directory policy of the manager.

The default is QNetworkRequest::NoLessSafeRedirectPolicy.

See also: setRedirectPolicy().

◆ setDeletePartialDownloads()

void Qx::SyncDownloadManager::setDeletePartialDownloads ( bool deletePartialDownloads )

Configures the manager to automatically remove incomplete files after a download fails or is aborted if deletePartialDownloads is true; otherwise, partial downloads are kept.

See also: isDeletePartialDownloads().

◆ setEnumerationTimeout()

void Qx::SyncDownloadManager::setEnumerationTimeout ( int timeout = 500 )

Sets timeout as the enumeration timeout in milliseconds.

The manager falls back to guessing a files size based on previous size queries if a given size query fails to complete before the timeout expires.

Zero means no timer is set.

See also: setEnumerationTimeout().

◆ setMaxSimultaneous()

void Qx::SyncDownloadManager::setMaxSimultaneous ( int maxSimultaneous )

Sets the number of allowed simultaneous downloads to maxSimultaneous.

A value less than one results in no limit

See also: maxSimultaneous().

◆ setOverwrite()

void Qx::SyncDownloadManager::setOverwrite ( bool overwrite )

Configures the manager to overwrite existing local files that already exist if overwrite is true; otherwise the download task that maps to destination will be aborted.

See also: isOverwrite().

◆ setRedirectPolicy()

void Qx::SyncDownloadManager::setRedirectPolicy ( QNetworkRequest::RedirectPolicy redirectPolicy )

Sets the redirect policy of the manager to redirectPolicy. This policy will affect all subsequent requests created by the manager.

Use this function to enable or disable HTTP redirects on the manager's level.

The default value is QNetworkRequest::NoLessSafeRedirectPolicy.

See also: redirectPolicy().

◆ setSkipEnumeration()

void Qx::SyncDownloadManager::setSkipEnumeration ( bool skipEnumeration )

Specifies whether or not the manager should attempt to query the size of all queued tasks before actually initiating any downloads.

See also: isSkipEnumeration().

◆ setStopOnError()

void Qx::SyncDownloadManager::setStopOnError ( bool autoAbort )

Configures the manager to automatically halt all downloads after a single failure on if stopOnError is true.

See also: isStopOnError().

◆ setTransferTimeout()

void Qx::SyncDownloadManager::setTransferTimeout ( int timeout = QNetworkRequest::DefaultTransferTimeoutConstant )

Sets timeout as the transfer timeout in milliseconds.

Transfers are aborted if no bytes are transferred before the timeout expires.

Zero means no timer is set.

See also: transferTimeout().

◆ setVerificationMethod()

void Qx::SyncDownloadManager::setVerificationMethod ( QCryptographicHash::Algorithm method )

Sets the hash algorithm used to verify downloads for tasks that include a checksum.

See also: verificationMethod() and DownloadTask::checksum.

◆ sslErrors

void Qx::SyncDownloadManager::sslErrors	(	Qx::Error	errorMsg,
		bool *	ignore )

signal

This signal is emitted if the SSL/TLS session encountered errors during the set up, including certificate verification errors. The errorMsg parameter details the errors.

To indicate that the errors are not fatal and that the connection should proceed, the ignore parameter should be set to true; otherwise the task experiencing the errors will be halted with an error.

This signal can be used to display an error message to the user indicating that security may be compromised.

Note: It is not possible to use a QueuedConnection to connect to this signal, as the connection will automatically aborts if abort has not been modified when the signal returns.

◆ taskCount()

int Qx::SyncDownloadManager::taskCount ( ) const

Returns current number of download tasks remaining, which includes pending and active downloads.

See also: hasTasks().

◆ transferTimeout()

int Qx::SyncDownloadManager::transferTimeout ( ) const

Returns the transfer timeout of the manager.

The default is zero, which means the timeout is disabled.

See also: setTransferTimeout().

◆ verificationMethod()

QCryptographicHash::Algorithm Qx::SyncDownloadManager::verificationMethod ( ) const

Returns the hash algorithm used to verify downloads for tasks that include a checksum.

The default is QCryptographicHash::Sha256.

See also: setVerificationMethod().

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

qx-downloadmanager.h
qx-downloadmanager.cpp

Public Slots

Signals

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ SyncDownloadManager()

Member Function Documentation

◆ abort

◆ appendTask()

◆ authenticationRequired

◆ clearTasks()

◆ downloadFinished

◆ downloadProgress

◆ downloadTotalChanged

◆ enumerationTimeout()

◆ hasTasks()

◆ isDeletePartialDownloads()

◆ isOverwrite()

◆ isProcessing()

◆ isSkipEnumeration()

◆ isStopOnError()

◆ maxSimultaneous()

◆ preSharedKeyAuthenticationRequired

◆ processQueue()

◆ proxyAuthenticationRequired

◆ redirectPolicy()

◆ setDeletePartialDownloads()

◆ setEnumerationTimeout()

◆ setMaxSimultaneous()

◆ setOverwrite()

◆ setRedirectPolicy()

◆ setSkipEnumeration()

◆ setStopOnError()

◆ setTransferTimeout()

◆ setVerificationMethod()

◆ sslErrors

◆ taskCount()

◆ transferTimeout()

◆ verificationMethod()