class DCOPRef

# class DCOPRef | A DCOPRef(erence) encapsulates a remote DCOP object as a triple where type is optional. More...
Definition | `#include <dcopref.h>`
List of all Methods
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 ) | ### call

Calls the function `fun` on the object referenced by this reference.

Parameters:

fun | the name of the DCOP function. This can be either the full function signature (e.g. "setName(QString)") or only the function's name (e.g. "setName"). In the latter case the exact signature will be guessed from the arguments

Returns: the DCOPReply object. Is invalid (DCOPReply::isValid()) when an error occurred.

See also: DCOPArg, DCOPArg

template DCOPReply call ( const QCString& fun, const T1& t1 ) | ### call

Calls the function `fun` on the object referenced by this reference.

Parameters:

fun | the name of the DCOP function. This can be either the full function signature (e.g. "setName(QString)") or only the function's name (e.g. "setName"). In the latter case the exact signature will be guessed from the arguments
t1 | the first argument of the function. This can be a supported base type or a DCOPArg object.

Returns: the DCOPReply object. Is invalid (DCOPReply::isValid()) when an error occurred.

See also: DCOPArg, DCOPArg

template DCOPReply call ( const QCString& fun, const T1& t1, const T2& t2 ) | ### call

Calls the function `fun` on the object referenced by this reference.

Parameters:

fun | the name of the DCOP function. This can be either the full function signature (e.g. "setName(QString)") or only the function's name (e.g. "setName"). In the latter case the exact signature will be guessed from the arguments
t1 | the first argument of the function. This can be a supported base type or a DCOPArg object.
t2 | the second argument of the function. This can be a supported base type or a DCOPArg object.

Returns: the DCOPReply object. Is invalid (DCOPReply::isValid()) when an error occurred.

See also: DCOPArg, DCOPArg

template DCOPReply call ( const QCString& fun, const T1& t1, const T2& t2, const T3& t3 ) | ### call

Calls the function `fun` on the object referenced by this reference.

Parameters:

fun | the name of the DCOP function. This can be either the full function signature (e.g. "setName(QString)") or only the function's name (e.g. "setName"). In the latter case the exact signature will be guessed from the arguments
t1 | the first argument of the function. This can be a supported base type or a DCOPArg object.
t2 | the second argument of the function. This can be a supported base type or a DCOPArg object.
t3 | the third argument of the function. This can be a supported base type or a DCOPArg object.

Returns: the DCOPReply object. Is invalid (DCOPReply::isValid()) when an error occurred.

See also: DCOPArg, DCOPArg

template DCOPReply call ( const QCString& fun, const T1& t1, const T2& t2, const T3& t3, const T4& t4 ) | ### call

Calls the function `fun` on the object referenced by this reference.

Parameters:

fun | the name of the DCOP function. This can be either the full function signature (e.g. "setName(QString)") or only the function's name (e.g. "setName"). In the latter case the exact signature will be guessed from the arguments
t1 | the first argument of the function. This can be a supported base type or a DCOPArg object.
t2 | the second argument of the function. This can be a supported base type or a DCOPArg object.
t3 | the third argument of the function. This can be a supported base type or a DCOPArg object.
t4 | the fourth argument of the function. This can be a supported base type or a DCOPArg object.

Returns: the DCOPReply object. Is invalid (DCOPReply::isValid()) when an error occurred.

See also: DCOPArg, DCOPArg

template DCOPReply call ( const QCString& fun, const T1& t1, const T2& t2, const T3& t3, const T4& t4, const T5& t5 ) | ### call

Calls the function `fun` on the object referenced by this reference.

Parameters:

fun | the name of the DCOP function. This can be either the full function signature (e.g. "setName(QString)") or only the function's name (e.g. "setName"). In the latter case the exact signature will be guessed from the arguments
t1 | the first argument of the function. This can be a supported base type or a DCOPArg object.
t2 | the second argument of the function. This can be a supported base type or a DCOPArg object.
t3 | the third argument of the function. This can be a supported base type or a DCOPArg object.
t4 | the fourth argument of the function. This can be a supported base type or a DCOPArg object.
t5 | the fifth argument of the function. This can be a supported base type or a DCOPArg object.

Returns: the DCOPReply object. Is invalid (DCOPReply::isValid()) when an error occurred.

See also: DCOPArg, DCOPArg

template DCOPReply call ( const QCString& fun, const T1& t1, const T2& t2, const T3& t3, const T4& t4, const T5& t5, const T6& t6 ) | ### call

Calls the function `fun` on the object referenced by this reference.

Parameters:

fun | the name of the DCOP function. This can be either the full function signature (e.g. "setName(QString)") or only the function's name (e.g. "setName"). In the latter case the exact signature will be guessed from the arguments
t1 | the first argument of the function. This can be a supported base type or a DCOPArg object.
t2 | the second argument of the function. This can be a supported base type or a DCOPArg object.
t3 | the third argument of the function. This can be a supported base type or a DCOPArg object.
t4 | the fourth argument of the function. This can be a supported base type or a DCOPArg object.
t5 | the fifth argument of the function. This can be a supported base type or a DCOPArg object.
t6 | the sixth argument of the function. This can be a supported base type or a DCOPArg object.

Returns: the DCOPReply object. Is invalid (DCOPReply::isValid()) when an error occurred.

See also: DCOPArg, DCOPArg

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 ) | ### call

Calls the function `fun` on the object referenced by this reference.

Parameters:

fun | the name of the DCOP function. This can be either the full function signature (e.g. "setName(QString)") or only the function's name (e.g. "setName"). In the latter case the exact signature will be guessed from the arguments
t1 | the first argument of the function. This can be a supported base type or a DCOPArg object.
t2 | the second argument of the function. This can be a supported base type or a DCOPArg object.
t3 | the third argument of the function. This can be a supported base type or a DCOPArg object.
t4 | the fourth argument of the function. This can be a supported base type or a DCOPArg object.
t5 | the fifth argument of the function. This can be a supported base type or a DCOPArg object.
t6 | the sixth argument of the function. This can be a supported base type or a DCOPArg object.
t7 | the seventh argument of the function. This can be a supported base type or a DCOPArg object.

Returns: the DCOPReply object. Is invalid (DCOPReply::isValid()) when an error occurred.

See also: DCOPArg, DCOPArg

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 ) | ### call

Calls the function `fun` on the object referenced by this reference.

Parameters:

fun | the name of the DCOP function. This can be either the full function signature (e.g. "setName(QString)") or only the function's name (e.g. "setName"). In the latter case the exact signature will be guessed from the arguments
t1 | the first argument of the function. This can be a supported base type or a DCOPArg object.
t2 | the second argument of the function. This can be a supported base type or a DCOPArg object.
t3 | the third argument of the function. This can be a supported base type or a DCOPArg object.
t4 | the fourth argument of the function. This can be a supported base type or a DCOPArg object.
t5 | the fifth argument of the function. This can be a supported base type or a DCOPArg object.
t6 | the sixth argument of the function. This can be a supported base type or a DCOPArg object.
t7 | the seventh argument of the function. This can be a supported base type or a DCOPArg object.
t8 | the eigth argument of the function. This can be a supported base type or a DCOPArg object.

Returns: the DCOPReply object. Is invalid (DCOPReply::isValid()) when an error occurred.

See also: DCOPArg, DCOPArg

bool send ( const QCString& fun ) | ### send

Calls the function `fun` on the object referenced by this reference. Unlike call() this method does not expect a return value.

Parameters:

fun | the name of the DCOP function. This can be either the full function signature (e.g. "setName(QString)") or only the function's name (e.g. "setName"). In the latter case the exact signature will be guessed from the arguments

Returns: the DCOPReply object. Is invalid (DCOPReply::isValid()) when an error occurred.

See also: call()

template bool send ( const QCString& fun, const T1& t1 ) | ### send

Calls the function `fun` on the object referenced by this reference. Unlike call() this method does not expect a return value.

Parameters:

fun | the name of the DCOP function. This can be either the full function signature (e.g. "setName(QString)") or only the function's name (e.g. "setName"). In the latter case the exact signature will be guessed from the arguments
t1 | the first argument of the function. This can be a supported base type or a DCOPArg object.

Returns: the DCOPReply object. Is invalid (DCOPReply::isValid()) when an error occurred.

See also: DCOPArg, DCOPArg

template bool send ( const QCString& fun, const T1& t1, const T2& t2 ) | ### send

Calls the function `fun` on the object referenced by this reference. Unlike call() this method does not expect a return value.

Parameters:

fun | the name of the DCOP function. This can be either the full function signature (e.g. "setName(QString)") or only the function's name (e.g. "setName"). In the latter case the exact signature will be guessed from the arguments
t1 | the first argument of the function. This can be a supported base type or a DCOPArg object.
t2 | the second argument of the function. This can be a supported base type or a DCOPArg object.

Returns: the DCOPReply object. Is invalid (DCOPReply::isValid()) when an error occurred.

See also: DCOPArg, DCOPArg

template bool send ( const QCString& fun, const T1& t1, const T2& t2, const T3& t3 ) | ### send

Calls the function `fun` on the object referenced by this reference. Unlike call() this method does not expect a return value.

Parameters:

fun | the name of the DCOP function. This can be either the full function signature (e.g. "setName(QString)") or only the function's name (e.g. "setName"). In the latter case the exact signature will be guessed from the arguments
t1 | the first argument of the function. This can be a supported base type or a DCOPArg object.
t2 | the second argument of the function. This can be a supported base type or a DCOPArg object.
t3 | the third argument of the function. This can be a supported base type or a DCOPArg object.

Returns: the DCOPReply object. Is invalid (DCOPReply::isValid()) when an error occurred.

See also: DCOPArg, DCOPArg

template bool send ( const QCString& fun, const T1& t1, const T2& t2, const T3& t3, const T4& t4 ) | ### send

Calls the function `fun` on the object referenced by this reference. Unlike call() this method does not expect a return value.

Parameters:

fun | the name of the DCOP function. This can be either the full function signature (e.g. "setName(QString)") or only the function's name (e.g. "setName"). In the latter case the exact signature will be guessed from the arguments
t1 | the first argument of the function. This can be a supported base type or a DCOPArg object.
t2 | the second argument of the function. This can be a supported base type or a DCOPArg object.
t3 | the third argument of the function. This can be a supported base type or a DCOPArg object.
t4 | the fourth argument of the function. This can be a supported base type or a DCOPArg object.

Returns: the DCOPReply object. Is invalid (DCOPReply::isValid()) when an error occurred.

See also: DCOPArg, DCOPArg

template bool send ( const QCString& fun, const T1& t1, const T2& t2, const T3& t3, const T4& t4, const T5& t5 ) | ### send

Calls the function `fun` on the object referenced by this reference. Unlike call() this method does not expect a return value.

Parameters:

fun | the name of the DCOP function. This can be either the full function signature (e.g. "setName(QString)") or only the function's name (e.g. "setName"). In the latter case the exact signature will be guessed from the arguments
t1 | the first argument of the function. This can be a supported base type or a DCOPArg object.
t2 | the second argument of the function. This can be a supported base type or a DCOPArg object.
t3 | the third argument of the function. This can be a supported base type or a DCOPArg object.
t4 | the fourth argument of the function. This can be a supported base type or a DCOPArg object.
t5 | the fifth argument of the function. This can be a supported base type or a DCOPArg object.

Returns: the DCOPReply object. Is invalid (DCOPReply::isValid()) when an error occurred.

See also: DCOPArg, DCOPArg

template bool send ( const QCString& fun, const T1& t1, const T2& t2, const T3& t3, const T4& t4, const T5& t5, const T6& t6 ) | ### send

Calls the function `fun` on the object referenced by this reference. Unlike call() this method does not expect a return value.

Parameters:

fun | the name of the DCOP function. This can be either the full function signature (e.g. "setName(QString)") or only the function's name (e.g. "setName"). In the latter case the exact signature will be guessed from the arguments
t1 | the first argument of the function. This can be a supported base type or a DCOPArg object.
t2 | the second argument of the function. This can be a supported base type or a DCOPArg object.
t3 | the third argument of the function. This can be a supported base type or a DCOPArg object.
t4 | the fourth argument of the function. This can be a supported base type or a DCOPArg object.
t5 | the fifth argument of the function. This can be a supported base type or a DCOPArg object.
t6 | the sixth argument of the function. This can be a supported base type or a DCOPArg object.

Returns: the DCOPReply object. Is invalid (DCOPReply::isValid()) when an error occurred.

See also: DCOPArg, DCOPArg

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 ) | ### send

Calls the function `fun` on the object referenced by this reference. Unlike call() this method does not expect a return value.

Parameters:

fun | the name of the DCOP function. This can be either the full function signature (e.g. "setName(QString)") or only the function's name (e.g. "setName"). In the latter case the exact signature will be guessed from the arguments
t1 | the first argument of the function. This can be a supported base type or a DCOPArg object.
t2 | the second argument of the function. This can be a supported base type or a DCOPArg object.
t3 | the third argument of the function. This can be a supported base type or a DCOPArg object.
t4 | the fourth argument of the function. This can be a supported base type or a DCOPArg object.
t5 | the fifth argument of the function. This can be a supported base type or a DCOPArg object.
t6 | the sixth argument of the function. This can be a supported base type or a DCOPArg object.
t7 | the seventh argument of the function. This can be a supported base type or a DCOPArg object.

Returns: the DCOPReply object. Is invalid (DCOPReply::isValid()) when an error occurred.

See also: DCOPArg, DCOPArg

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 ) | ### send

Calls the function `fun` on the object referenced by this reference. Unlike call() this method does not expect a return value.

Parameters:

fun | the name of the DCOP function. This can be either the full function signature (e.g. "setName(QString)") or only the function's name (e.g. "setName"). In the latter case the exact signature will be guessed from the arguments
t1 | the first argument of the function. This can be a supported base type or a DCOPArg object.
t2 | the second argument of the function. This can be a supported base type or a DCOPArg object.
t3 | the third argument of the function. This can be a supported base type or a DCOPArg object.
t4 | the fourth argument of the function. This can be a supported base type or a DCOPArg object.
t5 | the fifth argument of the function. This can be a supported base type or a DCOPArg object.
t6 | the sixth argument of the function. This can be a supported base type or a DCOPArg object.
t7 | the seventh argument of the function. This can be a supported base type or a DCOPArg object.
t8 | the eigth argument of the function. This can be a supported base type or a DCOPArg object.

Returns: the DCOPReply object. Is invalid (DCOPReply::isValid()) when an error occurred.

See also: DCOPArg, DCOPArg

- Author: Matthias Ettrich , Torben Weis
- Generated: root on macppc.ports.openbsd.org on Sat Sep 6 10:36:00 2003, using kdoc 2.0a54.