|
|
Provide 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 dataStream(data, IO_WriteOnly);
dataStream << QString("This is text I am serializing");
client->send("someApp", "someObject", "someFunction", data);
| DCOPClient () |
Create a new DCOP client, but do not attach to any server.
| ~DCOPClient () |
Clean up any open connections and dynamic data.
| void setServerAddress (const QCString &addr) |
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 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 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 from the DCOP server.
| bool isAttached () |
Query whether or not the client is attached to the server.
| QCString registerAs ( QCString appId, bool addPID = true ) |
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 () |
Query whether or not the client is registered at the server.
| QCString appId () |
Returns the current app id or a null string if the application hasn't yet been registered.
| int socket () |
Returns: The socket over which DCOP is communicating with the server.
| bool send (const QCString &remApp, const QCString &remObj, const QCString &remFun, const QByteArray &data, bool fast=false) |
Send 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. |
| fast | 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) |
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 fast=false) |
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.
| bool process (const QCString &fun, const QByteArray &data, QCString& replyType, QByteArray &replyData) |
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 DCOPObjectProxy.
| DCOPClientTransaction * 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) |
Send the delayed reply of a function call.
| Q_INT32 transactionId () |
Test whether the current function call is delayed.
NOTE: Should be called from inside process(...) only!
Returns: The ID of the current transaction 0 if no transaction is going on.
| bool isApplicationRegistered ( const QCString& remApp) |
Check whether remApp is registered with the DCOPServer.
Returns: true if the remote application is registered, otherwise false.
| QCStringList registeredApplications () |
Retrieve the list of all currently registered applications.
| bool receive (const QCString &app, const QCString &obj, const QCString &fun, const QByteArray& data, QCString& replyType, QByteArray &replyData) |
Receive a piece of data from the server.
Parameters:
| app | The application the data 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 ) |
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:
"void someFunction(QString,int)"
When using send() or call(), normlization is done automatically for you.
| void setNotifications ( bool enabled ) |
Enable / disable the applicationRegistered() / applicationRemoved() signals.
They are disabled by default.
| void applicationRegistered ( const QCString& appId ) |
Indicates 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 ) |
Indicates 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) |
Indicates that the process of establishing DCOP communications failed in some manner. Usually attached to a dialog box or some other visual aid.