class DCOPClient

# class DCOPClient | Inter-process communication and remote procedure calls for KDE applications. More...
Definition | `#include <dcopclient.h>`
Inherits | QObject (qt) [public ]
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

#### Public Methods

- DCOPClient ()
- virtual ~DCOPClient ()
- bool attach ()
- void bindToApp ()
- bool detach ()
- bool isAttached () const
- bool isAttachedToForeignServer () const
- bool acceptCalls () const
- void setAcceptCalls (bool b)
- bool qtBridgeEnabled ()
- void setQtBridgeEnabled (bool b)
- QCString registerAs ( const QCString &appId, bool addPID = true )
- bool isRegistered () const
- QCString appId () const
- int socket () const
- void suspend ()
- void resume ()
- bool isSuspended () const
- bool send (const QCString &remApp, const QCString &remObj, const QCString &remFun, const QByteArray &data)
- bool send (const QCString &remApp, const QCString &remObj, const QCString &remFun, const QString &data)
- bool call (const QCString &remApp, const QCString &remObj, const QCString &remFun, const QByteArray &data, QCString& replyType, QByteArray &replyData, bool useEventLoop=false)
- bool findObject (const QCString &remApp, const QCString &remObj, const QCString &remFun, const QByteArray &data, QCString &foundApp, QCString &foundObj, bool useEventLoop=false)
- void emitDCOPSignal ( const QCString &object, const QCString &signal, const QByteArray &data)
- void emitDCOPSignal ( const QCString &signal, const QByteArray &data)
- bool connectDCOPSignal ( const QCString &sender, const QCString &senderObj, const QCString &signal, const QCString &receiverObj, const QCString &slot, bool Volatile)
- bool connectDCOPSignal ( const QCString &sender, const QCString &signal, const QCString &receiverObj, const QCString &slot, bool Volatile)
- bool disconnectDCOPSignal ( const QCString &sender, const QCString &senderObj, const QCString &signal, const QCString &receiverObj, const QCString &slot)
- bool disconnectDCOPSignal ( const QCString &sender, const QCString &signal, const QCString &receiverObj, const QCString &slot)
- virtual bool process (const QCString &fun, const QByteArray &data, QCString& replyType, QByteArray &replyData)
- DCOPClientTransaction * beginTransaction ( )
- void endTransaction ( DCOPClientTransaction *t, QCString& replyType, QByteArray &replyData)
- Q_INT32 transactionId () const
- bool isApplicationRegistered ( const QCString& remApp)
- QCStringList registeredApplications ()
- QCStringList remoteObjects ( const QCString& remApp, bool *ok = 0 )
- QCStringList remoteInterfaces ( const QCString& remApp, const QCString& remObj , bool *ok = 0 )
- QCStringList remoteFunctions ( const QCString& remApp, const QCString& remObj , bool *ok = 0 )
- bool receive (const QCString &app, const QCString &obj, const QCString &fun, const QByteArray& data, QCString& replyType, QByteArray &replyData)
- bool find (const QCString &app, const QCString &obj, const QCString &fun, const QByteArray& data, QCString& replyType, QByteArray &replyData)
- QCString senderId () const
- void setDefaultObject ( const QCString& objId )
- QCString defaultObject () const
- void setNotifications ( bool enabled )
- void setDaemonMode ( bool daemonMode )

#### Signals

- void applicationRegistered ( const QCString& appId )
- void applicationRemoved ( const QCString& appId )
- void attachFailed (const QString &msg)
- void blockUserInput ( bool block )

#### Public Static Methods

- static void setServerAddress (const QCString &addr)
- static QCString normalizeFunctionSignature ( const QCString& fun )
- static DCOPClient* mainClient ()
- static void setMainClient ( DCOPClient* mainClient)
- static void emergencyClose ()
- static const char * postMortemSender ()
- static const char * postMortemObject ()
- static const char * postMortemFunction ()
- static QCString dcopServerFile (const QCString &hostname=0)
- static QCString dcopServerFileOld (const QCString &hostname=0)

#### Protected Methods

- virtual void virtual_hook ( int id, void* data )

#### Protected Slots

- void processSocketData (int socknum)

## Detailed Description

Inter-process communication and remote procedure calls for KDE applications.

This class provides IPC and RPC for KDE applications. Usually you will not have to instantiate one yourself because KApplication contains a method to return a pointer to a DCOPClient object which can be used for your whole application.

Before being able to send or receive any DCOP messages, you will have to attach your client object to the DCOP server, and then register your application with a specific name. See attach() and registerAs() for more information.

Data to be sent should be serialized into a QDataStream which was initialized with the QByteArray that you actually intend to send the data in. An example of how you might do this:

       QByteArray data;
       QDataStream arg(data, IO_WriteOnly);
       arg << QString("This is text I am serializing");
       client->send("someApp", "someObject", "someFunction", arg);

See also: KApplication::dcopClient()

DCOPClient () | ### DCOPClient

Constructs a new DCOP client, but does not attach to any server.

~DCOPClient () | ### ~DCOPClient

[virtual]

Cleans up any open connections and dynamic data.

void setServerAddress (const QCString &addr) | ### setServerAddress

[static]

Sets the address of a server to use upon attaching.

If no server address is ever specified, attach will try its best to find the server anyway.

Parameters:

addr | the new address of the server

bool attach () | ### attach

Attaches to the DCOP server.

If the connection was already attached, the connection will be re-established with the current server address.

Naturally, only attached application can use DCOP services.

If a QApplication object exists then client registers itself as QApplication::name() + "-" + . If no QApplication object exists the client registers itself as "anonymous".

If you want to register differently, you should use registerAs() instead.

Returns: true if attaching was successful.

void bindToApp () | ### bindToApp

Internal function for KUniqueApplication to register the DCOPClient with the application in case the application didn't exist at the time the DCOPClient was created.

bool detach () | ### detach

Detaches from the DCOP server.

Returns: true if successful, false otherwise

bool isAttached () | ### isAttached

[const]

Returns whether or not the client is attached to the server.

Returns: true if attached, false if not

bool isAttachedToForeignServer () | ### isAttachedToForeignServer

[const]

Returns whether the client is attached to a server owned by another user.

Returns: true if attached to a foreign server, false if not

bool acceptCalls () | ### acceptCalls

[const]

Returns whether the client handles incoming calls.

Returns: true if the client accepts calls

void setAcceptCalls (bool b) | ### setAcceptCalls

Specify whether the client should accept incoming calls. By default clients accept incoming calls, but not when connected to a foreign server.

Parameters:

b | true to accept calls, false to reject them

bool qtBridgeEnabled () | ### qtBridgeEnabled

Returns whether the DCOP - Qt bridge is enabled. By default the DCOP - Qt bridge is enabled.

Returns: true if Qt objects are accessible over DCOP

void setQtBridgeEnabled (bool b) | ### setQtBridgeEnabled

Specify whether Qt objects of the application should be accessible via DCOP. By default the DCOP - Qt bridge is enabled.

Parameters:

b | true to make Qt objects accessible over DCOP

QCString registerAs ( const QCString &appId, bool addPID = true ) | ### registerAs

Registers at the DCOP server.

If the application was already registered, the registration will be re-done with the new appId.

`appId` is a `unique` application/program id that the server will use to associate requests with. If there is already an application registered with the same name, the server will add a number to the id to unify it. If `addPID` is true, the PID of the current process will be added to id.

Registration is necessary if you want to allow other clients to talk to you. They can do so using your `appId` as first parameter for send() or call(). If you just want to talk to other clients, you do not need to register at the server. In that case attach() is enough. It will implicitly register you as "anonymous".

Parameters:

appId | the id of the application
addPID | true to add the process id

Returns: The actual `appId` used for the registration or a null string if the registration wasn't successful.

bool isRegistered () | ### isRegistered

[const]

Returns whether or not the client is registered at the server.

Returns: true if registered at the server

QCString appId () | ### appId

[const]

Returns the current app id or a null string if the application hasn't yet been registered.

Parameters:

the | application id, or QString::null if not registered

int socket () | ### socket

[const]

Returns the socket fd that is used for communication with the server.

Returns: The socket over which DCOP is communicating with the server.

void suspend () | ### suspend

Temporarily suspends processing of DCOP events. This can be usefull if you need to show e.g. a dialog before your application is ready to accept DCOP requests. Normally the dialog would start an event loop and in this event loop DCOP requests will be handled.

Be aware that not responding to DCOP requests may cause other programs that want to communicate with your application, to hang.

See also: resume(), isSuspended()

void resume () | ### resume

Resumes the processing of DCOP events.

See also: suspend()., isSuspended()

bool isSuspended () | ### isSuspended

[const]

Returns whether DCOP events are being processed.

See also: suspend(), resume().

bool send (const QCString &remApp, const QCString &remObj, const QCString &remFun, const QByteArray &data) | ### send

Sends a data block to the server.

Parameters:

remApp | The remote application id.
remObj | The name of the remote object.
remFun | The remote function in the specified object to call.
data | The data to provide to the remote function.

Returns: Whether or not the server was able to accept the send.

bool send (const QCString &remApp, const QCString &remObj, const QCString &remFun, const QString &data) | ### send

This function acts exactly the same as the above, but the data parameter can be specified as a QString for convenience.

Parameters:

remApp | The remote application id.
remObj | The name of the remote object.
remFun | The remote function in the specified object to call.
data | The data to provide to the remote function.

Returns: Whether or not the server was able to accept the send.

bool call (const QCString &remApp, const QCString &remObj, const QCString &remFun, const QByteArray &data, QCString& replyType, QByteArray &replyData, bool useEventLoop=false) | ### call

Performs a synchronous send and receive.

The parameters are the same as for send, with the exception of another QByteArray being provided for results to be (optionally) returned in.

A call blocks the application until the process receives the answer.

If `useEventLoop` is true, a local event loop will be started after 1/10th of a second in order to keep the user interface updated (by processing paint events and such) until an answer is received.

Parameters:

remApp | the remote application's id
remObj | the remote object id
remFun | the remote function id
data | the data to send
replyType | the type of the reply will be written here
replyData | the data of the reply will be written here
useEventLoop | if true the event loop will be started when the call blocks too long

Returns: true if successful, false otherwise

See also: send()

bool findObject (const QCString &remApp, const QCString &remObj, const QCString &remFun, const QByteArray &data, QCString &foundApp, QCString &foundObj, bool useEventLoop=false) | ### findObject

Searches for an object which matches a criteria.

findObject calls `remFun` in the applications and objects identified by `remApp` and `remObj` until `remFun` returns true. The name of the application and object that returned true are returned in `foundApp` and `foundObj` respectively.

If `remFun` is empty a default function is called in the object which always returns `true`.

A findObject blocks the application until the process receives the answer.

If `useEventLoop` is true, a local event loop will be started after 1/10th of a second in order to keep the user interface updated (by processing paint events and such) until an answer is received.

Parameters:

remApp | The remote application id.
remObj | The name of the remote object.
remFun | The remote function in the specified object to call. This function should return a bool and is used as criteria.
data | The data to provide to the remote function.
foundApp | The remote application id that matched the criteria.
foundObj | The remote object that matched the criteria.
useEventLoop | if true the event loop will be started when the call blocks too long

Returns: true is returned when an object was found for which `remFun` returned true. If no such object is the function returns false.

See also: send()

void emitDCOPSignal ( const QCString &object, const QCString &signal, const QByteArray &data) | ### emitDCOPSignal

Emits `signal` as DCOP signal from object `object` with `data` as arguments.

void emitDCOPSignal ( const QCString &signal, const QByteArray &data) | ### emitDCOPSignal

bool connectDCOPSignal ( const QCString &sender, const QCString &senderObj, const QCString &signal, const QCString &receiverObj, const QCString &slot, bool Volatile) | ### connectDCOPSignal

Connects to a DCOP signal.

- `Volatile` is true and `sender` does not exist.
- `signal` and `slot` do not have matching arguments.

Parameters:

sender | the name of the client that emits the signal. When empty the signal will be passed from any client.
senderObj | the name of the sending object that emits the signal.
signal | the name of the signal. The arguments should match with slot.
receiverObj | The name of the object to call
slot | The name of the slot to call. Its arguments should match with signal.
Volatile | If true, the connection will not be reestablished when `sender` unregisters and reregisters with DCOP. In this case the `sender` must be registered when the connection is made. If false, the connection will be reestablished when `sender` reregisters. In this case the connection can be made even if `sender` is not registered at that time.

Returns: false if a connection could not be established. This will be the case when

bool connectDCOPSignal ( const QCString &sender, const QCString &signal, const QCString &receiverObj, const QCString &slot, bool Volatile) | ### connectDCOPSignal

For backwards compatibility

bool disconnectDCOPSignal ( const QCString &sender, const QCString &senderObj, const QCString &signal, const QCString &receiverObj, const QCString &slot) | ### disconnectDCOPSignal

Disconnects a DCOP signal.

A special case is when both `sender` & `signal` are empty. In this case all connections related to `receiverObj` in the current client are disconnected. (Both connections from as well as to this object!)

Parameters:

sender | the name of the client that emits the signal.
senderObj | the name of the object that emits the signal. If empty all objects will be disconnected.
signal | the name of the signal. The arguments should match with slot.
receiverObj | The name of the object the signal is connected to. If empty all objects will be disconnected.
slot | The name of the slot the signal is connected to. If empty all slots will be disconnected.

Returns: false if no connection(s) where removed.

bool disconnectDCOPSignal ( const QCString &sender, const QCString &signal, const QCString &receiverObj, const QCString &slot) | ### disconnectDCOPSignal

For backwards compatibility

bool process (const QCString &fun, const QByteArray &data, QCString& replyType, QByteArray &replyData) | ### process

[virtual]

Reimplement this function to handle app-wide function calls unassociated w/an object.

Note that `fun` is normalized. See normalizeFunctionSignature().

If you do not want to reimplement this function for whatever reason, you can also use a default object or a DCOPObjectProxy.

Parameters:

the | normalized function signature
data | the received data
replyType | write the reply type in this string
replyData | write the reply data in this array

Returns: true if successful, false otherwise

See also: setDefaultObject()

DCOPClientTransaction * beginTransaction ( ) | ### beginTransaction

Delays the reply of the current function call until endTransaction() is called.

This allows a server to queue requests.

Note: Should be called from inside process() only!

See also: endTransaction()

void endTransaction ( DCOPClientTransaction *t, QCString& replyType, QByteArray &replyData) | ### endTransaction

Sends the delayed reply of a function call.

Parameters:

t | the transaction as received from beginTransaction()
replyType | write the reply type in this string
replyData | write the reply data in this array

See also: beginTransaction()

Q_INT32 transactionId () | ### transactionId

[const]

Test whether the current function call is delayed.

Note: Should be called from inside process() only!

Returns: The ID of the current transaction or 0 if no transaction is going on.

See also: process(), beginTransaction()

bool isApplicationRegistered ( const QCString& remApp) | ### isApplicationRegistered

Checks whether `remApp` is registered with the DCOP server.

Parameters:

remApp | the id of the remote application

Returns: true if the remote application is registered, otherwise `false`.

QCStringList registeredApplications () | ### registeredApplications

Retrieves the list of all currently registered applications from dcopserver.

Returns: a list of all regietered applications

QCStringList remoteObjects ( const QCString& remApp, bool *ok = 0 ) | ### remoteObjects

Retrieves the list of objects of the remote application `remApp`.

Parameters:

tremAPp | he id of the application
ok | if not null, the function sets `ok` to true if successful and false if an error occurred

Returns: the list of object ids

QCStringList remoteInterfaces ( const QCString& remApp, const QCString& remObj , bool *ok = 0 ) | ### remoteInterfaces

Retrieves the list of interfaces of the remote object `remObj` of application `remApp`.

Parameters:

remApp | the id of the application
remObj | the id of the object
ok | if not null, the function sets `ok` to true if successful and false if an error occurred

Returns: the list of interfaces

QCStringList remoteFunctions ( const QCString& remApp, const QCString& remObj , bool *ok = 0 ) | ### remoteFunctions

Retrieves the list of functions of the remote object `remObj` of application `remApp`

Parameters:

remApp | the id of the application
remObj | the id of the object
ok | if not null, the function sets `ok` to true if successful and false if an error occurred

Returns: the list of function ids

bool receive (const QCString &app, const QCString &obj, const QCString &fun, const QByteArray& data, QCString& replyType, QByteArray &replyData) | ### receive

Receives a DCOPSend or DCOPCall message from the server.

Parameters:

app | The application the message was intended for. Should be equal to our appId that we passed when the DCOPClient was created.
obj | The name of the object to pass the data on to.
fun | The name of the function in the object to call.
data | The arguments for the function.

Returns: true if successful, false otherwise

bool find (const QCString &app, const QCString &obj, const QCString &fun, const QByteArray& data, QCString& replyType, QByteArray &replyData) | ### find

Receives a `DCOPFind` message from the server.

Parameters:

app | The application the message was intended for. Should be equal to our appId that we passed when the DCOPClient was created.
obj | The name of the object to pass the data on to.
fun | The name of the function in the object to call.
data | The arguments for the function.

QCString normalizeFunctionSignature ( const QCString& fun ) | ### normalizeFunctionSignature

[static]

Normalizes the function signature `fun`.

A normalized signature doesn't contain any unnecessary whitespace anymore. The remaining whitespace consists of single blanks only (0x20).

Example for a normalized signature:

       "someFunction(QString,int)"

When using send() or call(), normalization is done automatically for you.

Parameters:

fun | the function signature to normalize

Returns: the normalized function

QCString senderId () | ### senderId

[const]

Returns the appId of the last application that talked to us.

Returns: the application id of the last application that send a message to this client

void setDefaultObject ( const QCString& objId ) | ### setDefaultObject

Installs object `objId` as application-wide default object.

All app-wide messages that have not been processed by the dcopclient will be send further to `objId`.

Parameters:

objId | the id of the new default object

QCString defaultObject () | ### defaultObject

[const]

Returns the current default object or an empty string if no object is installed as default object.

A default object receives application-wide messages that have not been processed by the DCOPClient itself.

Returns: the id of the new default object

void setNotifications ( bool enabled ) | ### setNotifications

Enables / disables the applicationRegistered() / applicationRemoved() signals. Note that a counter is maintained about how often this method was called. If this method is called twice with `enabled` set to true, notifications will be enabled until it was called with `enabled` set to false as often.

They are disabled by default.

Parameters:

enabled | true to enable notifications, false to disable

void setDaemonMode ( bool daemonMode ) | ### setDaemonMode

Tells the dcopserver to treat the client as daemon client, not as regular client. If the number of regular clients drops down to zero, the dcopserver will emit a KDE termination signal after 10 seconds.

Parameters:

daemonMode | true to enable daemon mode, false to disable

DCOPClient* mainClient () | ### mainClient

[static]

Returns the application's main dcop client. The main client can be used by objects that do not have any specific access to a dcop client. In KDE applications, the main client usually is the same as KAppliction::dcopClient().

Returns: the application's main dcop client

void setMainClient ( DCOPClient* mainClient) | ### setMainClient

[static]

Sets the application's main dcop client. The main client can be used by objects that do not have any specific access to a dcop client. In KDE applications, the main client usually is the same as KAppliction::dcopClient().

Parameters:

mainClient | the new main dcop client

void emergencyClose () | ### emergencyClose

[static]

const char * postMortemSender () | ### postMortemSender

[static]

Provides information about the last DCOP call for debugging purposes.

const char * postMortemObject () | ### postMortemObject

[static]

const char * postMortemFunction () | ### postMortemFunction

[static]

QCString dcopServerFile (const QCString &hostname=0) | ### dcopServerFile

[static]

File with information how to reach the dcopserver.

Parameters:

hostname | Hostname to use, if empty current hostname of the system is used.

Returns: Filename that contains information how to contact the DCOPserver.

QCString dcopServerFileOld (const QCString &hostname=0) | ### dcopServerFileOld

[static]

For backwards compatibility with KDE 2.x

void applicationRegistered ( const QCString& appId ) | ### applicationRegistered

[signal]

Indicates that the application `appId` has been registered with the server we are attached to.

You need to call setNotifications() first, to tell the DCOP server that you want to get these events.

Parameters:

appId | the id of the new application

void applicationRemoved ( const QCString& appId ) | ### applicationRemoved

[signal]

Indicates that the formerly registered application `appId` has been removed.

You need to call setNotifications() first, to tell the DCOP server that you want to get these events.

Parameters:

appId | the id of the removed application

void attachFailed (const QString &msg) | ### attachFailed

[signal]

Indicates that the process of establishing DCOP communications failed in some manner.

Usually attached to a dialog box or some other visual aid.

Parameters:

msg | the message tha contains further information

void blockUserInput ( bool block ) | ### blockUserInput

[signal]

Indicates that user input shall be blocked or released, depending on the argument.

The signal is emitted whenever the client has to wait too long (i.e. more than 1/10 of a second) for an answer to a synchronous call. In that case, it will enter a local event loop to keep the GUI updated until finally an answer arrives.

In KDE, the KApplication object connects to this signal to be able to block any user input (i.e. mouse and key events) while we are waiting for an answer. If we did not do this, the application might end up in an illegal state, as a keyboard shortcut or a mouse action might cause another dcop call to be issued.

Parameters:

block | true to block user input, false otherwise

void processSocketData (int socknum) | ### processSocketData

[protected slots slot]

Process data from the socket.

Parameters:

socknum | the fd of the socket

void virtual_hook ( int id, void* data ) | ### virtual_hook

[protected virtual]

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