You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
411 lines
14 KiB
411 lines
14 KiB
/*
|
|
Copyright (c) 1999,2000 Preston Brown <pbrown@kde.org>
|
|
Copyright (c) 1999, 2000 Matthias Ettrich <ettrich@kde.org>
|
|
|
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
of this software and associated documentation files (the "Software"), to deal
|
|
in the Software without restriction, including without limitation the rights
|
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
copies of the Software, and to permit persons to whom the Software is
|
|
furnished to do so, subject to the following conditions:
|
|
|
|
The above copyright notice and this permission notice shall be included in
|
|
all copies or substantial portions of the Software.
|
|
|
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
|
|
AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
|
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
*/
|
|
|
|
#ifndef _DCOPOBJECT_H
|
|
#define _DCOPOBJECT_H
|
|
|
|
#include <tqobject.h>
|
|
#include <tqmap.h>
|
|
#include <tqstring.h>
|
|
#include <tqptrlist.h>
|
|
#include <tqvaluelist.h>
|
|
#include <kdatastream.h> // needed for proper bool marshalling
|
|
#include "tdelibs_export.h"
|
|
|
|
class DCOPClient;
|
|
typedef TQValueList<TQCString> QCStringList;
|
|
|
|
// Makros for DCOP interfaces
|
|
|
|
#define K_DCOP \
|
|
public: \
|
|
virtual bool process(const TQCString &fun, const TQByteArray &data, TQCString& replyType, TQByteArray &replyData); \
|
|
QCStringList functions(); \
|
|
QCStringList interfaces(); \
|
|
private:
|
|
|
|
#define k_dcop_signals public
|
|
#define k_dcop_hidden public
|
|
#define k_dcop public
|
|
#define ASYNC void
|
|
|
|
/**
|
|
* 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 DCOPClient
|
|
* @see DCOPObjectProxy
|
|
* @author Preston Brown <pbrown@kde.org>, Matthias Ettrich <ettrich@kde.org>
|
|
*/
|
|
class DCOP_EXPORT DCOPObject
|
|
{
|
|
public:
|
|
/**
|
|
* Creates a DCOPObject and calculates the object id
|
|
* using its physical memory address.
|
|
*/
|
|
DCOPObject();
|
|
/**
|
|
* Creates a DCOPObject and calculates the object id
|
|
* using TQObject::name().
|
|
* @param obj the object to extract the name from
|
|
*/
|
|
DCOPObject(TQObject *obj);
|
|
/**
|
|
* Creates a DCOPObject with object Id @p objId.
|
|
* @param objId the object id of the DCOP object
|
|
*/
|
|
DCOPObject(const TQCString &objId);
|
|
/**
|
|
* Destroys the DCOPObject and removes it from the map
|
|
* of known objects.
|
|
*/
|
|
virtual ~DCOPObject();
|
|
|
|
/**
|
|
* Returns the object id of the DCOPObject.
|
|
* @return the object's id
|
|
*/
|
|
TQCString objId() const;
|
|
|
|
/**
|
|
* Renames a dcop object, if no other with the same name exists
|
|
* Use with care, all dcop signals are disconnected
|
|
*
|
|
* @param objId the new object id
|
|
**/
|
|
bool setObjId(const TQCString &objId);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param fun is the normalized function signature.
|
|
* Such a signature usually looks like
|
|
* foobar(TQString,int). The return type,
|
|
* qualifiers like "const" etc. are not part of
|
|
* the signature.
|
|
* @param data the received data
|
|
* @param replyType write the reply type in this string
|
|
* @param replyData write the reply data in this array
|
|
* @return true if successful, false otherwise. The default implementation
|
|
* returns false for all @p fun except "functions()" and
|
|
* "interfaces()".
|
|
*
|
|
* @see DCOPClient::normalizeFunctionSignature()
|
|
* @see functions()
|
|
* @see DCOPClient::process()
|
|
*/
|
|
virtual bool process(const TQCString &fun, const TQByteArray &data,
|
|
TQCString& replyType, TQByteArray &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.
|
|
* Dynamically means that methods may appear and vanish
|
|
* during runtime.
|
|
*
|
|
* @param fun is the normalized function signature.
|
|
* Such a signature usually looks like
|
|
* foobar(TQString,int). The return type,
|
|
* qualifiers like "const" etc. are not part of
|
|
* the signature.
|
|
* @param data the received data
|
|
* @param replyType write the reply type in this string
|
|
* @param replyData write the reply data in this array
|
|
* @return true if successful, false otherwise. The default implementation
|
|
* returns always false.
|
|
* @see process()
|
|
* @see DCOPClient::normalizeFunctionSignature()
|
|
* @see functions(),
|
|
* @see DCOPClient::process()
|
|
*/
|
|
virtual bool processDynamic(const TQCString &fun, const TQByteArray &data,
|
|
TQCString& replyType, TQByteArray &replyData);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @return A list of the additional functions, default is an empty list.
|
|
*
|
|
* @see functions(),
|
|
*/
|
|
virtual QCStringList functionsDynamic();
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @return A list of the additional interfaces, default is an empty list.
|
|
*
|
|
* @see interfaces(),
|
|
*/
|
|
virtual QCStringList interfacesDynamic();
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @return a list of interfaces
|
|
* @see functions()
|
|
*/
|
|
virtual QCStringList interfaces();
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @return a list of functions
|
|
* @see interfaces()
|
|
* @see process()
|
|
* @see processDynamic()
|
|
* @see DCOPClient::normalizeFunctionSignature()
|
|
*/
|
|
virtual QCStringList functions();
|
|
|
|
/**
|
|
* Emit @p signal as DCOP signal from this object with @p data as
|
|
* arguments
|
|
* @param signal the signal to emit
|
|
* @param data the data to send
|
|
*/
|
|
void emitDCOPSignal( const TQCString &signal, const TQByteArray &data);
|
|
|
|
/**
|
|
* Connects to a DCOP signal.
|
|
* @param sender the name of the client that emits the signal. When empty
|
|
* the signal will be passed from any client.
|
|
* @param senderObj the name of the sending object that emits the signal.
|
|
* @param signal the name of the signal. The arguments should match with slot.
|
|
* @param slot The name of the slot to call. Its arguments should match with signal.
|
|
* @param Volatile If true, the connection will not be reestablished when
|
|
* @p sender unregisters and reregisters with DCOP. In this case the @p sender
|
|
* must be registered when the connection is made.
|
|
* If false, the connection will be reestablished when @p sender reregisters.
|
|
* In this case the connection can be made even if @p sender is not registered
|
|
* at that time.
|
|
*
|
|
* @return false if a connection could not be established.
|
|
* This will be the case when
|
|
* @li @p Volatile is true and @p sender does not exist.
|
|
* @li @p signal and @p slot do not have matching arguments.
|
|
*/
|
|
bool connectDCOPSignal( const TQCString &sender, const TQCString &senderObj,
|
|
const TQCString &signal,
|
|
const TQCString &slot,
|
|
bool Volatile);
|
|
|
|
/**
|
|
* Disconnects a DCOP signal.
|
|
*
|
|
* A special case is when both @p sender & @p 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!)
|
|
*
|
|
* @param sender the name of the client that emits the signal.
|
|
* @param senderObj the name of the object that emits the signal.
|
|
* If empty all objects will be disconnected.
|
|
* @param signal the name of the signal. The arguments should match with slot.
|
|
* If empty all objects will be disconnected.
|
|
* @param slot The name of the slot the signal is connected to.
|
|
* If empty all slots will be disconnected.
|
|
*
|
|
* @return false if no connection(s) where removed.
|
|
*/
|
|
bool disconnectDCOPSignal( const TQCString &sender, const TQCString &senderObj,
|
|
const TQCString &signal,
|
|
const TQCString &slot);
|
|
|
|
/**
|
|
* Returns the DCOPClient responsible for making the call.
|
|
* Only call this function while you are handling a DCOP call.
|
|
* @return the DCOPClient responsible for making the call.
|
|
* This information is only guaranteed to be correct when
|
|
* entering your DCOP function.
|
|
* @since 3.1
|
|
*/
|
|
DCOPClient *callingDcopClient();
|
|
|
|
/**
|
|
* @internal Sets DCOPClient returned by callingDcopClient()
|
|
* @since 3.1
|
|
*/
|
|
void setCallingDcopClient(DCOPClient *);
|
|
|
|
/**
|
|
* Checks whether an object with the given id is known in this process.
|
|
* @return true if an object with the questionable @p objId is
|
|
* known in this process. This query does not ask proxies.
|
|
*
|
|
* DCOPObjectProxy
|
|
*/
|
|
static bool hasObject(const TQCString &objId);
|
|
|
|
/**
|
|
* Try to find a dcop object with the given id.
|
|
* This function does not query the DCOPObjectProxy.
|
|
* @param objId the object id to search
|
|
* @return the DCOPObject for the id @p objId.
|
|
*/
|
|
static DCOPObject *find(const TQCString &objId);
|
|
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param partialId the partial object id to search for
|
|
* @return a list of DCOPObjects beginning with the string
|
|
* contained in @p partialId.
|
|
*/
|
|
static TQPtrList<DCOPObject> match(const TQCString &partialId);
|
|
|
|
/**
|
|
* Creates an object id for the TQObject @p obj. This is done
|
|
* using the TQObject::name() function.
|
|
* @param obj the object whose name will be used
|
|
* @return the created object id
|
|
*/
|
|
static TQCString objectName( TQObject* obj );
|
|
|
|
private:
|
|
/**
|
|
* The object id of this DCOPObject.
|
|
*/
|
|
TQCString ident;
|
|
|
|
protected:
|
|
virtual void virtual_hook( int id, void* data );
|
|
private:
|
|
class DCOPObjectPrivate;
|
|
DCOPObjectPrivate *d;
|
|
};
|
|
|
|
class DCOPObjectProxyPrivate;
|
|
/**
|
|
* You must use a proxy if you want to dispatch method calls for
|
|
* object IDs which don't have (yet) a corresponding DCOPObject.
|
|
* This is somewhat like virtual object references in CORBA.
|
|
*
|
|
* @see DCOPObject
|
|
* @see DCOPClient
|
|
* @author Matthias Ettrich <ettrich@kde.org>
|
|
*/
|
|
class DCOP_EXPORT DCOPObjectProxy
|
|
{
|
|
public:
|
|
/**
|
|
* Creates a new proxy.
|
|
*/
|
|
DCOPObjectProxy();
|
|
|
|
/**
|
|
* Obsolete, do not use. DCOP clients know about object proxies
|
|
* automatically.
|
|
*
|
|
* @deprecated
|
|
*/
|
|
DCOPObjectProxy( DCOPClient*);
|
|
|
|
/**
|
|
* Destroy the proxy.
|
|
*/
|
|
virtual ~DCOPObjectProxy();
|
|
|
|
/**
|
|
* Reimplement this method to dispatch method calls.
|
|
*
|
|
* This method is called of all proxies if the DCOPClient
|
|
* knows no object with the id @p obj. If the first proxy returns
|
|
* @p true, the DCOPClient will no longer call other proxies.
|
|
*
|
|
* The object id @p obj may be empty for app-wide function calls no
|
|
* associated with any object.
|
|
* @param obj the id of the object
|
|
* @param fun is the normalized function signature.
|
|
* Such a signature usually looks like
|
|
* foobar(TQString,int). The return type,
|
|
* qualifiers like "const" etc. are not part of
|
|
* the signature.
|
|
* @param data the received data
|
|
* @param replyType write the reply type in this string
|
|
* @param replyData write the reply data in this array
|
|
* @return true if successful, false otherwise. The default implementation
|
|
* returns always false.
|
|
*/
|
|
virtual bool process( const TQCString& obj, const TQCString& fun,
|
|
const TQByteArray& data,
|
|
TQCString& replyType, TQByteArray &replyData );
|
|
private:
|
|
void* unused;
|
|
void* unused_too;
|
|
friend class DCOPClient;
|
|
static TQPtrList<DCOPObjectProxy>* proxies;
|
|
protected:
|
|
virtual void virtual_hook( int id, void* data );
|
|
private:
|
|
DCOPObjectProxyPrivate* d;
|
|
};
|
|
|
|
|
|
|
|
#endif
|