class DCOPRef

A DCOPRef(erence) encapsulates a remote DCOP object as a triple where type is optional. More...

List of all Methods
Definition	`#include <dcopref.h>`

Annotated List

Files

Globals

Hierarchy

Index

Public Methods

DCOPRef ()
DCOPRef ( const DCOPRef& ref )
DCOPRef ( const QCString& app, const QCString& obj = "" )
DCOPRef ( DCOPObject *object )
DCOPRef ( const QCString& app, const QCString& obj, const QCString& type )
bool isNull () const
QCString app () const
QCString obj () const
QCString object () const
QCString type () const
DCOPRef& operator= ( const DCOPRef& )
void setRef ( const QCString& app, const QCString& obj = "" )
void setRef ( const QCString& app, const QCString& obj, const QCString& type )
void clear ()
DCOPClient* dcopClient () const
void setDCOPClient ( DCOPClient *client )
DCOPReply call ( const QCString& fun )
template DCOPReply call ( const QCString& fun, const T1& t1 )
template DCOPReply call ( const QCString& fun, const T1& t1, const T2& t2 )
template DCOPReply call ( const QCString& fun, const T1& t1, const T2& t2, const T3& t3 )
template DCOPReply call ( const QCString& fun, const T1& t1, const T2& t2, const T3& t3, const T4& t4 )
template DCOPReply call ( const QCString& fun, const T1& t1, const T2& t2, const T3& t3, const T4& t4, const T5& t5 )
template DCOPReply call ( const QCString& fun, const T1& t1, const T2& t2, const T3& t3, const T4& t4, const T5& t5, const T6& t6 )
template DCOPReply call ( const QCString& fun, const T1& t1, const T2& t2, const T3& t3, const T4& t4, const T5& t5, const T6& t6, const T7& t7 )
template DCOPReply call ( const QCString& fun, const T1& t1, const T2& t2, const T3& t3, const T4& t4, const T5& t5, const T6& t6, const T7& t7, const T8& t8 )
bool send ( const QCString& fun )
template bool send ( const QCString& fun, const T1& t1 )
template bool send ( const QCString& fun, const T1& t1, const T2& t2 )
template bool send ( const QCString& fun, const T1& t1, const T2& t2, const T3& t3 )
template bool send ( const QCString& fun, const T1& t1, const T2& t2, const T3& t3, const T4& t4 )
template bool send ( const QCString& fun, const T1& t1, const T2& t2, const T3& t3, const T4& t4, const T5& t5 )
template bool send ( const QCString& fun, const T1& t1, const T2& t2, const T3& t3, const T4& t4, const T5& t5, const T6& t6 )
template bool send ( const QCString& fun, const T1& t1, const T2& t2, const T3& t3, const T4& t4, const T5& t5, const T6& t6, const T7& t7 )
template bool send ( const QCString& fun, const T1& t1, const T2& t2, const T3& t3, const T4& t4, const T5& t5, const T6& t6, const T7& t7, const T8& t8 )

Detailed Description

A DCOPRef(erence) encapsulates a remote DCOP object as a triple where type is optional. It allows for calling and passing DCOP objects.

A DCOP reference makes it possible to return references to other DCOP objects in a DCOP interface, for example in the method giveMeAnotherObject() in an interface like this:


	class Example : public DCOPObject
	{
	   K_DCOP
	...
	k_dcop:
	   DCOPRef giveMeAnotherObject();
	   int doSomething( QString, float, bool );
	   ASYNC pingMe( QCString message );
	   UserType userFunction( UserType );
	};

In addition, the reference can operate as a comfortable generic stub to call remote DCOP objects in cases where no DCOPStub is available. The advantage of using DCOPRef instead of the low-level functions DCOPClient::call() and DCOPClient::send() are the nicer syntax and the implicit runtime error checking.

Say you want to call the method "doSomething" from the above interface on an object called "example" that lives in application "foo". Using DCOPRef, you would write


	DCOPRef example( "foo", "example" );
	int result = example.call( "doSomething", "Hello World", (float)2.5, true );

If it is important for you to know whether the call succeeded or not, you can use the slightly more elaborate pattern:


	DCOPRef example( "foo", "example" );
	DCOPReply reply = example.call( "doSomething", "Hello World", (float)2.5, true );
	if ( reply.isValid() ) {
	    int result = reply;
	    // ...
	}

For curiosity, here is how you would achieve the exactly same functionality by using DCOPClient::call() directly:


    QByteArray data, replyData;
    QCString replyType;
    QDataStream arg( data, IO_WriteOnly );
    arg << QString("hello world" ), (float) 2.5 << true;
    if ( DCOPClient::mainClient()->call( app, obj,
			     "doSomething(QString,float,bool)",
			     data, replyType, replyData ) ) {
	if ( replyType == "int" ) {
	    int result;
	    QDataStream reply( replyData, IO_ReadOnly );
	    reply >> result;
	    // ...
	}
    }

As you might see from the code snippet, the DCOPRef has to "guess" the names of the datatypes of the arguments to construct a dcop call. This is done through global inline overloads of the dcopTypeName function, for example


	inline const char* dcopTypeName( const QString& ) { return "QString"; }

If you use custom data types that do support QDataStream but have no corrsponding dcopTypeName overload, you can either provide such an overload or use a DCOPArg wrapper that allows you to specify the type.


	UserType userType;
	DCOPReply reply = example.call( "userFunction", DCOPArg( userType, "UserType" ) );

Similar, when you retrieve such a data type, you can use an explicit call to DCOPReply::get():


	UserType userType;
	reply.get( userType, "UserType" );

The function send() works very similar to call(), only that it returns a simple bool on whether the signal could be sent or not:


	if ( example.pingMe( "message" ) == false )
	   qWarning("could not ping example" );

A DCOP reference operates on DCOPClient::mainClient(), unless you explicitely specify another client with setDCOPClient().

See also: DCOPArg, DCOPReply, DCOPObject

DCOPRef ()

DCOPRef

Creates a null reference.

DCOPRef ( const DCOPRef& ref )

DCOPRef

Copy constructor.

DCOPRef ( const QCString& app, const QCString& obj = "" )

DCOPRef

Creates a reference for application app and object obj

Parameters:

app The name of an application as registered by the dcopserver.

obj The name of the dcop object.

DCOPRef ( DCOPObject *object )

DCOPRef

Creates a reference to an existing dcop object

Parameters:

object The dcop object to create the ref to.

DCOPRef ( const QCString& app, const QCString& obj, const QCString& type )

DCOPRef

Creates a reference for application app and object obj with a specified type type.

Parameters:

app The name of an application as registered by the dcopserver.

obj The name of the dcop object

type The object's type

bool isNull ()

isNull

[const]

Tests wether it is a null reference.

Returns: true if this object is a null reference

QCString app ()

app

[const]

Name of the application in which the object resides.

Returns: the application's id. Can be null or empty if not set.

QCString obj ()

obj

[const]

Object ID of the referenced object.

Returns: the id of the referenced object. Can be null or empty if not set.

QCString object ()

object

[const]

@obsolete

QCString type ()

type

[const]

Type of the referenced object. May be null (i.e. unknown).

Returns: the type of the referenced object, or null if unknown

DCOPRef& operator= ( const DCOPRef& )

operator=

Assignment operator. Copies the references data.

void setRef ( const QCString& app, const QCString& obj = "" )

setRef

Changes the referenced object. Resets the type to unknown (null).

Parameters:

app the application id.

obj the object id

void setRef ( const QCString& app, const QCString& obj, const QCString& type )

setRef

Changes the referenced object.

Parameters:

app the application id.

obj the object id

tyoe the object's type

void clear ()

clear

Makes this a null reference.

DCOPClient* dcopClient ()

dcopClient

[const]

Returns the dcop client the reference operates on. If no client has been set, this is the DCOPClient::mainClient().

Returns: the DCOPClient of this object

void setDCOPClient ( DCOPClient *client )

setDCOPClient

Sets a specific dcop client for this reference. Otherwise DCOPClient::mainClient() is used.

Parameters:

client the new DCOPClient of this object

DCOPReply call ( const QCString& fun )