view ui/downloader.h @ 1255:2a1aa9df8f11

(issue133) Improve API documentation
author Andre Heinecke <andre.heinecke@intevation.de>
date Thu, 25 Sep 2014 17:58:12 +0200
parents 78798d3af8f0
children
line wrap: on
line source
/* Copyright (C) 2014 by Bundesamt für Sicherheit in der Informationstechnik
 * Software engineering by Intevation GmbH
 *
 * This file is Free Software under the GNU GPL (v>=2)
 * and comes with ABSOLUTELY NO WARRANTY!
 * See LICENSE.txt for details.
 */
#ifndef DOWNLOADER_H
#define DOWNLOADER_H
/**
 * @file downloader.h
 * @brief High level API to download necessary data.
 *
 */

#include <QThread>
#include <QDateTime>
#include <QString>
#include <QByteArray>

#include "sslconnection.h"

/** @brief High level API to download necessary data.
 *
 * The downloader class is the UI interface to the Update server.
 * It controls the SSL Connection and checks if updates are available
 * and downloads them on demand. Each Downloader object is intended
 * to be run only once and controlled mainly by the constructor of
 * the object.
 */
class Downloader: public QThread
{
    Q_OBJECT

public:
    /**
     * @brief Construct a downloader with a specific certificate
     *
     * The downloader will check the last-modified date of the
     * certificate list / sw on the server at the specified url
     * and download those accordingly. If newestSW or newestList is
     * are valid datetimes only files modified after the respective date
     * are downloaded.
     *
     * Downloaded files are placed in QStandardPaths::DataLocation
     *
     * @param[in] parent the parent object.
     * @param[in] url the Url to download data from
     * @param[in] certificate optional certificate to validate https connection
     * @param[in] newestSW datetime after which software should be downloaded
     * @param[in] newestList datetime after which the list should be downloaded
     * @param[in] resourceSW the path where the software is to be found
     * @param[in] resourceList the path where the list is to be found
     * @param[in] downloadSW TODO
     */
    Downloader(QObject* parent, const QString& url,
               const QByteArray& certificate = QByteArray(),
               const QDateTime& newestSW = QDateTime(),
               const QDateTime& newestList = QDateTime(),
               const QString& resourceSW = QString(),
               const QString& resourceList = QString(),
               bool downloadSW = true);

    ~Downloader();

    /**
     * @brief get the directory where the downloader saves data
     *
     * If the directory does not exist this function ensures that it
     * is created.
     *
     * @returns The directory in which downloaded files are placed.
     **/
    QString getDataDirectory();

    /**
     * @brief get the current error state
     *
     * @returns The current error state.
     **/
    SSLConnection::ErrorCode getErrorState();


    /**
     * @brief forward the setCiphersuites call to the sslconnection
     *
     * see sslconnection.h for details.
     */
    void setCiphersuites(int suites[]);

protected:
    void run();

private:
    QDateTime mLastModSW;
    QDateTime mLastModList;

    QString mResourceSW;
    QString mResourceList;

    bool mDownloadSW;

    SSLConnection *mSSLConnection;

Q_SIGNALS:
    /**
     * @brief software update is available
     */
    void newSoftwareAvailable(const QString &fileName,
            const QDateTime &lastMod);

    /**
     * @brief new certificate list available
     */
    void newListAvailable(const QString &fileName, const QDateTime &lastMod);

    /**
     * @brief Some progress has been made.
     *
     * @param[out] message: A message to show. Can be empty.
     * @param[out] current: Value of current progress.
     * @param[out] total: Total value of possible progress
     */
    void progress(const QString &message, int current, int total);

    /**
     * @brief An error happened
     *
     * @param[out] message: A message to show. Can be empty.
     * @param[out] error: ErrorCode of this error.
     */
    void error(const QString &message, SSLConnection::ErrorCode error);

    /**
     * @brief Found the last modified date for software.
     *
     * @param[out] date The last modified date.
     */
    void lastModifiedDate(const QDateTime &date);
};
#endif

http://wald.intevation.org/projects/trustbridge/