class DCOPClient

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

Definition#include <dcopclient.h>
InheritsQObject (qt) [public ]
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

Public Methods

Signals

Public Static Methods

Protected Slots


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

Create a new DCOP client, but do not attach to any server.

 ~DCOPClient ()

~DCOPClient

[virtual]

Clean up any open connections and dynamic data.

void  setServerAddress (const QCString &addr)

setServerAddress

[static]

Specify 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.

bool  attach ()

attach

Attach 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

Detach from the DCOP server.

bool  isAttached ()

isAttached

[const]

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

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

registerAs

Register 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".

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

bool  isRegistered ()

isRegistered

[const]

Query whether or not the client is 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.

int  socket ()

socket

[const]

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

void  suspend ()

suspend

Temporarily suspend 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.

void  resume ()

resume

Resume the processing of DCOP events. See suspend().

bool  send (const QCString &remApp, const QCString &remObj, const QCString &remFun, const QByteArray &data, bool fast=false)

send

Send a data block to the server.

Parameters:
remAppThe remote application id.
remObjThe name of the remote object.
remFunThe remote function in the specified object to call.
dataThe data to provide to the remote function.
fast(KDE 3.0: remove this) Tf set to true, a "fast" form of IPC will be used. Fast connections are not guaranteed to be implemented, but if they are they work only on the local machine, not across the network. "fast" is only a hint not an order.

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, bool fast=false)

send

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

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

call

Perform 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.

See also: send()

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

findObject

Search 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:
remAppThe remote application id.
remObjThe name of the remote object.
remFunThe remote function in the specified object to call. This function should return a bool and is used as criteria.
dataThe data to provide to the remote function.
foundAppThe remote application id that matched the criteria.
foundObjThe remote object that matched the criteria.
fastTf set to true, a "fast" form of IPC will be used. Fast connections are not guaranteed to be implemented, but if they are they work only on the local machine, not across the network. "fast" is only a hint not an order.

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

Emit 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

Connect to a DCOP signal

Parameters:
senderthe name of the client that emits the signal. When empty the signal will be passed from any client.
senderObjthe name of the sending object that emits the signal.
signalthe name of the signal. The arguments should match with slot.
receiverObjThe name of the object to call
slotThe name of the slot to call. Its arguments should match with signal.
VolatileIf 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

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

disconnectDCOPSignal

Disconnect 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:
senderthe name of the client that emits the signal.
senderObjthe name of the object that emits the signal. If empty all objects will be disconnected.
signalthe name of the signal. The arguments should match with slot.
receiverObjThe name of the object the signal is connected to. If empty all objects will be disconnected.
slotThe 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

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

process

[virtual]

Reimplement 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.

See also: setDefaultObject()

DCOPClientTransactionbeginTransaction ( )

beginTransaction

Delay 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!

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

endTransaction

Send the delayed reply of a function call.

Q_INT32  transactionId ()

transactionId

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.

bool  isApplicationRegistered ( const QCString& remApp)

isApplicationRegistered

Check whether remApp is registered with the DCOPServer.

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

QCStringList  registeredApplications ()

registeredApplications

Retrieves the list of all currently registered applications.

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

remoteObjects

Retrieves the list of objects of the remote application remApp

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

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

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

receive

Receive a DCOPSend or DCOPCall message from the server.

Parameters:
appThe application the message was intended for. Should be equal to our appId that we passed when the DCOPClient was created.
objThe name of the object to pass the data on to.
funThe name of the function in the object to call.
dataThe arguments for the function.

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

find

Receive a DCOPFind message from the server.

Parameters:
appThe application the message was intended for. Should be equal to our appId that we passed when the DCOPClient was created.
objThe name of the object to pass the data on to.
funThe name of the function in the object to call.
dataThe arguments for the function.

QCString  normalizeFunctionSignature ( const QCString& fun )

normalizeFunctionSignature

[static]

Normalize 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.

QCString  senderId ()

senderId

[const]

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

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.

QCString  defaultObject ()

defaultObject

[const]

Retrieve 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.

void  setNotifications ( bool enabled )

setNotifications

Enable / disable 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.

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.

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().

void  setMainClient ( DCOPClient* )

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().

void  emergencyClose ()

emergencyClose

[static]

QCString  dcopServerFile ()

dcopServerFile

[static]

void  applicationRegistered ( const QCString& appId )

applicationRegistered

[signal]

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

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

void  applicationRemoved ( const QCString& appId )

applicationRemoved

[signal]

Indicate that the formerly registered application appId has been removed.

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

void  attachFailed (const QString &msg)

attachFailed

[signal]

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

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

void  blockUserInput ( bool )

blockUserInput

[signal]

Indicate 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.

void  processSocketData (int socknum)

processSocketData

[protected slots slot]