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 | |
17 | class QUrl; |
18 | |
19 | namespace KIO |
20 | { |
21 | class 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 | * <link rel="shortcut icon" href="another_favicon.ico" /> |
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 | */ |
62 | class KIOGUI_EXPORT FavIconRequestJob : public KCompositeJob |
63 | { |
64 | Q_OBJECT |
65 | public: |
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 | |
116 | private 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 | |
120 | private: |
121 | std::unique_ptr<FavIconRequestJobPrivate> const d; |
122 | }; |
123 | |
124 | } |
125 | #endif |
126 | |