1/****************************************************************************
2**
3** Copyright (C) 2017 Ford Motor Company
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:FDL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Free Documentation License Usage
18** Alternatively, this file may be used under the terms of the GNU Free
19** Documentation License version 1.3 as published by the Free Software
20** Foundation and appearing in the file included in the packaging of
21** this file. Please review the following information to ensure
22** the GNU Free Documentation License version 1.3 requirements
23** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29\page qtremoteobjects-gettingstarted.html
30\title Getting Started with Qt Remote Objects
31\brief Detailed information on how to use Qt Remote Objects.
32
33\section1 Introduction
34
35The Qt Remote Objects module provides an easy way to share Qt APIs between
36processes and devices. For this to work, we require a data channel between
37processes and devices. To establish this data channel, first, you need a
38QRemoteObjectNode.
39
40In QtRO, a node is an endpoint for communication. In a remote objects network,
41each participant, be it a process or a device, needs its own node. QtRO is a
42peer-to-peer network, with connected nodes being the links in the network.
43
44Nodes, by themselves, don’t provide much use. But their value comes when you
45add QObject classes to a node to share. Then, any peer node can request a copy
46or instance of the shared object from the \e{host node}, the node that shares
47it.
48
49Unlike when using normal class instances (with independent properties and
50signal emissions), QtRO automatically synchronizes changes to the shared object
51across all of its copies. With a few exceptions, these copies have the
52identical Qt API as the original object, and are meant to be used exactly as if
53the original object were available.
54
55In QtRO, the original object is called the \l{Source}. It's a fully-implemented
56C++ class, with the necessary business logic to provide the required
57functionality. Copies of this object are called \l{Replica}s. You don’t need
58to write any C++ code for a replica; you request an instance from a node
59instead. While you do need some code to use the replica, such as connecting
60signals to your own slots, you don’t need to implement the internal behavior –
61that's already done for you in the source.
62
63Because the source can be in a different process or even on a different device,
64there are factors in QtRO that you need to consider, which you typically
65wouldn't run into when developing without Inter-Process Communication (IPC).
66Specifically, what happens if the process or device isn't there? This is where
67the additions to the Replica API come in:
68
69\list
70    \li The \l{QRemoteObjectReplica::}{initialized()} signal is emitted once the
71        replica has received the \l{Source}{source} state from the QtRO
72        network.
73    \li Both the \l{QRemoteObjectReplica::}{isReplicaValid} property and the
74        \l{QRemoteObjectReplica::}{stateChanged()} signal alert you if the
75        connection is lost.
76\endlist
77
78Objects shared over QtRO use the links (conduits) between nodes for all
79communication. If you want to share a QObject, you must create a \e{host node}
80with a URL other nodes can connect to. You can also use the \l{Registry} to
81facilitate connections, but your nodes that share \l{Source}{sources} still need
82to be host nodes. Each shared object is given a name (a QString), used to
83identify it on the QtRO network.
84
85\section1 Implementation
86
87To illustrate the use of remote objects, on the source side, we need to:
88
89\list 1
90    \li Create the \l {Source} object that is replicated to other nodes, with or
91        without using \l repc, the Qt Remote Objects Compiler.
92    \li Optionally, create the \l{Registry}. Otherwise, use direct connections.
93    \li Create a host node so that the source object can be shared.
94    \li Call the node's \l{QRemoteObjectHostBase::}{enableRemoting()} function
95        to share the source object.
96\endlist
97
98On the replica side, we need to:
99
100\list 1
101    \li Optionally, use \l repc to generate a \l{Replica} header for your project.
102    \li Create the node that will connect with the \l{Source} host node.
103    \li Call the node's \l{QRemoteObjectNode::}{acquire()} function to create a
104        pointer to a replica.
105\endlist
106
107The following examples illustrate both \l{repc}-compiled static objects and dynamic
108source objects. Additionally, they also show direct connections as well as
109connections that use a \l{Registry} between nodes.
110
111\list
112    \li \l{Example 1: Direct Connection using a Static Source}
113    \li \l{Example 2: Direct Connection with a Dynamic Replica}
114    \li \l{Example 3: Connections to Remote Nodes using a Registry}
115\endlist
116
117*/
118