From 683c2e80d4294e44820e244f87dc9250cdc59087 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Wed, 25 Feb 2015 13:52:35 +0100 Subject: Doc: add docs for KDUpdater::FileDownloader Change-Id: I27db6645449b2da5bb5fca36270031e22fd41dad Reviewed-by: Karsten Heimrich --- src/libs/kdtools/kdupdaterfiledownloader.cpp | 370 ++++++++++++++++++++++++--- 1 file changed, 340 insertions(+), 30 deletions(-) (limited to 'src/libs/kdtools') diff --git a/src/libs/kdtools/kdupdaterfiledownloader.cpp b/src/libs/kdtools/kdupdaterfiledownloader.cpp index e31b27c88..735358afe 100644 --- a/src/libs/kdtools/kdupdaterfiledownloader.cpp +++ b/src/libs/kdtools/kdupdaterfiledownloader.cpp @@ -70,17 +70,112 @@ static double calcProgress(qint64 done, qint64 total) File downloaders are used by the KDUpdater::Update class to download update files. Each subclass of FileDownloader can download files from a specific category of sources (such as - local, ftp, http). + \c local, \c ftp, \c http). - This is an internal class, not a part of the public API. Currently we have three - subclasses of FileDownloader + This is an internal class, not a part of the public API. Currently we have the + following subclasses of FileDownloader: \list - \li Use the FtpDownloader to download files from an FTP site. - \li Use the HttpDownloader to download files from an HTTP site. - \li Use the LocalFileDownloader to download files from the local file system. + \li HttpDownloader to download files over FTP, HTTP, or HTTPS if Qt is built with SSL. + \li LocalFileDownloader to copy files from the local file system. + \li ResourceFileDownloader to download resource files. \endlist */ +/*! + \property FileDownloader::autoRemoveDownloadedFile + \brief Whether the downloaded file should be automatically removed after it + is downloaded and the class goes out of scope. +*/ + +/*! + \property FileDownloader::url + \brief The URL to download files from. +*/ + +/*! + \property FileDownloader::scheme + \brief The scheme to use for downloading files. + */ + +/*! + \fn FileDownloader::authenticatorChanged(const QAuthenticator &authenticator) + This signal is emitted when the authenticator changes to \a authenticator. +*/ + +/*! + \fn FileDownloader::canDownload() const = 0 + Returns \c true if the file exists and is readable. +*/ + +/*! + \fn FileDownloader::clone(QObject *parent=0) const = 0 + Clones the local file downloader and assigns it the parent \a parent. +*/ + +/*! + \fn FileDownloader::downloadCanceled() + This signal is emitted if downloading a file is canceled. +*/ + +/*! + \fn FileDownloader::downloadedFileName() const = 0 + Returns the file name of the downloaded file. +*/ + +/*! + \fn FileDownloader::downloadProgress(double progress) + This signal is emitted with the current download \a progress. +*/ + +/*! + \fn FileDownloader::downloadProgress(qint64 bytesReceived, qint64 bytesToReceive) + This signal is emitted with the download progress as the number of received bytes, + \a bytesReceived, and the total size of the file to download, \a bytesToReceive. +*/ + +/*! + \fn FileDownloader::downloadSpeed(qint64 bytesPerSecond) + This signal is emitted with the download speed in bytes per second as \a bytesPerSecond. +*/ + +/*! + \fn FileDownloader::downloadStarted() + This signal is emitted when downloading a file starts. +*/ + +/*! + \fn FileDownloader::downloadStatus(const QString &status) + This signal is emitted with textual representation of the current download \a status in the + following format: "100 MiB of 150 MiB - (DAYS) (HOURS) (MINUTES) (SECONDS) remaining". +*/ + +/*! + \fn FileDownloader::estimatedDownloadTime(int seconds) + This signal is emitted with the estimated download time in \a seconds. +*/ + +/*! + \fn FileDownloader::isDownloaded() const = 0 + Returns \c true if the file is downloaded. +*/ + +/*! + \fn FileDownloader::onError() = 0 + Closes the destination file if an error occurs during copying and stops + the download speed timer. +*/ + +/*! + \fn FileDownloader::onSuccess() = 0 + Closes the destination file after it has been successfully copied and stops + the download speed timer. +*/ + +/*! + \fn FileDownloader::setDownloadedFileName(const QString &name) = 0 + Sets the file name of the downloaded file to \a name. +*/ + struct KDUpdater::FileDownloader::Private { Private() @@ -130,6 +225,9 @@ struct KDUpdater::FileDownloader::Private bool m_ignoreSslErrors; }; +/*! + Creates a file downloader with the scheme \a scheme and parent \a parent. +*/ KDUpdater::FileDownloader::FileDownloader(const QString &scheme, QObject *parent) : QObject(parent) , d(new Private) @@ -138,6 +236,9 @@ KDUpdater::FileDownloader::FileDownloader(const QString &scheme, QObject *parent d->followRedirect = false; } +/*! + Destroys the file downloader. +*/ KDUpdater::FileDownloader::~FileDownloader() { delete d; @@ -153,26 +254,42 @@ QUrl KDUpdater::FileDownloader::url() const return d->url; } +/*! + Returns the SHA-1 checksum of the downloaded file. +*/ QByteArray KDUpdater::FileDownloader::sha1Sum() const { return d->m_hash.result(); } +/*! + Returns the assumed SHA-1 checksum of the file to download. +*/ QByteArray KDUpdater::FileDownloader::assumedSha1Sum() const { return d->m_assumedSha1Sum; } +/*! + Sets the assumed SHA-1 checksum of the file to download to \a sum. +*/ void KDUpdater::FileDownloader::setAssumedSha1Sum(const QByteArray &sum) { d->m_assumedSha1Sum = sum; } +/*! + Returns an error message. +*/ QString FileDownloader::errorString() const { return d->errorString; } +/*! + Sets the human readable description of the last error that occurred to \a error. Emits the + downloadStatus() and downloadAborted() signals. +*/ void FileDownloader::setDownloadAborted(const QString &error) { d->errorString = error; @@ -180,6 +297,15 @@ void FileDownloader::setDownloadAborted(const QString &error) emit downloadAborted(error); } +/*! + Sets the download status to \c completed and displays a status message. + + If an assumed SHA-1 checksum is set and the actual calculated checksum does not match it, sets + the status to \c error. If no SHA-1 is assumed, no check is performed, and status is set to + \c success. + + Emits the downloadCompleted() and downloadStatus() signals on success. +*/ void KDUpdater::FileDownloader::setDownloadCompleted() { if (d->m_assumedSha1Sum.isEmpty() || (d->m_assumedSha1Sum == sha1Sum())) { @@ -192,6 +318,9 @@ void KDUpdater::FileDownloader::setDownloadCompleted() } } +/*! + Emits the downloadCanceled() and downloadStatus() signals. +*/ void KDUpdater::FileDownloader::setDownloadCanceled() { emit downloadCanceled(); @@ -213,11 +342,17 @@ void KDUpdater::FileDownloader::setAutoRemoveDownloadedFile(bool val) d->autoRemove = val; } +/*! + Determines that redirects should be followed if \a val is \c true. +*/ void KDUpdater::FileDownloader::setFollowRedirects(bool val) { d->followRedirect = val; } +/*! + Returns whether redirects should be followed. +*/ bool KDUpdater::FileDownloader::followRedirects() const { return d->followRedirect; @@ -228,43 +363,68 @@ bool KDUpdater::FileDownloader::isAutoRemoveDownloadedFile() const return d->autoRemove; } +/*! + Downloads files. +*/ void KDUpdater::FileDownloader::download() { QMetaObject::invokeMethod(this, "doDownload", Qt::QueuedConnection); } +/*! + Cancels file download. +*/ void KDUpdater::FileDownloader::cancelDownload() { // Do nothing } +/*! + Starts the download speed timer. +*/ void KDUpdater::FileDownloader::runDownloadSpeedTimer() { if (!d->m_timer.isActive()) d->m_timer.start(d->m_speedTimerInterval, this); } +/*! + Stops the download speed timer. +*/ void KDUpdater::FileDownloader::stopDownloadSpeedTimer() { d->m_timer.stop(); } +/*! + Adds \a sample to the current speed bin. +*/ void KDUpdater::FileDownloader::addSample(qint64 sample) { d->m_currentSpeedBin += sample; } +/*! + Returns the download speed timer ID. +*/ int KDUpdater::FileDownloader::downloadSpeedTimerId() const { return d->m_timer.timerId(); } +/*! + Sets the file download progress to the number of received bytes, \a bytesReceived, + and the number of total bytes to receive, \a bytesToReceive. +*/ void KDUpdater::FileDownloader::setProgress(qint64 bytesReceived, qint64 bytesToReceive) { d->m_bytesReceived = bytesReceived; d->m_bytesToReceive = bytesToReceive; } +/*! + Calculates the download speed in bytes per second and emits the downloadSpeed() signal. +*/ void KDUpdater::FileDownloader::emitDownloadSpeed() { unsigned int windowSize = sizeof(d->m_samples) / sizeof(qint64); @@ -290,6 +450,12 @@ void KDUpdater::FileDownloader::emitDownloadSpeed() emit downloadSpeed(d->m_downloadSpeed); } +/*! + Builds a textual representation of the download status in the following format: + "100 MiB of 150 MiB - (DAYS) (HOURS) (MINUTES) (SECONDS) remaining". + + Emits the downloadStatus() signal. +*/ void KDUpdater::FileDownloader::emitDownloadStatus() { QString status; @@ -342,11 +508,17 @@ void KDUpdater::FileDownloader::emitDownloadStatus() emit downloadStatus(status); } +/*! + Emits dowload progress. +*/ void KDUpdater::FileDownloader::emitDownloadProgress() { emit downloadProgress(d->m_bytesReceived, d->m_bytesToReceive); } +/*! + Emits the estimated download time. +*/ void KDUpdater::FileDownloader::emitEstimatedDownloadTime() { if (d->m_bytesToReceive <= 0 || d->m_downloadSpeed <= 0) { @@ -356,16 +528,25 @@ void KDUpdater::FileDownloader::emitEstimatedDownloadTime() emit estimatedDownloadTime((d->m_bytesToReceive - d->m_bytesReceived) / d->m_downloadSpeed); } +/*! + \overload addCheckSumData() +*/ void KDUpdater::FileDownloader::addCheckSumData(const QByteArray &data) { d->m_hash.addData(data); } +/*! + Adds the \a length of characters of \a data to the cryptographic hash of the downloaded file. +*/ void KDUpdater::FileDownloader::addCheckSumData(const char *data, int length) { d->m_hash.addData(data, length); } +/*! + Resets SHA-1 checksum data of the downloaded file. +*/ void KDUpdater::FileDownloader::resetCheckSumData() { d->m_hash.reset(); @@ -373,8 +554,8 @@ void KDUpdater::FileDownloader::resetCheckSumData() /*! - Returns a copy of the proxy factory that this FileDownloader object is using to determine the proxies to - be used for requests. + Returns a copy of the proxy factory that this FileDownloader object is using to determine the + proxies to be used for requests. */ FileDownloaderProxyFactory *KDUpdater::FileDownloader::proxyFactory() const { @@ -384,9 +565,9 @@ FileDownloaderProxyFactory *KDUpdater::FileDownloader::proxyFactory() const } /*! - Sets the proxy factory for this class to be \a factory. A proxy factory is used to determine a more - specific list of proxies to be used for a given request, instead of trying to use the same proxy value - for all requests. This might only be of use for http or ftp requests. + Sets the proxy factory for this class to be \a factory. A proxy factory is used to determine a + more specific list of proxies to be used for a given request, instead of trying to use the same + proxy value for all requests. This might only be of use for HTTP or FTP requests. */ void KDUpdater::FileDownloader::setProxyFactory(FileDownloaderProxyFactory *factory) { @@ -395,8 +576,8 @@ void KDUpdater::FileDownloader::setProxyFactory(FileDownloaderProxyFactory *fact } /*! - Returns a copy of the authenticator that this FileDownloader object is using to set the username and - password for download request. + Returns a copy of the authenticator that this FileDownloader object is using to set the username + and password for a download request. */ QAuthenticator KDUpdater::FileDownloader::authenticator() const { @@ -404,9 +585,9 @@ QAuthenticator KDUpdater::FileDownloader::authenticator() const } /*! - Sets the authenticator object for this class to be \a authenticator. A authenticator is used to - pass on the required authentication information. This might only be of use for http or ftp requests. - Emits the authenticator changed signal with the new authenticator in use. + Sets the authenticator object for this class to be \a authenticator. An authenticator is used to + pass on the required authentication information. This might only be of use for HTTP or FTP + requests. Emits the authenticator changed signal with the new authenticator in use. */ void KDUpdater::FileDownloader::setAuthenticator(const QAuthenticator &authenticator) { @@ -416,11 +597,17 @@ void KDUpdater::FileDownloader::setAuthenticator(const QAuthenticator &authentic } } +/*! + Returns \c true if SSL errors should be ignored. +*/ bool KDUpdater::FileDownloader::ignoreSslErrors() { return d->m_ignoreSslErrors; } +/*! + Determines that SSL errors should be ignored if \a ignore is \c true. +*/ void KDUpdater::FileDownloader::setIgnoreSslErrors(bool ignore) { d->m_ignoreSslErrors = ignore; @@ -428,20 +615,17 @@ void KDUpdater::FileDownloader::setIgnoreSslErrors(bool ignore) // -- KDUpdater::LocalFileDownloader -/* - Even though QFile::copy() does the task of copying local files from one place - to another, I prefer to use the timer and copy one block of data per unit time. - - This is because, it is possible that the user of KDUpdater is simultaneously - downloading several files. Sometimes in tandem with other file downloaders. - If the local file that is being downloaded takes a long time; then that will - hang the other downloads. - - On the other hand, local downloads need not actually download the file. It can - simply pass on the source file as destination file. At this moment however, - I think the user of LocalFileDownloader will assume that the downloaded file - can be fiddled around with without worrying about whether it would mess up - the original source or not. +/*! + \inmodule kdupdater + \class KDUpdater::LocalFileDownloader + \brief The LocalFileDownloader class is used to copy files from the local + file system. + + The user of KDUpdater might be simultaneously downloading several files; + sometimes in parallel to other file downloaders. If copying a local file takes + a long time, it will make the other downloads hang. Therefore, a timer is used + and one block of data is copied per unit time, even though QFile::copy() does the + task of copying local files from one place to another. */ struct KDUpdater::LocalFileDownloader::Private @@ -460,12 +644,18 @@ struct KDUpdater::LocalFileDownloader::Private int timerId; }; +/*! + Creates a local file downloader with the parent \a parent. +*/ KDUpdater::LocalFileDownloader::LocalFileDownloader(QObject *parent) : KDUpdater::FileDownloader(QLatin1String("file"), parent) , d (new Private) { } +/*! + Destroys the local file downloader. +*/ KDUpdater::LocalFileDownloader::~LocalFileDownloader() { if (this->isAutoRemoveDownloadedFile() && !d->destFileName.isEmpty()) @@ -474,12 +664,18 @@ KDUpdater::LocalFileDownloader::~LocalFileDownloader() delete d; } +/*! + Returns \c true if the file exists and is readable. +*/ bool KDUpdater::LocalFileDownloader::canDownload() const { QFileInfo fi(url().toLocalFile()); return fi.exists() && fi.isReadable(); } +/*! + Returns \c true if the file is copied. +*/ bool KDUpdater::LocalFileDownloader::isDownloaded() const { return d->downloaded; @@ -529,21 +725,34 @@ void KDUpdater::LocalFileDownloader::doDownload() emit downloadProgress(0); } +/*! + Returns the file name of the copied file. +*/ QString KDUpdater::LocalFileDownloader::downloadedFileName() const { return d->destFileName; } +/*! + Sets the file name of the copied file to \a name. +*/ void KDUpdater::LocalFileDownloader::setDownloadedFileName(const QString &name) { d->destFileName = name; } +/*! + Clones the local file downloader and assigns it the parent \a parent. Returns + the new local file downloader. +*/ KDUpdater::LocalFileDownloader *KDUpdater::LocalFileDownloader::clone(QObject *parent) const { return new LocalFileDownloader(parent); } +/*! + Cancels copying the file. +*/ void KDUpdater::LocalFileDownloader::cancelDownload() { if (d->timerId < 0) @@ -556,6 +765,9 @@ void KDUpdater::LocalFileDownloader::cancelDownload() setDownloadCanceled(); } +/*! + Called when the download timer event \a event occurs. +*/ void KDUpdater::LocalFileDownloader::timerEvent(QTimerEvent *event) { if (event->timerId() == d->timerId) { @@ -602,6 +814,10 @@ void KDUpdater::LocalFileDownloader::timerEvent(QTimerEvent *event) } } +/*! + Closes the destination file after it has been successfully copied and stops + the download speed timer. +*/ void LocalFileDownloader::onSuccess() { d->downloaded = true; @@ -616,6 +832,10 @@ void LocalFileDownloader::onSuccess() stopDownloadSpeedTimer(); } +/*! + Clears the destination file if an error occurs during copying and stops + the download speed timer. +*/ void LocalFileDownloader::onError() { d->downloaded = false; @@ -630,6 +850,11 @@ void LocalFileDownloader::onError() // -- ResourceFileDownloader +/*! + \inmodule kdupdater + \class KDUpdater::ResourceFileDownloader + \brief The ResourceFileDownloader class can be used to download resource files. +*/ struct KDUpdater::ResourceFileDownloader::Private { Private() @@ -642,28 +867,43 @@ struct KDUpdater::ResourceFileDownloader::Private bool downloaded; }; +/*! + Creates a resource file downloader with the parent \a parent. +*/ KDUpdater::ResourceFileDownloader::ResourceFileDownloader(QObject *parent) : KDUpdater::FileDownloader(QLatin1String("resource"), parent) , d(new Private) { } +/*! + Destroys the resource file downloader. +*/ KDUpdater::ResourceFileDownloader::~ResourceFileDownloader() { delete d; } +/*! + Returns \c true if the file exists and is readable. +*/ bool KDUpdater::ResourceFileDownloader::canDownload() const { const QFileInfo fi(QInstaller::pathFromUrl(url())); return fi.exists() && fi.isReadable(); } +/*! + Returns \c true if the file is downloaded. +*/ bool KDUpdater::ResourceFileDownloader::isDownloaded() const { return d->downloaded; } +/*! + Downloads a resource file. +*/ void KDUpdater::ResourceFileDownloader::doDownload() { // Already downloaded @@ -686,21 +926,34 @@ void KDUpdater::ResourceFileDownloader::doDownload() d->timerId = startTimer(0); // start as fast as possible } +/*! + Returns the file name of the downloaded file. +*/ QString KDUpdater::ResourceFileDownloader::downloadedFileName() const { return d->destFile.fileName(); } +/*! + Sets the file name of the downloaded file to \a name. +*/ void KDUpdater::ResourceFileDownloader::setDownloadedFileName(const QString &/*name*/) { // Not supported! } +/*! + Clones the resource file downloader and assigns it the parent \a parent. Returns + the new resource file downloader. +*/ KDUpdater::ResourceFileDownloader *KDUpdater::ResourceFileDownloader::clone(QObject *parent) const { return new ResourceFileDownloader(parent); } +/*! + Cancels downloading the file. +*/ void KDUpdater::ResourceFileDownloader::cancelDownload() { if (d->timerId < 0) @@ -712,6 +965,9 @@ void KDUpdater::ResourceFileDownloader::cancelDownload() setDownloadCanceled(); } +/*! + Called when the download timer event \a event occurs. +*/ void KDUpdater::ResourceFileDownloader::timerEvent(QTimerEvent *event) { if (event->timerId() == d->timerId) { @@ -748,6 +1004,10 @@ void KDUpdater::ResourceFileDownloader::timerEvent(QTimerEvent *event) } } +/*! + Closes the destination file after it has been successfully copied and stops + the download speed timer. +*/ void KDUpdater::ResourceFileDownloader::onSuccess() { d->destFile.close(); @@ -755,6 +1015,10 @@ void KDUpdater::ResourceFileDownloader::onSuccess() stopDownloadSpeedTimer(); } +/*! + Closes the destination file if an error occurs during copying and stops + the download speed timer. +*/ void KDUpdater::ResourceFileDownloader::onError() { d->destFile.close(); @@ -766,6 +1030,13 @@ void KDUpdater::ResourceFileDownloader::onError() // -- KDUpdater::HttpDownloader +/*! + \inmodule kdupdater + \class KDUpdater::HttpDownloader + \brief The HttpDownloader class is used to download files over FTP, HTTP, or HTTPS. + + HTTPS is supported if Qt is built with SSL. +*/ struct KDUpdater::HttpDownloader::Private { explicit Private(HttpDownloader *qq) @@ -798,6 +1069,9 @@ struct KDUpdater::HttpDownloader::Private } }; +/*! + Creates an HTTP downloader with the parent \a parent. +*/ KDUpdater::HttpDownloader::HttpDownloader(QObject *parent) : KDUpdater::FileDownloader(QLatin1String("http"), parent) , d(new Private(this)) @@ -810,6 +1084,12 @@ KDUpdater::HttpDownloader::HttpDownloader(QObject *parent) SLOT(onAuthenticationRequired(QNetworkReply*, QAuthenticator*))); } +/*! + Destroys an HTTP downloader. + + Removes the downloaded file if FileDownloader::isAutoRemoveDownloadedFile() returns \c true or + FileDownloader::setAutoRemoveDownloadedFile() was called with \c true. +*/ KDUpdater::HttpDownloader::~HttpDownloader() { if (this->isAutoRemoveDownloadedFile() && !d->destFileName.isEmpty()) @@ -817,12 +1097,18 @@ KDUpdater::HttpDownloader::~HttpDownloader() delete d; } +/*! + Returns \c true if the file exists and is readable. +*/ bool KDUpdater::HttpDownloader::canDownload() const { // TODO: Check whether the http file actually exists or not. return true; } +/*! + Returns \c true if the file is downloaded. +*/ bool KDUpdater::HttpDownloader::isDownloaded() const { return d->downloaded; @@ -840,16 +1126,26 @@ void KDUpdater::HttpDownloader::doDownload() runDownloadSpeedTimer(); } +/*! + Returns the file name of the downloaded file. +*/ QString KDUpdater::HttpDownloader::downloadedFileName() const { return d->destFileName; } +/*! + Sets the file name of the downloaded file to \a name. +*/ void KDUpdater::HttpDownloader::setDownloadedFileName(const QString &name) { d->destFileName = name; } +/*! + Clones the HTTP downloader and assigns it the parent \a parent. Returns the new + HTTP downloader. +*/ KDUpdater::HttpDownloader *KDUpdater::HttpDownloader::clone(QObject *parent) const { return new HttpDownloader(parent); @@ -884,6 +1180,9 @@ void KDUpdater::HttpDownloader::httpError(QNetworkReply::NetworkError) httpDone(true); } +/*! + Cancels downloading the file. +*/ void KDUpdater::HttpDownloader::cancelDownload() { d->aborted = true; @@ -914,6 +1213,10 @@ void KDUpdater::HttpDownloader::httpDone(bool error) //PENDING: what about the non-error case?? } +/*! + Closes the destination file if an error occurs during copying and stops + the download speed timer. +*/ void KDUpdater::HttpDownloader::onError() { d->downloaded = false; @@ -923,6 +1226,10 @@ void KDUpdater::HttpDownloader::onError() stopDownloadSpeedTimer(); } +/*! + Closes the destination file after it has been successfully copied and stops + the download speed timer. +*/ void KDUpdater::HttpDownloader::onSuccess() { d->downloaded = true; @@ -967,6 +1274,9 @@ void KDUpdater::HttpDownloader::httpReadProgress(qint64 done, qint64 total) emit downloadProgress(calcProgress(done, total)); } +/*! + Called when the download timer event \a event occurs. +*/ void KDUpdater::HttpDownloader::timerEvent(QTimerEvent *event) { if (event->timerId() == downloadSpeedTimerId()) { -- cgit v1.2.3