QRemoteObjectHostBase Class

Member Function Documentation

[since 5.12] void QRemoteObjectHostBase::addHostSideConnection(QIODevice *ioDevice)

In order to QRemoteObjectHost::enableRemoting() Source objects over External QIODevices, Qt Remote Objects needs access to the communications channel (a QIODevice) between the respective nodes. It is the addHostSideConnection() call that enables this on the Source side, taking the ioDevice as input. Any enableRemoting() call will still work without calling addHostSideConnection, but the Node will not be able to share the Source objects without being provided the connection to the Replica node. Before calling this function you must call setHostUrl() with a unique URL and AllowExternalRegistration.

This function was introduced in Qt 5.12.

See also addClientSideConnection.

[invokable] bool QRemoteObjectHostBase::disableRemoting(QObject *remoteObject)

Disables remote access for the QObject remoteObject. Returns false if the current node is a client node or if the remoteObject is not registered, and returns true if remoting is successfully disabled for the Source object.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also enableRemoting().

template <template <typename> class ApiDefinition, typename ObjectType> bool QRemoteObjectHostBase::enableRemoting(ObjectType *object)

This templated function overload enables a host node to provide remote access to a QObject object with a specified (and compile-time checked) interface. Client nodes connected to the node hosting this object may obtain Replicas of this Source.

This is best illustrated by example:

#include "rep_TimeModel_source.h"
MinuteTimer timer;
hostNode.enableRemoting<MinuteTimerSourceAPI>(&timer);

Here the MinuteTimerSourceAPI is the set of Signals/Slots/Properties defined by the TimeModel.rep file. Compile time checks are made to verify the input QObject can expose the requested API, it will fail to compile otherwise. This allows a subset of object 's interface to be exposed, and allows the types of conversions supported by Signal/Slot connections.

Returns false if the current node is a client node, or if the QObject is already registered to be remoted, and true if remoting is successfully enabled for the QObject.

See also disableRemoting().

[invokable] bool QRemoteObjectHostBase::enableRemoting(QObject *object, const QString &name = QString())

Enables a host node to dynamically provide remote access to the QObject object. Client nodes connected to the node hosting this object may obtain Replicas of this Source.

The optional name defines the lookup-name under which the QObject can be acquired using QRemoteObjectNode::acquire() . If not explicitly set then the name given in the QCLASSINFO_REMOTEOBJECT_TYPE will be used. If no such macro was defined for the QObject then the QObject::objectName() is used.

Returns false if the current node is a client node, or if the QObject is already registered to be remoted, and true if remoting is successfully enabled for the dynamic QObject.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also disableRemoting().

bool QRemoteObjectHostBase::enableRemoting(QAbstractItemModel *model, const QString &name, const QList<int> roles, QItemSelectionModel *selectionModel = nullptr)

This overload of enableRemoting() is specific to QAbstractItemModel types (or any type derived from QAbstractItemModel). This is useful if you want to have a model and the HMI for the model in different processes.

The three required parameters are the model itself, the name by which to lookup the model, and the roles that should be exposed on the Replica side. If you want to synchronize selection between Source and Replica, the optional selectionModel parameter can be used. This is only recommended when using a single Replica.

Behind the scenes, Qt Remote Objects batches data() lookups and prefetches data when possible to make the model interaction as responsive as possible.

Returns false if the current node is a client node, or if the QObject is already registered to be remoted, and true if remoting is successfully enabled for the QAbstractItemModel.

See also disableRemoting().

[since 5.11] bool QRemoteObjectHostBase::proxy(const QUrl &registryUrl, const QUrl &hostUrl = {}, QRemoteObjectHostBase::RemoteObjectNameFilter filter = [](QStringView, QStringView) {return true; })

Forward Remote Objects from another network

The proxy functionality is useful when you want to share Source objects over multiple networks. For instance, if you have an embedded target using target-only connections (like local) and you want to make some of those same objects available externally.

As a concrete example, say you have a set of processes talking to each other on your target hardware using a registry, with the Registry at "local:registry" and separate processes using a node at "local:MyHost" that holds Source objects. If you wanted to access these objects, but over tcp, you could create a new proxyNode like so:

// myInternalHost is a node only visible on the device...
QRemoteObjectHost myInternalHost("local:MyHost");
myInternalHost.enableRemoting<SomeObject>(&someObject);

// Regular host node, listening on port 12123, so visible to other
// devices
QRemoteObjectHost proxyNode("tcp://localhost:12123");

// Enable proxying objects from nodes on the local machine's internal
// QtRO bus
proxyNode.proxy("local:registry");

And from another device you create another node:

// NB: localhost resolves to a different ip address than proxyNode
QRemoteObjectHost nodeOnRemoteDevice("tcp://localhost:23234");

// Connect to the target's proxyNode directly, or use a tcp registry...
nodeOnRemoteDevice.connectToNode("tcp://<target device>:12123");

// Because of the proxy, we can get the object over tcp/ip port 12123,
// even though we can't connect directly to "local:MyHost"
SomeObject *so = nodeOnRemoteDevice.acquire<SomeObject>();

This would (internally) create a node in proxyNode, which (again internally/automatically) connects to the provided registry (given by the registryUrl parameter, "local:registry" in this example). Whenever local:registry emits the remoteObjectAdded signal, the QRemoteObjectSourceLocation is passed to the filter given to the proxy call. If this method returns true (the default filter simply returns true without any filtering), the object is acquired() from the internal node and enableRemoting() (once the replica is initialized) is called on proxyNode.

If a hostUrl is provided (which is required to enable reverseProxy, but not needed otherwise), the internal node will be a QRemoteObjectHost node configured with the provided address. If no hostUrl is provided, the internal node will be a QRemoteObjectNode (not HostNode).

Returns true if the object is acquired from the internal node.

This function was introduced in Qt 5.11.

See also reverseProxy().

[since 5.11] bool QRemoteObjectHostBase::reverseProxy(QRemoteObjectHostBase::RemoteObjectNameFilter filter = [](QStringView, QStringView) {return true; })

Forwards remote objects to another network.

The reverseProxy() function allows the proxy() functionality to be extended, in effect mirroring the proxy functionality in the "reverse" direction. These are distinct, because node communication is not symmetric, one side calls enableRemoting() with a Source object, the other side calls acquire() to get a Replica. Using proxy() allows you to "observe" objects on a target device remotely via acquire, but it does not allow off-target Source objects to be acquired from the device's local:* network. That is where reverseProxy() comes in. If a proxyNode is created like so:

// myInternalHost is a node only visible on the device...
QRemoteObjectHost myInternalHost("local:MyHost", "local:registry");

// RegistryHost node, listening on port 12123, so visible to other
// devices.  The node must be a RegistryHost, so the Sources on
// the "outside" network can be forwarded to the inner network.
QRemoteObjectRegistryHost proxyNode("tcp://0.0.0.0:12123");

// Enable proxying objects from nodes on the local machine's internal
// QtRO bus.  Note the hostUrl parameter is now needed.
proxyNode.proxy("local:registry", "local:fromProxy");
proxyNode.reverseProxy();

And from another device you create another node:

// Listen on a local port, and connect to "proxyNode" as the registry.
// NB: localhost resolves to a different ip address than proxyNode
QRemoteObjectHost nodeOnRemoteDevice("tcp://localhost:23234",
                                     "tcp://<target device>:12123");

// Because of the reverseProxy, we can expose objects on this device
// and they will make their way to proxyNode...
nodeOnRemoteDevice.enableRemoting<OtherObject>(&otherObject);

// Acquire() can now see the objects on other devices through proxyNode,
// due to the reverseProxy call.
OtherObject *oo = myInternalHost.acquire<OtherObject>();

While the proxy() functionality allows Source objects on another network to be acquired(), reverseProxy() allows Source objects to be "pushed" to an otherwise inaccessible network.

Returns true on success, false otherwise.

This function was introduced in Qt 5.11.

See also proxy().

[override virtual] void QRemoteObjectHostBase::setName(const QString &name)

Reimplements: QRemoteObjectNode::setName(const QString &name).

Similar to QObject::setObjectName() (which this method calls), but this version also applies the name to internal classes as well, which are used in some of the debugging output.