// Copyright (C) 2017 Ford Motor Company
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
\page qtremoteobjects-gettingstarted.html
\title Getting Started with Qt Remote Objects
\brief Detailed information on how to use Qt Remote Objects.

\section1 Introduction

The Qt Remote Objects module provides an easy way to share Qt APIs between
processes and devices. For this to work, we require a data channel between
processes and devices. To establish this data channel, first, you need a
QRemoteObjectNode.

In QtRO, a node is an endpoint for communication. In a remote objects network,
each participant, be it a process or a device, needs its own node. QtRO is a
peer-to-peer network, with connected nodes being the links in the network.

Nodes, by themselves, don’t provide much use. But their value comes when you
add QObject classes to a node to share. Then, any peer node can request a copy
or instance of the shared object from the \e{host node}, the node that shares
it.

Unlike when using normal class instances (with independent properties and
signal emissions), QtRO automatically synchronizes changes to the shared object
across all of its copies. With a few exceptions, these copies have the
identical Qt API as the original object, and are meant to be used exactly as if
the original object were available.

In QtRO, the original object is called the \l{Source}. It's a fully-implemented
C++ class, with the necessary business logic to provide the required
functionality. Copies of this object are called \l{Replica}s. You don’t need
to write any C++ code for a replica; you request an instance from a node
instead. While you do need some code to use the replica, such as connecting
signals to your own slots, you don’t need to implement the internal behavior –
that's already done for you in the source.

Because the source can be in a different process or even on a different device,
there are factors in QtRO that you need to consider, which you typically
wouldn't run into when developing without Inter-Process Communication (IPC).
Specifically, what happens if the process or device isn't there? This is where
the additions to the Replica API come in:

\list
    \li The \l{QRemoteObjectReplica::}{initialized()} signal is emitted once the
        replica has received the \l{Source}{source} state from the QtRO
        network.
    \li Both the \l{QRemoteObjectReplica::}{isReplicaValid} property and the
        \l{QRemoteObjectReplica::}{stateChanged()} signal alert you if the
        connection is lost.
\endlist

Objects shared over QtRO use the links (conduits) between nodes for all
communication. If you want to share a QObject, you must create a \e{host node}
with a URL other nodes can connect to. You can also use the \l{Registry} to
facilitate connections, but your nodes that share \l{Source}{sources} still need
to be host nodes. Each shared object is given a name (a QString), used to
identify it on the QtRO network.

\section1 Implementation

To illustrate the use of remote objects, on the source side, we need to:

\list 1
    \li Create the \l {Source} object that is replicated to other nodes, with or
        without using \l repc, the Qt Remote Objects Compiler.
    \li Optionally, create the \l{Registry}. Otherwise, use direct connections.
    \li Create a host node so that the source object can be shared.
    \li Call the node's \l{QRemoteObjectHostBase::}{enableRemoting()} function
        to share the source object.
\endlist

On the replica side, we need to:

\list 1
    \li Optionally, use \l repc to generate a \l{Replica} header for your project.
    \li Create the node that will connect with the \l{Source} host node.
    \li Call the node's \l{QRemoteObjectNode::}{acquire()} function to create a
        pointer to a replica.
\endlist

The following examples illustrate both \l{repc}-compiled static objects and dynamic
source objects. Additionally, they also show direct connections as well as
connections that use a \l{Registry} between nodes.

\list
    \li \l{Example 1: Direct Connection using a Static Source}
    \li \l{Example 2: Direct Connection with a Dynamic Replica}
    \li \l{Example 3: Connections to Remote Nodes using a Registry}
\endlist

*/
