Document and safeguard usage of custom schemes

The change improves the documentation of QWebEngineUrlSchemeHandler to
notify the requirement of registering a custom scheme before installing
a custom scheme handler.

Also start showing warnings when
QWebEngineProfile::installUrlSchemeHandler() is called before a scheme
is registered. Also show warnings when installing the handler using
QML.

Task-number: QTBUG-72079
Change-Id: If249592ea43fe2f9ad587a6ff4e8c9dedcc5d3d3
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Kai Koehne <kai.koehne@qt.io>

4 files changed, 60 insertions, 6 deletions

diff --git a/src/core/api/qwebengineurlscheme.cpp b/src/core/api/qwebengineurlscheme.cpp
index f36f3335b..d63599163 100644
--- a/src/core/api/qwebengineurlscheme.cpp
+++ b/src/core/api/qwebengineurlscheme.cpp
@@ -84,8 +84,10 @@ public:
   URLs.
 
   Custom URL schemes must be configured early at application startup, before
-  creating any Qt WebEngine classes. The configuration applies globally to all
-  profiles.
+  creating any Qt WebEngine classes. In general this means the schemes need to be configured before
+  a QGuiApplication or QApplication instance is created.
+
+  Every registered scheme configuration applies globally to all profiles.
 
   \code
   int main(int argc, char **argv)
diff --git a/src/core/api/qwebengineurlschemehandler.cpp b/src/core/api/qwebengineurlschemehandler.cpp
index 94b85c42b..6f06b2c6e 100644
--- a/src/core/api/qwebengineurlschemehandler.cpp
+++ b/src/core/api/qwebengineurlschemehandler.cpp
@@ -48,12 +48,51 @@ QT_BEGIN_NAMESPACE
     \brief The QWebEngineUrlSchemeHandler is a base class for handling custom URL schemes.
     \since 5.6
 
-    To implement a custom URL scheme for QtWebEngine, you must write a class derived from this class,
-    and reimplement requestStarted(). Then install it via QWebEngineProfile::installUrlSchemeHandler()
+    To implement a custom URL scheme for QtWebEngine, you first have to create an instance of
+    QWebEngineUrlScheme and register it using QWebEngineUrlScheme::registerScheme().
+
+    \note Make sure that you create and register the scheme object \e before the QGuiApplication
+    or QApplication object is instantiated.
+
+    Then you must create a class derived from QWebEngineUrlSchemeHandler,
+    and reimplement the requestStarted() method.
+
+    Finally, install the scheme handler object via QWebEngineProfile::installUrlSchemeHandler()
     or QQuickWebEngineProfile::installUrlSchemeHandler().
 
+    \code
+
+    class MySchemeHandler : public QWebEngineUrlSchemeHandler
+    {
+    public:
+        MySchemeHandler(QObject *parent = nullptr);
+        void requestStarted(QWebEngineUrlRequestJob *request)
+        {
+            // ....
+        }
+    };
+
+    int main(int argc, char **argv)
+    {
+        QWebEngineUrlScheme scheme("myscheme");
+        scheme.setSyntax(QWebEngineUrlScheme::Syntax::HostAndPort);
+        scheme.setDefaultPort(2345);
+        scheme.setFlags(QWebEngineUrlScheme::SecureScheme);
+        QWebEngineUrlScheme::registerScheme(scheme);
+
+        // ...
+        QApplication app(argc, argv);
+        // ...
+
+        // installUrlSchemeHandler does not take ownership of the handler.
+        MySchemeHandler *handler = new MySchemeHandler(parent);
+        QWebEngineProfile::defaultProfile()->installUrlSchemeHandler("myscheme", handler);
+    }
+    \endcode
+
     \inmodule QtWebEngineCore
 
+    \sa {QWebEngineUrlScheme}, {WebEngine Widgets WebUI Example}
 */
 
 /*!
diff --git a/src/webengine/api/qquickwebengineprofile.cpp b/src/webengine/api/qquickwebengineprofile.cpp
index ed2600e49..ddc71602b 100644
--- a/src/webengine/api/qquickwebengineprofile.cpp
+++ b/src/webengine/api/qquickwebengineprofile.cpp
@@ -53,6 +53,8 @@
 #include "renderer_host/user_resource_controller_host.h"
 #include "web_engine_settings.h"
 
+#include <QtWebEngineCore/qwebengineurlscheme.h>
+
 using QtWebEngineCore::ProfileAdapter;
 
 QT_BEGIN_NAMESPACE
@@ -857,7 +859,7 @@ static bool checkInternalScheme(const QByteArray &scheme)
 /*!
     Registers a handler \a handler for custom URL scheme \a scheme in the profile.
 
-    It is recommended to first register the scheme with \l
+    It is necessary to first register the scheme with \l
     QWebEngineUrlScheme::registerScheme at application startup.
 */
 void QQuickWebEngineProfile::installUrlSchemeHandler(const QByteArray &scheme, QWebEngineUrlSchemeHandler *handler)
@@ -875,6 +877,11 @@ void QQuickWebEngineProfile::installUrlSchemeHandler(const QByteArray &scheme, Q
             qWarning("URL scheme handler already installed for the scheme: %s", scheme.constData());
         return;
     }
+
+    if (QWebEngineUrlScheme::schemeByName(canonicalScheme) == QWebEngineUrlScheme())
+        qWarning("Please register the custom scheme '%s' via QWebEngineUrlScheme::registerScheme() "
+                 "before installing the custom scheme handler.", scheme.constData());
+
     d->profileAdapter()->addCustomUrlSchemeHandler(canonicalScheme, handler);
     connect(handler, SIGNAL(_q_destroyedUrlSchemeHandler(QWebEngineUrlSchemeHandler*)), this, SLOT(destroyedUrlSchemeHandler(QWebEngineUrlSchemeHandler*)));
 }
diff --git a/src/webenginewidgets/api/qwebengineprofile.cpp b/src/webenginewidgets/api/qwebengineprofile.cpp
index 537cf41fd..03ce5e0bc 100644
--- a/src/webenginewidgets/api/qwebengineprofile.cpp
+++ b/src/webenginewidgets/api/qwebengineprofile.cpp
@@ -52,6 +52,7 @@
 #include "visited_links_manager_qt.h"
 #include "web_engine_settings.h"
 
+#include <QtWebEngineCore/qwebengineurlscheme.h>
 
 QT_BEGIN_NAMESPACE
 
@@ -688,7 +689,7 @@ static bool checkInternalScheme(const QByteArray &scheme)
 
     Registers a handler \a handler for custom URL scheme \a scheme in the profile.
 
-    It is recommended to first register the scheme with \l
+    It is necessary to first register the scheme with \l
     QWebEngineUrlScheme::registerScheme at application startup.
 */
 void QWebEngineProfile::installUrlSchemeHandler(const QByteArray &scheme, QWebEngineUrlSchemeHandler *handler)
@@ -706,6 +707,11 @@ void QWebEngineProfile::installUrlSchemeHandler(const QByteArray &scheme, QWebEn
             qWarning("URL scheme handler already installed for the scheme: %s", scheme.constData());
         return;
     }
+
+    if (QWebEngineUrlScheme::schemeByName(canonicalScheme) == QWebEngineUrlScheme())
+        qWarning("Please register the custom scheme '%s' via QWebEngineUrlScheme::registerScheme() "
+                 "before installing the custom scheme handler.", scheme.constData());
+
     d->profileAdapter()->addCustomUrlSchemeHandler(canonicalScheme, handler);
     connect(handler, SIGNAL(_q_destroyedUrlSchemeHandler(QWebEngineUrlSchemeHandler*)), this, SLOT(destroyedUrlSchemeHandler(QWebEngineUrlSchemeHandler*)));
 }