|
|
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); |
|
Create a new DCOP client, but do not attach to any server.
~ |
[virtual]
Clean up any open connections and dynamic data.
void |
[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 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() + "-" + <pid>. 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 |
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 from the DCOP server.
bool |
[const]
Query whether or not the client is attached to the server.
QCString |
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 |
[const]
Query whether or not the client is registered at the server.
QCString |
[const]
Returns the current app id or a null string if the application hasn't yet been registered.
int |
[const]
Returns: The socket over which DCOP is communicating with the server.
void |
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 the processing of DCOP events. See suspend().
bool |
Send a data block to the server.
Parameters:
Returns: Whether or not the server was able to accept the send.
bool |
This function acts exactly the same as the above, but the data parameter can be specified as a QString for convenience.
bool |
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.
bool |
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:
Returns: true is returned when an object was found for which remFun
returned true. If no such object is the function returns false.
void |
Emit signal
as DCOP signal from object object
with @data as
arguments
void |
bool |
Connect to a DCOP signal
Volatile
is true and sender
does not exist.
signal
and slot
do not have matching arguments.
Parameters:
Returns: false if a connection could not be established. This will be the case when
bool |
bool |
Disconnect a DCOP signal
A special case is when both sender & signal are empty. In this case all connections related to @param receiverObj in the current client are disconnected. (Both connections from as well as to this object!)
Parameters:
Returns: false if no connection(s) where removed.
bool |
bool |
[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.
DCOPClientTransaction * |
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 |
Send the delayed reply of a function call.
Q_INT32 |
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 |
Check whether remApp
is registered with the DCOPServer.
Returns: true
if the remote application is registered, otherwise false.
QCStringList |
Retrieves the list of all currently registered applications.
QCStringList |
Retrieves the list of objects of the remote application remApp
QCStringList |
Retrieves the list of interfaces of the remote object remObj
of application remApp
QCStringList |
Retrieves the list of functions of the remote object remObj
of application remApp
bool |
Receive a DCOPSend or DCOPCall message from the server.
Parameters:
bool |
Receive a DCOPFind
message from the server.
Parameters:
QCString |
[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 |
[const]
Retrieve the appId
of the last application that talked to us.
void |
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 |
[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 |
Enable / disable the applicationRegistered() / applicationRemoved() signals.
They are disabled by default.
DCOPClient* |
[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 |
[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 |
[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 |
[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 |
[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 |
[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 |
[protected slot]