dcop Library API Documentation

DCOPObject Class Reference

Provides an interface for receiving DCOP messages. More...

#include <dcopobject.h>

Inheritance diagram for DCOPObject:

MyDCOPObject List of all members.

Public Methods

 DCOPObject ()
 Creates a DCOPObject and calculates the object id using its physical memory address.

 DCOPObject (QObject *obj)
 Creates a DCOPObject and calculates the object id using QObject::name().

 DCOPObject (const QCString &objId)
 Creates a DCOPObject with object Id objId.

virtual ~DCOPObject ()
 Destroys the DCOPObject and removes it from the map of known objects.

QCString objId () const
 Returns the object id of the DCOPObject.

bool setObjId (const QCString &objId)
 Renames a dcop object, if no other with the same name exists Use with care, all dcop signals are disconnected.

virtual bool process (const QCString &fun, const QByteArray &data, QCString &replyType, QByteArray &replyData)
 Dispatches a message.

virtual bool processDynamic (const QCString &fun, const QByteArray &data, QCString &replyType, QByteArray &replyData)
 This function is of interest when you used an IDL compiler to generate the implementation for process() but you still want to dispatch some functions dynamically.

virtual QCStringList functionsDynamic ()
 This function is of interest when you used an IDL compiler to generate the implementation for functions() but you still want to list some functions dynamically.

virtual QCStringList interfacesDynamic ()
 This function is of interest when you used an IDL compiler to generate the implementation for interfaces() but you still want to list some interfaces dynamically.

virtual QCStringList interfaces ()
 Returns the names of the interfaces, specific ones last.

virtual QCStringList functions ()
 Returns the list of functions understood by the object.

void emitDCOPSignal (const QCString &signal, const QByteArray &data)
 Emit signal as DCOP signal from this object with data as arguments.

bool connectDCOPSignal (const QCString &sender, const QCString &senderObj, const QCString &signal, const QCString &slot, bool Volatile)
 Connects to a DCOP signal.

bool disconnectDCOPSignal (const QCString &sender, const QCString &senderObj, const QCString &signal, const QCString &slot)
 Disconnects a DCOP signal.

DCOPClientcallingDcopClient ()
 Returns the DCOPClient responsible for making the call.


Static Public Methods

bool hasObject (const QCString &objId)
 Checks whether an object with the given id is known in this process.

DCOPObject * find (const QCString &objId)
 Try to find a dcop object with the given id.

QPtrList< DCOPObject > match (const QCString &partialId)
 Tries to find an object using a partial object id.

QCString objectName (QObject *obj)
 Creates an object id for the QObject obj.


Detailed Description

Provides an interface for receiving DCOP messages.

This class provides an interface for receiving DCOP messages. To use it, simply multiply-inherit from DCOPObject and from some other class, and then implement the DCOPObject::process() method. Because this method is pure virtual, you must implement the method.

Note that it is usually more convenient to mark a section in the class with "k_dcop:", add your DCOP methods there and let the IDL compiler do the rest. Read the tutorials for more information.

See also:
DCOPClient , DCOPObjectProxy
Author:
Preston Brown <pbrown@kde.org>, Matthias Ettrich <ettrich@kde.org>

Definition at line 65 of file dcopobject.h.


Constructor & Destructor Documentation

DCOPObject::DCOPObject  
 

Creates a DCOPObject and calculates the object id using its physical memory address.

Definition at line 47 of file dcopobject.cpp.

References QMap::insert(), and QCString::sprintf().

DCOPObject::DCOPObject QObject   obj
 

Creates a DCOPObject and calculates the object id using QObject::name().

Parameters:
obj  the object to extract the name from

Definition at line 54 of file dcopobject.cpp.

References QMap::insert(), QCString::mid(), QObject::name(), QObject::parent(), and QCString::prepend().

DCOPObject::DCOPObject const QCString   objId
 

Creates a DCOPObject with object Id objId.

Parameters:
objId  the object id of the DCOP object

Definition at line 69 of file dcopobject.cpp.

References QMap::insert(), QCString::isEmpty(), and QCString::sprintf().

DCOPObject::~DCOPObject   [virtual]
 

Destroys the DCOPObject and removes it from the map of known objects.

Definition at line 78 of file dcopobject.cpp.

References DCOPClient::disconnectDCOPSignal(), DCOPClient::mainClient(), objId(), and QMap::remove().


Member Function Documentation

QCString DCOPObject::objId  
 

Returns the object id of the DCOPObject.

Returns:
the object's id

Definition at line 112 of file dcopobject.cpp.

Referenced by connectDCOPSignal(), disconnectDCOPSignal(), emitDCOPSignal(), MyDCOPObject::process(), and ~DCOPObject().

bool DCOPObject::setObjId const QCString   objId
 

Renames a dcop object, if no other with the same name exists Use with care, all dcop signals are disconnected.

Parameters:
objId  the new object id

Definition at line 98 of file dcopobject.cpp.

References DCOPClient::disconnectDCOPSignal(), QMap::end(), QMap::find(), QMap::insert(), DCOPClient::mainClient(), and QMap::remove().

bool DCOPObject::process const QCString   fun,
const QByteArray   data,
QCString   replyType,
QByteArray   replyData
[virtual]
 

Dispatches a message.

Usually you want to use an IDL compiler to automatically generate an implementation for this function.

If this function returns false, then processDynamic() is called.

Note to implementators: remember to call the baseclasses implementation. It handles the functions "functions()" and "interfaces()" which return the lists of supported functions and interfaces, respectively.

Parameters:
fun  is the normalized function signature. Such a signature usually looks like foobar(QString,int). The return type, qualifiers like "const" etc. are not part of the 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. The default implementation returns false for all fun except "functions()" and "interfaces()".
See also:
DCOPClient::normalizeFunctionSignature() , functions() , DCOPClient::process()

Reimplemented in KUniqueApplication, and MyDCOPObject.

Definition at line 166 of file dcopobject.cpp.

References functions(), interfaces(), and processDynamic().

Referenced by MyDCOPObject::process().

bool DCOPObject::processDynamic const QCString   fun,
const QByteArray   data,
QCString   replyType,
QByteArray   replyData
[virtual]
 

This function is of interest when you used an IDL compiler to generate the implementation for process() but you still want to dispatch some functions dynamically.

Dynamically means that methods may appear and vanish during runtime.

Parameters:
fun  is the normalized function signature. Such a signature usually looks like foobar(QString,int). The return type, qualifiers like "const" etc. are not part of the 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. The default implementation returns always false.
See also:
process() , DCOPClient::normalizeFunctionSignature() , functions(), , DCOPClient::process()

Definition at line 183 of file dcopobject.cpp.

Referenced by process().

QCStringList DCOPObject::functionsDynamic   [virtual]
 

This function is of interest when you used an IDL compiler to generate the implementation for functions() but you still want to list some functions dynamically.

Dynamically means that the methods may appear and vanish during runtime.

Returns:
A list of the additional functions, default is an empty list.
See also:
functions(),

Definition at line 193 of file dcopobject.cpp.

Referenced by functions().

QCStringList DCOPObject::interfacesDynamic   [virtual]
 

This function is of interest when you used an IDL compiler to generate the implementation for interfaces() but you still want to list some interfaces dynamically.

Dynamically means that they may appear and vanish during runtime.

Returns:
A list of the aditional interfaces, default is an empty list.
See also:
interfaces(),

Definition at line 187 of file dcopobject.cpp.

Referenced by interfaces().

QCStringList DCOPObject::interfaces   [virtual]
 

Returns the names of the interfaces, specific ones last.

The functions gets reimplemented by the IDL compiler. If you don't use the IDL compiler, consider implementing this function manually if you want your object to be easily explorable.

Returns:
a list of interfaces
See also:
functions()

Definition at line 198 of file dcopobject.cpp.

References interfacesDynamic().

Referenced by process().

QCStringList DCOPObject::functions   [virtual]
 

Returns the list of functions understood by the object.

It gets reimplemented by the IDL compiler. If you don't use the IDL compiler, consider implementing this function manually if you want your object to be easily scriptable.

Rationale: functions() allows an interpreter to do client-side type-casting properly.

Note to implementators: remember to call the baseclasses implementation.

Returns:
a list of functions
See also:
interfaces() , process() , processDynamic() , DCOPClient::normalizeFunctionSignature()

Reimplemented in MyDCOPObject.

Definition at line 205 of file dcopobject.cpp.

References functionsDynamic(), and QValueList< QCString >::prepend().

Referenced by MyDCOPObject::functions(), and process().

void DCOPObject::emitDCOPSignal const QCString   signal,
const QByteArray   data
 

Emit signal as DCOP signal from this object with data as arguments.

Parameters:
signal  the signal to emit
data  the data to send

Definition at line 213 of file dcopobject.cpp.

References DCOPClient::emitDCOPSignal(), DCOPClient::mainClient(), and objId().

bool DCOPObject::connectDCOPSignal const QCString   sender,
const QCString   senderObj,
const QCString   signal,
const QCString   slot,
bool    Volatile
 

Connects to a DCOP signal.

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.
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
  • Volatile is true and sender does not exist.
  • signal and slot do not have matching arguments.

Definition at line 220 of file dcopobject.cpp.

References DCOPClient::connectDCOPSignal(), DCOPClient::mainClient(), and objId().

bool DCOPObject::disconnectDCOPSignal const QCString   sender,
const QCString   senderObj,
const QCString   signal,
const QCString   slot
 

Disconnects a DCOP signal.

A special case is when both sender & signal are empty. In this case all connections related to this object 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. 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.

Definition at line 234 of file dcopobject.cpp.

References DCOPClient::disconnectDCOPSignal(), DCOPClient::mainClient(), and objId().

DCOPClient * DCOPObject::callingDcopClient  
 

Returns the DCOPClient responsible for making the call.

Only call this function while you are handling a DCOP call.

Returns:
the DCOPClient responsible for making the call. This information is only guaranteed to be correct when entering your DCOP function.
Since:
3.1

Definition at line 88 of file dcopobject.cpp.

bool DCOPObject::hasObject const QCString   objId [static]
 

Checks whether an object with the given id is known in this process.

Returns:
true if an object with the questionable objId is known in this process. This query does not ask proxies.
DCOPObjectProxy

Definition at line 117 of file dcopobject.cpp.

References QMap::contains().

DCOPObject * DCOPObject::find const QCString   objId [static]
 

Try to find a dcop object with the given id.

This function does not query the DCOPObjectProxy.

Parameters:
objId  the object id to search
Returns:
the DCOPObject for the id objId.

Definition at line 125 of file dcopobject.cpp.

References QMap::end(), and QMap::find().

QPtrList< DCOPObject > DCOPObject::match const QCString   partialId [static]
 

Tries to find an object using a partial object id.

This function is used for multicasting a DCOP message to several objects inside a single process.

Parameters:
partialId  the partial object id to search for
Returns:
a list of DCOPObjects beginning with the string contained in partialId.

Definition at line 135 of file dcopobject.cpp.

References QPtrList::append(), QMap::end(), and QCString::length().

QCString DCOPObject::objectName QObject   obj [static]
 

Creates an object id for the QObject obj.

This is done using the QObject::name() function.

Parameters:
obj  the object whose name will be used
Returns:
the created object id

Definition at line 146 of file dcopobject.cpp.

References QCString::mid(), QObject::name(), QObject::parent(), and QCString::prepend().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kdelibs Version 3.1.0.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Wed Oct 8 12:20:26 2003 by doxygen 1.2.18 written by Dimitri van Heesch, © 1997-2001