QRemoteObjectReplica Class

A class interacting with (but not implementing) a Qt API on the Remote Object network. More...

Header: #include <QRemoteObjectReplica>
CMake: find_package(Qt6 REQUIRED COMPONENTS RemoteObjects)
target_link_libraries(mytarget PRIVATE Qt6::RemoteObjects)
qmake: QT += remoteobjects
Inherits: QObject
Inherited By:

QRemoteObjectDynamicReplica and QRemoteObjectRegistry

Public Types

enum State { Uninitialized, Default, Valid, Suspect, SignatureMismatch }


  • node : QRemoteObjectNode*
  • state : const State

Public Functions

bool isInitialized() const
bool isReplicaValid() const
QRemoteObjectNode *node() const
virtual void setNode(QRemoteObjectNode *node)
QRemoteObjectReplica::State state() const
bool waitForSource(int timeout = 30000)


void initialized()
void notified()
void stateChanged(QRemoteObjectReplica::State state, QRemoteObjectReplica::State oldState)

Detailed Description

A Remote Object Replica is a QObject proxy for another QObject (called the Source object). Once initialized, a replica can be considered a "latent copy" of the Source object. That is, every change to a Q_PROPERTY on the Source, or signal emitted by the Source will be updated/emitted by all Replica objects. Latency is introduced by process scheduling by any OSes involved and network communication latency. As long as the replica has been initialized and the communication is not disrupted, receipt and order of changes is guaranteed.

The isInitialized and state properties (and corresponding initialized()/stateChanged() signals) allow the state of a Replica to be determined.

While Qt Remote Objects (QtRO) handles the initialization and synchronization of Replica objects, there are numerous steps happening behind the scenes which can fail and that aren't encountered in single process Qt applications. See Troubleshooting for advice on how to handle such issues when using a remote objects network.

Member Type Documentation

enum QRemoteObjectReplica::State

This enum type specifies the various state codes associated with QRemoteObjectReplica states:

QRemoteObjectReplica::Uninitialized0Initial value of DynamicReplica, where nothing is known about the replica before connection to source.
QRemoteObjectReplica::Default1Initial value of static replica, where any defaults set in the .rep file are available so it can be used if necessary.
QRemoteObjectReplica::Valid2Indicates the replica is connected, has good property values and can be interacted with.
QRemoteObjectReplica::Suspect3Error state that occurs if the connection to the source is lost after it is initialized.
QRemoteObjectReplica::SignatureMismatch4Error state that occurs if a connection to the source is made, but the source and replica are not derived from the same .rep (only possible for static Replicas).

Property Documentation

node : QRemoteObjectNode*

This property holds a pointer to the node this object was acquired from.

Access functions:

QRemoteObjectNode *node() const
virtual void setNode(QRemoteObjectNode *node)

[read-only] state : const State

Returns the replica state.

This property holds the replica QRemoteObjectReplica::State.

Access functions:

QRemoteObjectReplica::State state() const

Notifier signal:

void stateChanged(QRemoteObjectReplica::State state, QRemoteObjectReplica::State oldState)

Member Function Documentation

[signal] void QRemoteObjectReplica::initialized()

This signal is emitted once the replica is initialized. An intialized replica has all property values set, but has not yet emitted any property change notifications.

See also isInitialized() and stateChanged().

bool QRemoteObjectReplica::isInitialized() const

Returns true if this replica has been initialized with data from the Source object. Returns false otherwise.

See also state().

bool QRemoteObjectReplica::isReplicaValid() const

Returns true if this replica has been initialized and has a valid connection with the node hosting the Source. Returns false otherwise.

See also isInitialized().

[signal] void QRemoteObjectReplica::notified()

This signal is emitted once the replica is initialized and all property change notifications have been emitted.

It is sometimes useful to respond to property changes as events. For example, you might want to display a user notification when a certain property change occurs. However, this user notification would then also be triggered when a replica first became QRemoteObjectReplica::Valid, as all property change signals are emitted at that time. This isn't always desirable, and notified allows the developer to distinguish between these two cases.

QRemoteObjectReplica::State QRemoteObjectReplica::state() const

Returns the current state of the replica.

Note: Getter function for property state.

See also isInitialized.

[signal] void QRemoteObjectReplica::stateChanged(QRemoteObjectReplica::State state, QRemoteObjectReplica::State oldState)

This signal is emitted whenever a replica's state toggles between QRemoteObjectReplica::State.

The change in state is represented with state and oldState.

Note: Notifier signal for property state.

See also state() and initialized().

bool QRemoteObjectReplica::waitForSource(int timeout = 30000)

Blocking call that waits for the replica to become initialized or until the timeout (in ms) expires. Returns true if the replica is initialized when the call completes, false otherwise.

If timeout is -1, this function will not time out.

See also isInitialized() and initialized().

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.