/****************************************************************************
**
** Copyright (C) 2018 Ford Motor Company
** Contact: https://www.qt.io/licensing/
**
** 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 The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtremoteobjects-node.html
\title Qt Remote Objects Nodes
\brief Describes how Qt Remote Objects pass data between nodes.

In a QtRO network, information is passed between processes via
QRemoteObjectNodes ("nodes"). This peer-to-peer functionality uses a small
number of distinct packets passing the necessary data between nodes.

Each process that participates in the network instantiates a Node-based type,
such as QRemoteObjectNode, QRemoteObjectHost, or QRemoteObjectRegistryHost.
The host types of Nodes provide additional functionality. Both
QRemoteObjectHost and QRemoteObjectRegistryHost support the
\l{QRemoteObjectHostBase::}{enableRemoting()} and the corresponding
\l{QRemoteObjectHostBase::}{disableRemoting()}) methods, which are the key
methods to expose source objects to the network. To use the \l Registry
functionality, you need to have a QRemoteObjectRegistryHost on the network.
Then, all other nodes can pass the RegistryHost's URL to the Node's
\c registryAddress constructor parameter, or pass the URL to the
\l {QRemoteObjectNode::}{setRegistryUrl()} method.

Since QtRO is a peer-to-peer network, to
\l{QRemoteObjectNode::acquire()}{acquire()} a valid \l{Replica}, the replica's
node needs to be connected to the node that hosts its \l{Source}. A host node is a
node that allows other nodes to connect to it, which is accomplished by giving
hosts unique addresses. This address is provided to the QRemoteObjectHost
constructor or set by the setHostUrl method. The node from which a replica is
requested must establish the connection to the host node, to initialize the
replica and keep it up to date.

\section1 Connecting Nodes using QtRO URLs

Host Nodes use custom URLs to simplify connections. Currently, QtRO supports
two types of connections:

\list 1
    \li A TCP connection using the standard TCP/IP protocol - supports
        connections between devices as well as between processes on the same
        device.
    \li A local connection - supports connections between processes on the same
        device. This type of connection can have less overhead, depending on
        the underlying Operating System features.
\endlist

For local connections, you must use a unique name. For TCP connections, you
must provide a unique address and port number combination.

Currently, QtRO does not include a \l {http://www.zeroconf.org/} {zeroconf}
facility. Therefore, all processes or devices must know beforehand, how to
connect to each other. A \l {QRemoteObjectRegistry} can be used to simplify
the connection process for a network with multiple Host Nodes.

The table below summarizes the connection types available:

    \table 90%
    \header
        \li URL
        \li Host Node
        \li Connecting Node
    \row
        \li \l {QUrl}("local:service")
        \li \l {QLocalServer}("service")
        \li \l {QLocalSocket}("service")
    \row
        \li \l {QUrl}("tcp://192.168.1.1:9999")
        \li \l {QTcpServer}("192.168.1.1",9999)
        \li \l {QTcpSocket}("192.168.1.1",9999)
    \endtable

Nodes have a few \l{QRemoteObjectHostBase::enableRemoting()}
{enableRemoting()} methods that are used to share objects on the network.
However, if the node is not a host node, an error is returned.

Other processes or  devices that want to interact with a shared object can
use one of the \l{QRemoteObjectNode::acquire()} {node's acquire()} methods,
to instantiate a replica.

*/
