1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
|
// Copyright (C) 2016 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
#include "qdesktopservices.h"
#ifndef QT_NO_DESKTOPSERVICES
#include <qdebug.h>
#include <qstandardpaths.h>
#include <qhash.h>
#include <qobject.h>
#include <qcoreapplication.h>
#include <private/qguiapplication_p.h>
#include <qurl.h>
#include <qmutex.h>
#include <qpa/qplatformservices.h>
#include <qpa/qplatformintegration.h>
#include <qdir.h>
QT_BEGIN_NAMESPACE
class QOpenUrlHandlerRegistry
{
public:
QOpenUrlHandlerRegistry() = default;
QRecursiveMutex mutex;
struct Handler
{
QObject *receiver;
QByteArray name;
};
typedef QHash<QString, Handler> HandlerHash;
HandlerHash handlers;
};
Q_GLOBAL_STATIC(QOpenUrlHandlerRegistry, handlerRegistry)
/*!
\class QDesktopServices
\brief The QDesktopServices class provides methods for accessing common desktop services.
\since 4.2
\ingroup desktop
\inmodule QtGui
Many desktop environments provide services that can be used by applications to
perform common tasks, such as opening a web page, in a way that is both consistent
and takes into account the user's application preferences.
This class contains functions that provide simple interfaces to these services
that indicate whether they succeeded or failed.
The openUrl() function is used to open files located at arbitrary URLs in external
applications. For URLs that correspond to resources on the local filing system
(where the URL scheme is "file"), a suitable application will be used to open the
file; otherwise, a web browser will be used to fetch and display the file.
The user's desktop settings control whether certain executable file types are
opened for browsing, or if they are executed instead. Some desktop environments
are configured to prevent users from executing files obtained from non-local URLs,
or to ask the user's permission before doing so.
\section1 URL Handlers
The behavior of the openUrl() function can be customized for individual URL
schemes to allow applications to override the default handling behavior for
certain types of URLs.
The dispatch mechanism allows only one custom handler to be used for each URL
scheme; this is set using the setUrlHandler() function. Each handler is
implemented as a slot which accepts only a single QUrl argument.
The existing handlers for each scheme can be removed with the
unsetUrlHandler() function. This returns the handling behavior for the given
scheme to the default behavior.
This system makes it easy to implement a help system, for example. Help could be
provided in labels and text browsers using \uicontrol{help://myapplication/mytopic}
URLs, and by registering a handler it becomes possible to display the help text
inside the application:
\snippet code/src_gui_util_qdesktopservices.cpp 0
\snippet code/src_gui_util_qdesktopservices.cpp setUrlHandler
If inside the handler you decide that you can't open the requested
URL, you can just call QDesktopServices::openUrl() again with the
same argument, and it will try to open the URL using the
appropriate mechanism for the user's desktop environment.
Combined with platform specific settings, the schemes registered by the
openUrl() function can also be exposed to other applications, opening up
for application deep linking or a very basic URL-based IPC mechanism.
\sa QSystemTrayIcon, QProcess, QStandardPaths
*/
/*!
Opens the given \a url in the appropriate Web browser for the user's desktop
environment, and returns \c true if successful; otherwise returns \c false.
If the URL is a reference to a local file (i.e., the URL scheme is "file") then
it will be opened with a suitable application instead of a Web browser.
The following example opens a file on the Windows file system residing on a path
that contains spaces:
\snippet code/src_gui_util_qdesktopservices.cpp 2
If a \c mailto URL is specified, the user's e-mail client will be used to open a
composer window containing the options specified in the URL, similar to the way
\c mailto links are handled by a Web browser.
For example, the following URL contains a recipient (\c{user@foo.com}), a
subject (\c{Test}), and a message body (\c{Just a test}):
\snippet code/src_gui_util_qdesktopservices.cpp 1
\warning Although many e-mail clients can send attachments and are
Unicode-aware, the user may have configured their client without these features.
Also, certain e-mail clients (e.g., Lotus Notes) have problems with long URLs.
\warning A return value of \c true indicates that the application has successfully requested
the operating system to open the URL in an external application. The external application may
still fail to launch or fail to open the requested URL. This result will not be reported back
to the application.
\warning URLs passed to this function on iOS will not load unless their schemes are
listed in the \c LSApplicationQueriesSchemes key of the application's Info.plist file.
For more information, see the Apple Developer Documentation for
\l {iOS: canOpenURL:}{canOpenURL:}.
For example, the following lines enable URLs with the HTTPS scheme:
\snippet code/src_gui_util_qdesktopservices.cpp 3
\note For Android Nougat (SDK 24) and above, URLs with a \c file scheme
are opened using \l {Android: FileProvider}{FileProvider} which tries to obtain
a shareable \c content scheme URI first. For that reason, Qt for Android defines
a file provider with the authority \c ${applicationId}.qtprovider, with \c applicationId
being the app's package name to avoid name conflicts. For more information, also see
\l {Android: Setting up file sharing}{Setting up file sharing}.
\sa setUrlHandler()
*/
bool QDesktopServices::openUrl(const QUrl &url)
{
QOpenUrlHandlerRegistry *registry = handlerRegistry();
QMutexLocker locker(®istry->mutex);
static bool insideOpenUrlHandler = false;
if (!insideOpenUrlHandler) {
QOpenUrlHandlerRegistry::HandlerHash::ConstIterator handler = registry->handlers.constFind(url.scheme());
if (handler != registry->handlers.constEnd()) {
insideOpenUrlHandler = true;
bool result = QMetaObject::invokeMethod(handler->receiver, handler->name.constData(), Qt::DirectConnection, Q_ARG(QUrl, url));
insideOpenUrlHandler = false;
return result; // ### support bool slot return type
}
}
if (!url.isValid())
return false;
QPlatformIntegration *platformIntegration = QGuiApplicationPrivate::platformIntegration();
if (Q_UNLIKELY(!platformIntegration)) {
QCoreApplication *application = QCoreApplication::instance();
if (Q_UNLIKELY(!application))
qWarning("QDesktopServices::openUrl: Please instantiate the QGuiApplication object "
"first");
else if (Q_UNLIKELY(!qobject_cast<QGuiApplication *>(application)))
qWarning("QDesktopServices::openUrl: Application is not a GUI application");
return false;
}
QPlatformServices *platformServices = platformIntegration->services();
if (!platformServices) {
qWarning("The platform plugin does not support services.");
return false;
}
// We only use openDocument if there is no fragment or query for the URL to
// avoid it being lost when using openDocument
if (url.isLocalFile() && !url.hasFragment() && !url.hasQuery())
return platformServices->openDocument(url);
return platformServices->openUrl(url);
}
/*!
Sets the handler for the given \a scheme to be the handler \a method provided by
the \a receiver object.
This function provides a way to customize the behavior of openUrl(). If openUrl()
is called with a URL with the specified \a scheme then the given \a method on the
\a receiver object is called instead of QDesktopServices launching an external
application.
The provided method must be implemented as a slot that only accepts a single QUrl
argument.
\snippet code/src_gui_util_qdesktopservices.cpp 0
If setUrlHandler() is used to set a new handler for a scheme which already
has a handler, the existing handler is simply replaced with the new one.
Since QDesktopServices does not take ownership of handlers, no objects are
deleted when a handler is replaced.
Note that the handler will always be called from within the same thread that
calls QDesktopServices::openUrl().
You must call unsetUrlHandler() before destroying the handler object, so
the destruction of the handler object does not overlap with concurrent
invocations of openUrl() using it.
\target configuring qdesktopservices url handler on ios and macos
\section1 iOS and \macos
To use this function for receiving data from other apps on iOS/\macos
you also need to add the custom scheme to the \c CFBundleURLSchemes
list in your Info.plist file:
\snippet code/src_gui_util_qdesktopservices.cpp 4
For more information, see the Apple Developer Documentation for
\l {iOS: Defining a Custom URL Scheme for Your App}{Defining a Custom URL Scheme for Your App}.
\warning It is not possible to claim support for some well known URL schemes, including http and
https. This is only allowed for Universal Links.
To claim support for http and https the above entry in the Info.plist file
is not allowed. This is only possible when you add your domain to the
Entitlements file:
\snippet code/src_gui_util_qdesktopservices.cpp 7
iOS/\macos will search for /.well-known/apple-app-site-association on your domain,
when the application is installed. If you want to listen to
\c{https://your.domain.com/help?topic=ABCDEF} you need to provide the following
content there:
\snippet code/src_gui_util_qdesktopservices.cpp 8
For more information, see the Apple Developer Documentation for
\l {iOS: Supporting Associated Domains}{Supporting Associated Domains}.
\target configuring qdesktopservices url handler on android
\section1 Android
To use this function for receiving data from other apps on Android, you
need to add one or more intent filter to the \c activity in your app manifest:
\snippet code/src_gui_util_qdesktopservices.cpp 9
For more information, see the Android Developer Documentation for
\l {Android: Create Deep Links to App Content}{Create Deep Links to App Content}.
To immediately open the corresponding content in your Android app, without
requiring the user to select the app, you need to verify your link. To
enable the verification, add an additional parameter to your intent filter:
\snippet code/src_gui_util_qdesktopservices.cpp 10
Android will look for \c{https://your.domain.com/.well-known/assetlinks.json},
when the application is installed. If you want to listen to
\c{https://your.domain.com:1337/help}, you need to provide the following
content there:
\snippet code/src_gui_util_qdesktopservices.cpp 11
For more information, see the Android Developer Documentation for
\l {Android: Verify Android App Links}{Verify Android App Links}.
\sa openUrl(), unsetUrlHandler()
*/
void QDesktopServices::setUrlHandler(const QString &scheme, QObject *receiver, const char *method)
{
QOpenUrlHandlerRegistry *registry = handlerRegistry();
QMutexLocker locker(®istry->mutex);
if (!receiver) {
registry->handlers.remove(scheme.toLower());
return;
}
QOpenUrlHandlerRegistry::Handler h;
h.receiver = receiver;
h.name = method;
registry->handlers.insert(scheme.toLower(), h);
}
/*!
Removes a previously set URL handler for the specified \a scheme.
Call this function before the handler object that was registered for \a scheme
is destroyed, to prevent concurrent openUrl() calls from continuing to call
the destroyed handler object.
\sa setUrlHandler()
*/
void QDesktopServices::unsetUrlHandler(const QString &scheme)
{
setUrlHandler(scheme, nullptr, nullptr);
}
QT_END_NAMESPACE
#endif // QT_NO_DESKTOPSERVICES
|