QRemoteObjectNode Class | Qt Remote Objects 5.12.9

- Qt 5.12
- Qt Remote Objects
- C++ Classes
- QRemoteObjectNode
- Qt 5.12.9 Reference Documentation

# QRemoteObjectNode Class

A node on a Qt Remote Objects network. More...

Header: | #include <QRemoteObjectNode>
qmake: | QT += remoteobjects
Instantiated By: | Node
Inherits: | QObject
Inherited By: | QRemoteObjectHostBase

- List of all members, including inherited members
- Obsolete members

## Public Types

enum | ErrorCode { NoError, RegistryNotAcquired, RegistryAlreadyHosted, NodeIsNoServer, ..., ListenFailed }
typedef | RemoteObjectSchemaHandler

## Properties

- heartbeatInterval : int
- persistedStore : QRemoteObjectAbstractPersistedStore*
- registryUrl : QUrl

- 1 property inherited from QObject

## Public Functions

| QRemoteObjectNode(QObject *parent = nullptr)
| QRemoteObjectNode(const QUrl &registryAddress, QObject *parent = nullptr)
virtual | ~QRemoteObjectNode() override
ObjectType * | acquire(const QString &name = QString())
QRemoteObjectDynamicReplica * | acquireDynamic(const QString &name)
QAbstractItemModelReplica * | acquireModel(const QString &name, QtRemoteObjects::InitialAction action = QtRemoteObjects::FetchRootSize, const QVector<int> &rolesHint = {})
void | addClientSideConnection(QIODevice *ioDevice)
bool | connectToNode(const QUrl &address)
int | heartbeatInterval() const
QStringList | instances() const
QStringList | instances(const QString &typeName) const
QRemoteObjectNode::ErrorCode | lastError() const
QRemoteObjectAbstractPersistedStore * | persistedStore() const
void | registerExternalSchema(const QString &schema, QRemoteObjectNode::RemoteObjectSchemaHandler handler)
const QRemoteObjectRegistry * | registry() const
QUrl | registryUrl() const
void | setHeartbeatInterval(int interval)
virtual void | setName(const QString &name)
void | setPersistedStore(QRemoteObjectAbstractPersistedStore *persistedStore)
virtual bool | setRegistryUrl(const QUrl &registryAddress)
bool | waitForRegistry(int timeout = 30000)

- 31 public functions inherited from QObject

## Signals

void | error(QRemoteObjectNode::ErrorCode errorCode)
void | heartbeatIntervalChanged(int heartbeatInterval)
void | remoteObjectAdded(const QRemoteObjectSourceLocation &loc)
void | remoteObjectRemoved(const QRemoteObjectSourceLocation &)

- 2 signals inherited from QObject

## Static Public Members

const QMetaObject | staticMetaObject

- 9 static public members inherited from QObject

## Protected Functions

| QRemoteObjectNode(QRemoteObjectNodePrivate &, QObject *parent)

## Reimplemented Protected Functions

virtual void | timerEvent(QTimerEvent *) override

- 9 protected functions inherited from QObject

### Additional Inherited Members

- 1 public slot inherited from QObject

## Detailed Description

A node on a Qt Remote Objects network.

The QRemoteObjectNode class provides an entry point to a QtRemoteObjects network. A network can be as simple as two nodes, or an arbitrarily complex set of processes and devices.

A QRemoteObjectNode does not have a url that other nodes can connect to, and thus is able to acquire replicas only. It is not able to share source objects (only QRemoteObjectHost and QRemoteObjectRegistryHost Nodes can share).

Nodes may connect to each other directly using connectToNode, or they can use the QRemoteObjectRegistry to simplify connections.

The QRemoteObjectRegistry is a special replica available to every node that connects to the Registry Url. It knows how to connect to every QRemoteObjectSource object on the network.

See also QRemoteObjectHost and QRemoteObjectRegistryHost.

## Member Type Documentation

### enum QRemoteObjectNode::ErrorCode

This enum type specifies the various error codes associated with QRemoteObjectNode errors:

Constant | Value | Description
--- | --- | ---
`QRemoteObjectNode::NoError` | `0` | No error.
`QRemoteObjectNode::RegistryNotAcquired` | `1` | The registry could not be acquired.
`QRemoteObjectNode::RegistryAlreadyHosted` | `2` | The registry is already defined and hosting Sources.
`QRemoteObjectNode::NodeIsNoServer` | `3` | The given QRemoteObjectNode is not a host node.
`QRemoteObjectNode::ServerAlreadyCreated` | `4` | The host node has already been initialized.
`QRemoteObjectNode::UnintendedRegistryHosting` | `5` | An attempt was made to create a host QRemoteObjectNode and connect to itself as the registry.
`QRemoteObjectNode::OperationNotValidOnClientNode` | `6` | The attempted operation is not valid on a client QRemoteObjectNode.
`QRemoteObjectNode::SourceNotRegistered` | `7` | The given QRemoteObjectSource is not registered on this node.
`QRemoteObjectNode::MissingObjectName` | `8` | The given QObject does not have objectName() set.
`QRemoteObjectNode::HostUrlInvalid` | `9` | The given url has an invalid or unrecognized scheme.
`QRemoteObjectNode::ProtocolMismatch` | `10` | The client and the server have different protocol versions.
`QRemoteObjectNode::ListenFailed` | `11` | Can't listen on the specified host port.

### typedef QRemoteObjectNode::RemoteObjectSchemaHandler

Typedef for a std::function method that can take a QUrl input and is responsible for creating the communications channel between this node and the node hosting the desired Source. As some types of QIODevices (e.g., QSslSocket) require additional steps before the device is ready for use, the method is responsible for calling addClientSideConnection once the connection is fully established.

This typedef was introduced in Qt 5.12.

## Property Documentation

### heartbeatInterval : int

Heartbeat interval in ms.

The heartbeat (only helpful for socket connections) will periodically send a message to connected nodes to detect whether the connection was disrupted. Qt Remote Objects will try to reconnect automatically if it detects a dropped connection. This function can help with that detection since the client will only detect that the server is unavailable when it tries to send data.

A value of `0` (the default) will disable the heartbeat.

Access functions:

int | heartbeatInterval() const
void | setHeartbeatInterval(int interval)

Notifier signal:

void | heartbeatIntervalChanged(int heartbeatInterval)

### persistedStore : QRemoteObjectAbstractPersistedStore*

Allows setting a QRemoteObjectAbstractPersistedStore instance for the node.

Allows replica PROP members with the PERSISTED trait to save their current value when the replica is deleted and restore a stored value the next time the replica is started.

Requires a QRemoteObjectAbstractPersistedStore class implementation to control where and how persistence is handled.

This property was introduced in Qt 5.11.

Access functions:

QRemoteObjectAbstractPersistedStore * | persistedStore() const
void | setPersistedStore(QRemoteObjectAbstractPersistedStore *persistedStore)

### registryUrl : QUrl

This property holds the address of the Registry used by this node.

This is an empty QUrl if there is no registry in use.

Access functions:

QUrl | registryUrl() const
virtual bool | setRegistryUrl(const QUrl &registryAddress)

## Member Function Documentation

### QRemoteObjectNode::QRemoteObjectNode(QObject *parent = nullptr)

Default constructor for QRemoteObjectNode with the given parent. A Node constructed in this manner can not be connected to, and thus can not expose Source objects on the network. It also will not include a QRemoteObjectRegistry, unless set manually using setRegistryUrl.

See also connectToNode and setRegistryUrl.

### QRemoteObjectNode::QRemoteObjectNode(const QUrl &registryAddress, QObject *parent = nullptr)

QRemoteObjectNode connected to a {QRemoteObjectRegistry} {Registry}. A Node constructed in this manner can not be connected to, and thus can not expose Source objects on the network. Finding and connecting to other (Host) Nodes is handled by the QRemoteObjectRegistry specified by registryAddress.

See also connectToNode, setRegistryUrl, QRemoteObjectHost, and QRemoteObjectRegistryHost.

### `[protected]` QRemoteObjectNode::QRemoteObjectNode(QRemoteObjectNodePrivate &, QObject *parent)

Default constructs an instance of QRemoteObjectNode.

### `[override virtual]` QRemoteObjectNode::~QRemoteObjectNode()

Destroys the instance of QRemoteObjectNode. The destructor is virtual.

### ObjectType *QRemoteObjectNode::acquire(const QString &name = QString())

Returns a pointer to a Replica of type ObjectType (which is a template parameter and must inherit from QRemoteObjectReplica). That is, the template parameter must be a repc generated type. The name parameter can be used to specify the name given to the object during the QRemoteObjectHost::enableRemoting() call.

### QRemoteObjectDynamicReplica *QRemoteObjectNode::acquireDynamic(const QString &name)

Returns a QRemoteObjectDynamicReplica of the Source name.

### QAbstractItemModelReplica *QRemoteObjectNode::acquireModel(const QString &name, QtRemoteObjects::InitialAction action = QtRemoteObjects::FetchRootSize, const QVector<int> &rolesHint = {})

Returns a pointer to a Replica which is specifically derived from QAbstractItemModel. The name provided must match the name used with the matching enableRemoting that put the Model on the network. The returned `model` will be empty until it is initialized with the Source.

### void QRemoteObjectNode::addClientSideConnection(QIODevice *ioDevice)

In order to QRemoteObjectNode::acquire() Replica objects over External QIODevices, Qt Remote Objects needs access to the communications channel (a QIODevice) between the respective nodes. It is the addClientSideConnection() call that enables this, taking the ioDevice as input. Any acquire() call made without calling addClientSideConnection will still work, but the Node will not be able to initialize the Replica without being provided the connection to the Host node.

This function was introduced in Qt 5.12.

See also QRemoteObjectHostBase::addHostSideConnection.

### bool QRemoteObjectNode::connectToNode(const QUrl &address)

Connects a client node to the host node at address.

Connections will remain valid until the host node is deleted or no longer accessible over a network.

Once a client is connected to a host, valid Replicas can then be acquired if the corresponding Source is being remoted.

Return `true` on success, `false` otherwise (usually an unrecognized url, or connecting to already connected address).

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

### `[signal]` void QRemoteObjectNode::error(QRemoteObjectNode::ErrorCode errorCode)

### QStringList QRemoteObjectNode::instances() const

This templated function (taking a repc generated type as the template parameter) will return the list of names of every instance of that type on the Remote Objects network. For example, if you have a Shape class defined in a .rep file, and Circle and Square classes inherit from the Source definition, they can be shared on the Remote Objects network using enableRemoting.

     Square square;
     Circle circle;
     myHost.enableRemoting(&square, "Square");
     myHost.enableRemoting(&circle, "Circle");

Then instance can be used to find the available instances of Shape.

     QStringList instances = clientNode.instances<Shape>();
     // will return a QStringList containing "Circle" and "Square"
     auto instance1 = clientNode.acquire<Shape>("Circle");
     auto instance2 = clientNode.acquire<Shape>("Square");
     ...

### QStringList QRemoteObjectNode::instances(const QString &typeName) const

This function overloads instances().

This convenience function provides the same result as the templated version, but takes the name of the Source class as a parameter (typeName) rather than deriving it from the class type.

### QRemoteObjectNode::ErrorCode QRemoteObjectNode::lastError() const

Returns the last error set.

### void QRemoteObjectNode::registerExternalSchema(const QString &schema, QRemoteObjectNode::RemoteObjectSchemaHandler handler)

Provide a custom method to handle externally provided schemas

This method is tied to the Registry and External Schemas. By registering a std::function handler for an external schema, the registered method will be called when the registry is notified of a Source you've acquired being available. Without this registration, QtRO would only be able to handle the "built-in" schemas.

The provided method, handler, will be called when the registry sees a Source object on a new (not yet connected) Node with a {QUrl::schema()} of schema. The handler, of type QRemoteObjectNode::RemoteObjectSchemaHandler will get the QUrl of the Node providing the Source as an input parameter, and is responsible for establishing the communications channel (a QIODevice of some sort) and calling addClientSideConnection with it.

This function was introduced in Qt 5.12.

See also RemoteObjectSchemaHandler.

### const QRemoteObjectRegistry *QRemoteObjectNode::registry() const

Returns a pointer to the Node's QRemoteObjectRegistry, if the Node is using the Registry feature; otherwise it returns 0.

### `[signal]` void QRemoteObjectNode::remoteObjectAdded(const QRemoteObjectSourceLocation &loc)

This signal is emitted whenever a new Source object is added to the Registry. The signal will not be emitted if there is no Registry set (i.e., Sources over connections made via connectToNode directly). The loc parameter contains the information about the added Source, including name, type and the QUrl of the hosting Node.

See also remoteObjectRemoved and instances.

### `[signal]` void QRemoteObjectNode::remoteObjectRemoved(const QRemoteObjectSourceLocation &)

### `[virtual]` void QRemoteObjectNode::setName(const QString &name)

Sets name as the internal name for this Node. This is then output as part of the logging (if enabled). This is primarily useful if you merge log data from multiple nodes.

### `[override virtual protected]` void QRemoteObjectNode::timerEvent(QTimerEvent *)

Reimplemented from QObject::timerEvent().

### bool QRemoteObjectNode::waitForRegistry(int timeout = 30000)

Blocks until this Node's Registry is initialized or timeout (in milliseconds) expires. Returns `true` if the Registry is successfully initialized upon return, or `false` otherwise.