summaryrefslogtreecommitdiff
path: root/examples/webenginewidgets/webui/doc/src/webui.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'examples/webenginewidgets/webui/doc/src/webui.qdoc')
-rw-r--r--examples/webenginewidgets/webui/doc/src/webui.qdoc141
1 files changed, 0 insertions, 141 deletions
diff --git a/examples/webenginewidgets/webui/doc/src/webui.qdoc b/examples/webenginewidgets/webui/doc/src/webui.qdoc
deleted file mode 100644
index c8ab43ea8..000000000
--- a/examples/webenginewidgets/webui/doc/src/webui.qdoc
+++ /dev/null
@@ -1,141 +0,0 @@
-// Copyright (C) 2018 The Qt Company Ltd.
-// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
-
-/*!
- \example webenginewidgets/webui
- \title WebEngine Widgets WebUI Example
- \ingroup webengine-widgetexamples
- \brief Displays HTML over a custom scheme.
-
- \image webui-example.png
-
- \e {WebUI} demonstrates how to implement a custom scheme in a secure way.
-
- Aside from the built-in URL schemes, such as \c {http} and \c {qrc},
- \QWE may be extended with \e {custom schemes} by creating \e {custom
- scheme handlers}. This example shows:
-
- \list
- \li How to create a custom scheme handler which serves HTML and handles
- HTML form submissions.
- \li How to prevent ordinary web content from accessing the custom scheme.
- \li How to prevent any other scheme from submitting HTML form data.
- \endlist
-
- \include examples-run.qdocinc
-
- \section1 Overview
-
- The example program consists of a single \l {QWebEngineView} showing a
- simple HTML page loaded from the URL \c {webui:about}, over our custom
- scheme. Pressing the button at the bottom of the page will trigger an HTML
- form submission via POST to the same URL, at which point our custom scheme
- handler will cause the application to exit.
-
- The program is divided into two parts, the \c {main} function for setting
- everything up, and the \c {WebUiHandler} class for implementing our custom
- scheme handler. The \c {main} function is quite short:
-
- \quotefromfile webenginewidgets/webui/main.cpp
- \skipto int main
- \printuntil /^\}/
-
- Aside from the relatively standard setup of widgets, two points are
- noteworthy. First, we call the static method \c
- {WebUiHandler::registerUrlScheme()} to register our custom scheme with the
- web engine. Second, we create and install our custom scheme handler \c
- {WebUiHandler} using \l
- {QWebEngineProfile::installUrlSchemeHandler()}{installUrlSchemeHandler()}.
- The following sections describe these aspects in more detail.
-
- \section1 Registering the Scheme
-
- As custom schemes are integrated directly into the web engine, they do not
- necessarily need to follow the standard security rules which apply to
- ordinary web content. Depending on the chosen configuration, content served
- over a custom scheme may be given access to local resources, be set to
- ignore Content-Security-Policy rules, or conversely, be denied access to any
- other content entirely.
-
- In order to take advantage of these possibilities, the custom scheme must
- first be registered. This means creating and configuring a \l
- {QWebEngineUrlScheme} object and then handing it over to \l
- {QWebEngineUrlScheme::registerScheme()}. The example program does exactly this in
- the static method \c {WebUiHandler::registerUrlScheme()}:
-
- \quotefromfile webenginewidgets/webui/webuihandler.cpp
- \skipto void WebUiHandler::registerUrlScheme
- \printuntil /^\}/
-
- A custom scheme needs a name, which can be set by passing it to
- the constructor of \c {QWebEngineUrlScheme} or by calling \l
- {QWebEngineUrlScheme::setName}. In the above, the name \c {webui} is set
- through the constructor. Additionally, we activate the flags \l
- {QWebEngineUrlScheme::SecureScheme}{SecureScheme}, \l
- {QWebEngineUrlScheme::LocalScheme}{LocalScheme} and \l
- {QWebEngineUrlScheme::LocalAccessAllowed}{LocalAccessAllowed}. Since our
- custom scheme handler will not deliver resources received from insecure
- network connections, we can safely mark it as a \c {SecureScheme}. The \c {LocalScheme}
- flag prevents content from non-local schemes (such as \c {http}) from
- interacting with our custom scheme. Without this flag it would be possible,
- for example, to embed the \c {webui:about} page in an \c <iframe> element on
- a remotely loaded HTML page, perhaps to attempt a phishing attack. We also
- need the \c {LocalAccessAllowed} flag without which we would not be able to
- access the \c {webui} scheme from our \c {webui:about} page.
-
- Earlier we saw that the call to \c {WebUiHandler::registerUrlScheme()} is
- made already at the top of the \c {main} function. This is so because custom
- schemes need to be registered as early as possible so that that they can be
- passed to all subprocesses. Specifically, custom schemes need to be registered
- before any other \QWE classes are instantiated by the application.
-
- \section1 Handling Requests
-
- A custom scheme handler is, broadly speaking, similar to a web application
- served over HTTP. However, because custom schemes are integrated directly
- into the web engine, they have the advantage in terms of efficiency: there's
- no need for generating and parsing HTTP messages or for transferring data
- over sockets.
-
- Implementing a handler means creating a subclass of \l
- {QWebEngineUrlSchemeHandler}, which is just what is done by the \c
- {WebUiHandler} class of the example program:
-
- \quotefromfile webenginewidgets/webui/webuihandler.h
- \skipto class WebUiHandler
- \printuntil /^\}/
-
- For each request to a \c {webui} URL, the \c
- {WebUiHandler::requestStarted()} method will be called:
-
- \quotefromfile webenginewidgets/webui/webuihandler.cpp
- \skipto void WebUiHandler::requestStarted
- \printuntil /^\}/
-
- The \l {QWebEngineUrlRequestJob} object \c {job} contains the request's
- attributes and provides methods for replying to the request with a response.
- Responses are generated asynchronously by reading them from the \l
- {QIODevice} that the application passes to \l
- {QWebEngineUrlRequestJob::reply()}{reply()}.
-
- \warning The \c requestStarted() method is not called from the main thread,
- but from the web engine's IO thread. Care must be taken to synchronize
- access to any resources on the main thread.
-
- Aside from the usual fare of \l
- {QWebEngineUrlRequestJob::requestMethod()}{requestMethod} and \l
- {QWebEngineUrlRequestJob::requestUrl()}{requestUrl}, there is also the \l
- {QWebEngineUrlRequestJob::initiator()}{initiator}, holding the origin of the
- content which initiated the request. An empty \c initiator means the request
- was initiated directly by the application (via \l
- {QWebEnginePage::setUrl()}, for example). The special value \c "null"
- corresponds to an opaque origin (a sandboxed \c {<iframe>} element, for
- example). Otherwise, the \c initiator will contain the URL scheme, hostname,
- and port of the content which initiated the request.
-
- In this example, the \c initiator is used to ensure that \c {POST} requests
- to \c {webui:about} will only trigger the application's exit if they
- originate from the \c {webui} scheme. This prevents content loaded over
- other schemes from triggering the application's exit.
-
-*/