Revision control
Copy as Markdown
// Copyright (C) 2018 Ford Motor Company
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\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.
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 Notes
\row
\li {QUrl}("local:service")
\li Uses (internally) {QLocalServer}/{QLocalSocket} classes to
communicate between nodes.
\row
\li Uses (internally) {QTcpServer}/{QTcpSocket} classes to
communicate between nodes.
\row
\li {QUrl}("qnx:service")
\li QNX OS only. Uses a custom (named) channel for native
communication between nodes.
\row
\li {QUrl}("localabstract:service")
\li Since 6.2. Linux/Android OSes only. Uses an abstract namespace
for Unix domain sockets. This allows QLocalSocket behavior to work on
non-writable devices.
\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.
*/