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

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