/usr/include/KF5/KIOGui/kio/faviconrequestjob.h

/*
 *  This file is part of the KDE libraries
 *  Copyright (c) 2016 David Faure <faure@kde.org>
 *  Copyright (C) 2001 Malte Starostik <malte@kde.org>
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; either
 *  version 2 of the License, or (at your option) any later version.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library.  If not, see <http://www.gnu.org/licenses/>.
 */

#ifndef KIO_FAVICONREQUESTJOB_H
#define KIO_FAVICONREQUESTJOB_H

#include "kiogui_export.h"
#include <kio/job_base.h> // for LoadType

class QUrl;

namespace KIO
{

class FavIconRequestJobPrivate;
/**
 * FavIconRequestJob handles the retrieval of a favicon (either from the local cache or from the internet)
 *
 * For instance, the icon for http://www.google.com exists at http://www.google.com/favicon.ico
 * This job will (the first time) download the favicon, and make it available as a local PNG
 * for fast lookups afterwards.
 *
 * Usage:
 * Create a FavIconRequestJob, connect to result(KJob *), and from there use iconFile().
 *
 * @code
 * // Let's say we want to show the icon for QUrl m_url
 * KIO::FavIconRequestJob *job = new KIO::FavIconRequestJob(m_url);
 * connect(job, &KIO::FavIconRequestJob::result, this, [job, this](KJob *){
 *     if (!job->error()) {
 *         // show the icon using QIcon(job->iconFile())
 *     }
 * });
 * @endcode
 *
 * For a given HTTP URL, you can find out if a favicon is available by calling KIO::favIconForUrl() in KIOCore.
 * It is however not necessary to check this first, FavIconRequestJob will do this
 * first and emit result right away if a cached icon is available and not too old.
 *
 * In Web Browsers, additional information exists: the HTML for a given page can
 * specify something like
 *  &lt;link rel="shortcut icon" href="another_favicon.ico" /&gt;
 * To handle this, call job->setIconUrl(iconUrl).
 * (KParts-based web engines use the signal BrowserExtension::setIconUrl to call back
 * into the web browser application, which should then call this).
 * The signal urlIconChanged will be emitted once the icon has been downloaded.
 *
 * The on-disk cache is shared between processes.
 *
 * @since 5.19
 */
class KIOGUI_EXPORT FavIconRequestJob : public KCompositeJob
{
    Q_OBJECT
public:
    /**
     * @brief FavIconRequestJob constructor
     * @param hostUrl The web page URL. We only use the scheme and host.
     * @param reload set this to reload to skip the cache and force a refresh of the favicon.
     * @param parent parent object
     */
    explicit FavIconRequestJob(const QUrl &hostUrl, KIO::LoadType reload = KIO::NoReload, QObject *parent = Q_NULLPTR);

    /**
     * Destructor. You do not need to delete the job, it will delete automatically,
     * unless you call setAutoDelete(false).
     */
    ~FavIconRequestJob();

    /**
     * @brief setIconUrl allows to set, for a specific URL, a different icon URL
     * than the default one for the host (http://host/favicon.ico)
     *
     * This information is stored in the on-disk cache, so that
     * other FavIconRequestJobs for this url and KIO::favIconForUrl
     * will return the icon specified here.
     *
     * @param iconUrl the URL to the icon, usually parsed from the HTML
     */
    void setIconUrl(const QUrl &iconUrl);

    /**
     * Returns the full local path to the icon from the cache.
     * Only call this in the slot connected to the result(KJob*) signal.
     * @return the path to the icon file
     */
    QString iconFile() const;

    /**
     * Returns the URL passed to the constructor
     * @since 5.20
     */
    QUrl hostUrl() const;

    /**
     * @internal
     * Do not call start(), KIO jobs are autostarted
     */
    void start() Q_DECL_OVERRIDE {}

private Q_SLOTS:
    void doStart(); // not called start() so that exec() doesn't call it too
    void slotResult(KJob *job) Q_DECL_OVERRIDE;

private:
    Q_PRIVATE_SLOT(d, void slotData(KIO::Job *, const QByteArray &))

    FavIconRequestJobPrivate *const d;
};

}
#endif
libkf5kio-dev 5.28.0-2 / usr / include / KF5 / KIOGui / kio / faviconrequestjob.h
