GCF::IpcRemoteObject Class Reference

This class allows you to maintain a persistent connection with a remote object. More...

#include <GCF3/IpcRemoteObject>

Signals
void	activated ()
void	deactivated ()
void	signalOccurance (const QString &signal, const QVariantList &args)
void	propertyUpdated (const QString &propertyName, const QVariant &value)
void	couldNotActivate (const QString &error)
void	error (const QString &error)

Public Member Functions
	IpcRemoteObject (const QHostAddress &addr, quint16 port, const QString &object, QObject *parent=0)
	~IpcRemoteObject ()
bool	isActivated () const
void	reactivate ()
QHostAddress	remoteAddress () const
quint16	remotePort () const
QString	remoteObjectPath () const
QVariantMap	properties () const
QStringList	signalMethods () const
QStringList	invokableMethods () const
GCF::Result	updateProperty (const QString &propertyName, QObject *receiver=0, const char *member=0)
GCF::Result	changeProperty (const QString &propertyName, const QVariant &propertyValue, QObject *receiver=0, const char *member=0)
GCF::Result	call (const QString &method, const QVariantList &args, QObject *receiver=0, const char *member=0)

Detailed Description

Once an instance of this class is created to connect to a remote object, it sends an activation request. Upon activation(); the object maintains a persistent connection with the remote object. If the remote application shuts down, or the remote object was deleted or otherwise goes out of communication, the deactivated() signal is emitted.

The following code snippet shows you how to create an instance of GCF::IpcRemoteObject and prepare to use it.

GCF::IpcRemoteObject *remoteObj = new GCF::IpcRemoteObject(addr, port, "Application.MyService");

// Wait for the object to get activated
GCF::SignalSpy spy(remoteObj, SIGNAL(activated()));
spy.wait();

if( remoteObj->isActivated() ) {
    // Connection to the remote object is now activated
}

You can make use of the GCF::ipcConnect() methods to make signal/slot connections between a local object and remote object. Example:

GCF::IpcRemoteObject *remoteApp = new GCF::IpcRemoteObject(addr, port, "Application");

// Wait for the object to get activated
GCF::SignalSpy spy(remoteApp, SIGNAL(activated()));
spy.wait();

// When a local button is clicked, we want the remoteApp to quit.
QPushButton *quitButton = ...;
GCF::ipcConnect(quitButton, SIGNAL(clicked()), remoteAll, SLOT(quit()));

Constructor & Destructor Documentation

GCF::IpcRemoteObject::IpcRemoteObject	(	const QHostAddress &	addr,
		quint16	port,
		const QString &	object,
		QObject *	parent = 0
	)

Constructor.

Parameters

addr	address of the computer on which the remote application is running
port	port number of the GCF::IpcServer in the remote application
object	name of the remote object
parent	pointer to the parent QObject of this class

Sometime after the constructor returns the activated() signal is emitted upon successful activation. The coundNotActivate() signal is emitted with an error message describing the reason for failure.

GCF::IpcRemoteObject::~IpcRemoteObject

(

)

Destructor

Member Function Documentation

bool GCF::IpcRemoteObject::isActivated

(

)

const

Returns

true if this class has been activated. False otherwise.

void GCF::IpcRemoteObject::reactivate

(

)

If this class was activated once and then got deactivated for whatever reason, you can call this method to request a reactivation.

QHostAddress GCF::IpcRemoteObject::remoteAddress

(

)

const

Returns

address of the computer on which the remote application is running

quint16 GCF::IpcRemoteObject::remotePort

(

)

const

Returns

port number of the GCF::IpcServer on the remote application

QString GCF::IpcRemoteObject::remoteObjectPath

(

)

const

Returns

path of the object in the remote application's object tree

QVariantMap GCF::IpcRemoteObject::properties

(

)

const

Returns

A map of all properties and their values in the remote application.

Note

this function returns an empty map until isActivated() returns false.

QStringList GCF::IpcRemoteObject::signalMethods

(

)

const

Returns

a list of signal method signatures in the remote object

Note

this function returns an empty list until isActivated() returns false.

QStringList GCF::IpcRemoteObject::invokableMethods

(

)

const

Returns

a list of invokable (signal, public slots and Q_INVOKABLE) method signatures in the remote object

Note

this function returns an empty list until isActivated() returns false.

GCF::Result GCF::IpcRemoteObject::updateProperty	(	const QString &	propertyName,
		QObject *	receiver = 0,
		const char *	member = 0
	)

Sends a request to update the value of propertyName in the local properties() map. The function returns true if the update request was queued successfully, false with error message otherwise.

The receiver and member parameters can be used to specify a object and its method that should get invoked when the result of sending the update property request becomes available. The member should be a function that accepts QVariant, bool and QString parameters.

Parameters

propertyName	name of the property to update
receiver	pointer to the QObject that will get notified when the result of update property request becomes available
member	a member function in receiver that will get called when the result becomes available. This parameter must be constructed using SIGNAL or SLOT macros.

Returns

true upon success. false and error message upon failure.

See Also

propertyUpdated()

GCF::Result GCF::IpcRemoteObject::changeProperty	(	const QString &	propertyName,
		const QVariant &	propertyValue,
		QObject *	receiver = 0,
		const char *	member = 0
	)

Sends a request to change the value of propertyName to propertyValue. The function returns true if the update request was queued successfully, false with error message otherwise.

The receiver and member parameters can be used to specify a object and its method that should get invoked when the result of sending the change property request becomes available. The member should be a function that accepts QVariant, bool and QString parameters.

Parameters

propertyName	name of the property in the remote object to change
propertyValue	new value of the property to be set on the remote obkect
receiver	pointer to the QObject that will get notified when the result of change property request becomes available
member	a member function in receiver that will get called when the result becomes available. This parameter must be constructed using SIGNAL or SLOT macros.

Returns

true upon success. false and error message upon failure.

See Also

propertyUpdated()

GCF::Result GCF::IpcRemoteObject::call	(	const QString &	method,
		const QVariantList &	args,
		QObject *	receiver = 0,
		const char *	member = 0
	)

Places a asynchronous call to a method on the remote object with args. When the result of the method invocation becomes available notification is sent to the member function on receiver.

Parameters

method	name of the remote method to invoke
args	arguments to be passed to the remote method
receiver	pointer to the receiver QObject that will be notified when the result of method invocation becomes available
member	a member function in receiver that will get called when the result becomes available. This parameter must be constructed using SIGNAL or SLOT macros. This member function must accept a QVariant, bool and QString parameter.

Returns

true upon successfully placing the call. False + error message upon failure.

void GCF::IpcRemoteObject::activated ( )

signal

This signal is emitted when this class becomes activated. GCF::IpcRemoteObject is considered activated when it was able to establish communication with a remote object successfuly and receive properties(), signalMethods() and invokableMethods() data.

void GCF::IpcRemoteObject::deactivated ( )

signal

This signal is emitted when connection with a remote object is lost. After this signal is emitted properties(), signalMethods() and invokableMethods() return empty maps and lists.

void GCF::IpcRemoteObject::signalOccurance ( const QString &  signal, const QVariantList &  args  )

signal

This signal is emitted when a signal by name signal was emitted in the remote object. args contains the parameters emitted in the remote signal.

void GCF::IpcRemoteObject::propertyUpdated ( const QString &  propertyName, const QVariant &  value  )

signal

This signal is emitted when the value of propertyName was updated to value in properties(). This happens only upon explicit calls to changeProperty() or updateProperty()

void GCF::IpcRemoteObject::couldNotActivate ( const QString &  error )

signal

This signal is emitted when this class could not be activated. The error parameter describes the reason for failure.

void GCF::IpcRemoteObject::error ( const QString &  error )

signal

This signal is emitted whenever any error is encountered in communicating with the remote object.