1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2016 David Faure <faure@kde.org>
4 SPDX-FileCopyrightText: 2001 Malte Starostik <malte@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#ifndef KIO_FAVICONREQUESTJOB_H
10#define KIO_FAVICONREQUESTJOB_H
11
12#include "kiogui_export.h"
13#include <kio/job_base.h> // for LoadType
14
15#include <memory>
16
17class QUrl;
18
19namespace KIO
20{
21class FavIconRequestJobPrivate;
22/*!
23 * \class KIO::FavIconRequestJob
24 * \inheaderfile KIO/FavIconRequestJob
25 * \inmodule KIOGui
26 *
27 * \brief FavIconRequestJob handles the retrieval of a favicon (either from the local cache or from the internet).
28 *
29 * For instance, the icon for http://www.google.com exists at http://www.google.com/favicon.ico
30 * This job will (the first time) download the favicon, and make it available as a local PNG
31 * for fast lookups afterwards.
32 *
33 * Usage:
34 * Create a FavIconRequestJob, connect to result(KJob *), and from there use iconFile().
35 *
36 * \code
37 * // Let's say we want to show the icon for QUrl m_url
38 * KIO::FavIconRequestJob *job = new KIO::FavIconRequestJob(m_url);
39 * connect(job, &KIO::FavIconRequestJob::result, this, [job, this](KJob *){
40 * if (!job->error()) {
41 * // show the icon using QIcon(job->iconFile())
42 * }
43 * });
44 * \endcode
45 *
46 * For a given HTTP URL, you can find out if a favicon is available by calling KIO::favIconForUrl() in KIOCore.
47 * It is however not necessary to check this first, FavIconRequestJob will do this
48 * first and emit result right away if a cached icon is available and not too old.
49 *
50 * In Web Browsers, additional information exists: the HTML for a given page can
51 * specify something like
52 * &lt;link rel="shortcut icon" href="another_favicon.ico" /&gt;
53 * To handle this, call job->setIconUrl(iconUrl).
54 * (KParts-based web engines use the signal BrowserExtension::setIconUrl to call back
55 * into the web browser application, which should then call this).
56 * The signal urlIconChanged will be emitted once the icon has been downloaded.
57 *
58 * The on-disk cache is shared between processes.
59 *
60 * \since 5.19
61 */
62class KIOGUI_EXPORT FavIconRequestJob : public KCompositeJob
63{
64 Q_OBJECT
65public:
66 /*!
67 * FavIconRequestJob constructor
68 *
69 * \a hostUrl The web page URL. We only use the scheme and host.
70 *
71 * \a reload set this to reload to skip the cache and force a refresh of the favicon.
72 *
73 * \a parent parent object
74 */
75 explicit FavIconRequestJob(const QUrl &hostUrl, KIO::LoadType reload = KIO::NoReload, QObject *parent = nullptr);
76
77 /*!
78 * Destructor. You do not need to delete the job, it will delete automatically,
79 * unless you call setAutoDelete(false).
80 */
81 ~FavIconRequestJob() override;
82
83 /*!
84 * setIconUrl allows to set, for a specific URL, a different icon URL
85 * than the default one for the host (http://host/favicon.ico)
86 *
87 * This information is stored in the on-disk cache, so that
88 * other FavIconRequestJobs for this url and KIO::favIconForUrl
89 * will return the icon specified here.
90 *
91 * \a iconUrl the URL to the icon, usually parsed from the HTML
92 */
93 void setIconUrl(const QUrl &iconUrl);
94
95 /*!
96 * Returns the full local path to the icon from the cache.
97 * Only call this in the slot connected to the result(KJob*) signal.
98 * Returns the path to the icon file
99 */
100 QString iconFile() const;
101
102 /*!
103 * Returns the URL passed to the constructor
104 * \since 5.20
105 */
106 QUrl hostUrl() const;
107
108 /*!
109 * \internal
110 * Do not call start(), KIO jobs are autostarted
111 */
112 void start() override
113 {
114 }
115
116private Q_SLOTS:
117 KIOGUI_NO_EXPORT void doStart(); // not called start() so that exec() doesn't call it too
118 void slotResult(KJob *job) override;
119
120private:
121 std::unique_ptr<FavIconRequestJobPrivate> const d;
122};
123
124}
125#endif
126

source code of kio/src/gui/faviconrequestjob.h