QCopChannel Class Reference

The QCopChannel class provides communication capabilities between clients in Qt for Embedded Linux. More...

#include <qcopchannel_qws.h>

Inheritance diagram for QCopChannel:

Signals
void	received (const QString &msg, const QByteArray &data)
	This signal is emitted whenever this object's channel receives new messages (i. More...
Signals inherited from QObject
void	destroyed (QObject *=0)
	This signal is emitted immediately before the object obj is destroyed, and can not be blocked. More...

Public Functions
QString	channel () const
	Returns the name of this object's channel. More...
	QCopChannel (const QString &channel, QObject *parent=0)
	Constructs a QCopChannel object for the specified channel, with the given parent. More...
virtual void	receive (const QString &msg, const QByteArray &data)
	Processes the incoming message and data. More...
virtual	~QCopChannel ()
	Destroys this QCopChannel object. More...
Public Functions inherited from QObject
bool	blockSignals (bool b)
	If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it). More...
const QObjectList &	children () const
	Returns a list of child objects. More...
bool	connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const
bool	disconnect (const char *signal=0, const QObject *receiver=0, const char *member=0)
bool	disconnect (const QObject *receiver, const char *member=0)
void	dumpObjectInfo ()
	Dumps information about signal connections, etc. More...
void	dumpObjectTree ()
	Dumps a tree of children to the debug output. More...
QList< QByteArray >	dynamicPropertyNames () const
	Returns the names of all properties that were dynamically added to the object using setProperty(). More...
virtual bool	event (QEvent *)
	This virtual function receives events to an object and should return true if the event e was recognized and processed. More...
virtual bool	eventFilter (QObject *, QEvent *)
	Filters events if this object has been installed as an event filter for the watched object. More...
template<typename T >
T	findChild (const QString &aName=QString()) const
	Returns the child of this object that can be cast into type T and that is called name, or 0 if there is no such object. More...
template<typename T >
QList< T >	findChildren (const QString &aName=QString()) const
	Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects. More...
template<typename T >
QList< T >	findChildren (const QRegExp &re) const
bool	inherits (const char *classname) const
	Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false. More...
void	installEventFilter (QObject *)
	Installs an event filter filterObj on this object. More...
bool	isWidgetType () const
	Returns true if the object is a widget; otherwise returns false. More...
void	killTimer (int id)
	Kills the timer with timer identifier, id. More...
virtual const QMetaObject *	metaObject () const
	Returns a pointer to the meta-object of this object. More...
void	moveToThread (QThread *thread)
	Changes the thread affinity for this object and its children. More...
QString	objectName () const
QObject *	parent () const
	Returns a pointer to the parent object. More...
QVariant	property (const char *name) const
	Returns the value of the object's name property. More...
Q_INVOKABLE	QObject (QObject *parent=0)
	Constructs an object with parent object parent. More...
void	removeEventFilter (QObject *)
	Removes an event filter object obj from this object. More...
void	setObjectName (const QString &name)
void	setParent (QObject *)
	Makes the object a child of parent. More...
bool	setProperty (const char *name, const QVariant &value)
	Sets the value of the object's name property to value. More...
void	setUserData (uint id, QObjectUserData *data)
bool	signalsBlocked () const
	Returns true if signals are blocked; otherwise returns false. More...
int	startTimer (int interval)
	Starts a timer and returns a timer identifier, or returns zero if it could not start a timer. More...
QThread *	thread () const
	Returns the thread in which the object lives. More...
QObjectUserData *	userData (uint id) const
virtual	~QObject ()
	Destroys the object, deleting all its child objects. More...

Static Public Functions
static bool	flush ()
	Flushes all queued messages to the registered listeners. More...
static bool	isRegistered (const QString &channel)
	Queries the server for the existence of the given channel. More...
static void	reregisterAll ()
static bool	send (const QString &channel, const QString &msg)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
static bool	send (const QString &channel, const QString &msg, const QByteArray &data)
	Sends the given message on the specified channel with the given data. More...
static void	sendLocally (const QString &ch, const QString &msg, const QByteArray &data)
	Client side: distribute received event to the QCop instance managing the channel. More...
Static Public Functions inherited from QObject
static bool	connect (const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
	Creates a connection of the given type from the signal in the sender object to the method in the receiver object. More...
static bool	connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)
static bool	disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member)
	Disconnects signal in object sender from method in object receiver. More...
static bool	disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member)
static uint	registerUserData ()
static QString	tr (const char *sourceText, const char *comment=0, int n=-1)
static QString	trUtf8 (const char *sourceText, const char *comment=0, int n=-1)

Private Functions
void	init (const QString &channel)

Static Private Functions
static void	answer (QWSClient *cl, const QString &ch, const QString &msg, const QByteArray &data)
	Server side: transmit the message to all clients registered to the specified channel. More...
static void	detach (QWSClient *cl)
	Server side: unsubscribe cl from all channels. More...
static void	registerChannel (const QString &ch, QWSClient *cl)
	Server side: subscribe client cl on channel ch. More...

Properties
QCopChannelPrivate *	d

Friends
class	QApplication
class	QWSServer
class	QWSServerPrivate

Additional Inherited Members
Public Slots inherited from QObject
void	deleteLater ()
	Schedules this object for deletion. More...
Static Public Variables inherited from QObject
static const QMetaObject	staticMetaObject
	This variable stores the meta-object for the class. More...
Protected Functions inherited from QObject
virtual void	childEvent (QChildEvent *)
	This event handler can be reimplemented in a subclass to receive child events. More...
virtual void	connectNotify (const char *signal)
	This virtual function is called when something has been connected to signal in this object. More...
virtual void	customEvent (QEvent *)
	This event handler can be reimplemented in a subclass to receive custom events. More...
virtual void	disconnectNotify (const char *signal)
	This virtual function is called when something has been disconnected from signal in this object. More...
	QObject (QObjectPrivate &dd, QObject *parent=0)
int	receivers (const char *signal) const
	Returns the number of receivers connected to the signal. More...
QObject *	sender () const
	Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns 0. More...
int	senderSignalIndex () const
virtual void	timerEvent (QTimerEvent *)
	This event handler can be reimplemented in a subclass to receive timer events for the object. More...
Protected Variables inherited from QObject
QScopedPointer< QObjectData >	d_ptr
Static Protected Variables inherited from QObject
static const QMetaObject	staticQtMetaObject
Related Functions inherited from QObject
T	qFindChildqFindChildren (const QObject *obj, const QString &name)()
QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QString &name)()
QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QRegExp &regExp)()
T *	qobject_cast (QObject *object)
	QObjectList
void *	qt_find_obj_child (QObject *parent, const char *type, const QString &name)
	Returns a pointer to the object named name that inherits type and with a given parent. More...

Detailed Description

The QCopChannel class provides communication capabilities between clients in Qt for Embedded Linux.

Note that this class is only available in Qt for Embedded Linux.

The Qt COmmunication Protocol (QCOP) is a many-to-many protocol for transferring messages across registered channels. A channel is registered by name, and anyone who wants to can listen to the channel as well as send messages through it. The QCOP protocol allows clients to communicate both within the same address space and between different processes.

To send messages to a given channel, QCopChannel provides the static send() function. Using this function alone, the messages are queued until Qt re-enters the event loop. To immediately flush all queued messages to the registered listeners, call the static flush() function.

To listen to the traffic on a given channel, you typically instantiate a QCopChannel object for the given channel and connect to its received() signal that is emitted whenever there is incoming data. Use the static isRegistered() function to query the server for the existence of a given channel. QCopChannel provides the channel() function returning the name of this QCopChannel object's channel.

In additon, QCopChannel provides the virtual receive() function that can be reimplemented to filter the incoming messages and data. The default implementation simply emits the received() signal.

See also

QWSServer, QWSClient, {Qt for Embedded Linux Architecture}

Definition at line 58 of file qcopchannel_qws.h.

Constructors and Destructors

QCopChannel()

QCopChannel::QCopChannel ( const QString &  channel, QObject *  parent = 0  )

explicit

Constructs a QCopChannel object for the specified channel, with the given parent.

Once created, the channel is registered by the server.

See also

isRegistered(), channel()

Definition at line 157 of file qcopchannel_qws.cpp.

                                                                :
    QObject(parent)
{
    init(channel);
}

~QCopChannel()

QCopChannel::~QCopChannel ( )

virtual

Destroys this QCopChannel object.

The server is notified that this particular listener has closed its connection. The server will keep the channel open until the last registered listener detaches.

See also

isRegistered(), channel()

Definition at line 232 of file qcopchannel_qws.cpp.

{
    QMutexLocker locker(qcopClientMapMutex());
    QCopClientMap::Iterator it = qcopClientMap->find(d->channel);
    Q_ASSERT(it != qcopClientMap->end());
    it.value().removeAll(this);
    // still any clients connected locally ?
    if (it.value().isEmpty()) {
        QByteArray data;
        QDataStream s(&data, QIODevice::WriteOnly);
        s << d->channel;
        if (qt_fbdpy)
            send(QLatin1String(""), QLatin1String("detach()"), data);
        qcopClientMap->remove(d->channel);
    }

    delete d;
}

Functions

answer()

void QCopChannel::answer ( QWSClient *  cl, const QString &  ch, const QString &  msg, const QByteArray &  data  )

staticprivate

Server side: transmit the message to all clients registered to the specified channel.

Warning

This function is not part of the public interface.

Definition at line 514 of file qcopchannel_qws.cpp.

Referenced by QWSServerPrivate::invokeQCopSend().

{
    // internal commands
    if (ch.isEmpty()) {
        if (msg == QLatin1String("isRegistered()")) {
            QString c;
            QDataStream s(data);
            s >> c;
            bool known = qcopServerMap && qcopServerMap->contains(c)
                        && !((*qcopServerMap)[c]).isEmpty();
            // Yes, it's a typo, it's not user-visible, and we choose not to fix it for compatibility
            QLatin1String ans = QLatin1String(known ? "known" : "unknown");
            QWSServerPrivate::sendQCopEvent(cl, QLatin1String(""),
                                            ans, data, true);
            return;
        } else if (msg == QLatin1String("detach()")) {
            QString c;
            QDataStream s(data);
            s >> c;
            Q_ASSERT(qcopServerMap);
            QCopServerMap::Iterator it = qcopServerMap->find(c);
            if (it != qcopServerMap->end()) {
                //Q_ASSERT(it.value().contains(cl));
                it.value().removeAll(cl);
                if (it.value().isEmpty()) {
                  // If this was the last client in the channel, announce the channel as dead
                  QWSServerSignalBridge* qwsBridge = new QWSServerSignalBridge();
                  connect(qwsBridge, SIGNAL(removedChannel(QString)), qwsServer, SIGNAL(removedChannel(QString)));
                  qwsBridge->emitRemovedChannel(it.key());
                  delete qwsBridge;
                  qcopServerMap->erase(it);
                }
            }
        if (qcopServerRegexpList && containsWildcards(c)) {
        // Remove references to a wildcarded channel.
        QCopServerRegexpList::Iterator it
            = qcopServerRegexpList->begin();
        while(it != qcopServerRegexpList->end()) {
            if ((*it).client == cl && (*it).channel == c)
            it = qcopServerRegexpList->erase(it);
            else
            ++it;
        }
        }
            return;
        }
        qWarning("QCopChannel: unknown internal command %s", qPrintable(msg));
        QWSServerPrivate::sendQCopEvent(cl, QLatin1String(""),
                                        QLatin1String("bad"), data);
        return;
    }

    if (qcopServerMap) {
        QList<QWSClient*> clist = qcopServerMap->value(ch);
        for (int i=0; i < clist.size(); ++i) {
            QWSClient *c = clist.at(i);
            QWSServerPrivate::sendQCopEvent(c, ch, msg, data);
        }
    }

    if(qcopServerRegexpList && !containsWildcards(ch)) {
    // Search for wildcard matches and forward the message on.
    QCopServerRegexpList::ConstIterator it = qcopServerRegexpList->constBegin();
    for (; it != qcopServerRegexpList->constEnd(); ++it) {
        if ((*it).regexp.exactMatch(ch)) {
        QByteArray newData;
        {
            QDataStream stream
            (&newData, QIODevice::WriteOnly | QIODevice::Append);
            stream << ch;
            stream << msg;
            stream << data;
            // Stream is flushed and closed at this point.
        }
        QWSServerPrivate::sendQCopEvent
            ((*it).client, (*it).channel,
             QLatin1String("forwardedMessage(QString,QString,QByteArray)"),
             newData);
        }
    }
    }
}

channel()

QString QCopChannel::channel

(

)

const

Returns the name of this object's channel.

See also

isRegistered()

Definition at line 257 of file qcopchannel_qws.cpp.

Referenced by init(), isRegistered(), and QCopChannel().

{
    return d->channel;
}

detach()

void QCopChannel::detach ( QWSClient *  cl )

staticprivate

Server side: unsubscribe cl from all channels.

Warning

This function is not part of the public interface.

Definition at line 474 of file qcopchannel_qws.cpp.

Referenced by QWSServerPrivate::_q_clientClosed().

{
    if (!qcopServerMap)
        return;

    QCopServerMap::Iterator it = qcopServerMap->begin();
    for (; it != qcopServerMap->end(); ++it) {
      if (it.value().contains(cl)) {
        it.value().removeAll(cl);
        // If this was the last client in the channel, announce the channel as dead.
        if (it.value().count() == 0) {
          QWSServerSignalBridge* qwsBridge = new QWSServerSignalBridge();
          connect(qwsBridge, SIGNAL(removedChannel(QString)), qwsServer, SIGNAL(removedChannel(QString)));
          qwsBridge->emitRemovedChannel(it.key());
          delete qwsBridge;
        }
      }
    }

    if (!qcopServerRegexpList)
    return;

    QCopServerRegexpList::Iterator it2 = qcopServerRegexpList->begin();
    while(it2 != qcopServerRegexpList->end()) {
    if ((*it2).client == cl)
        it2 = qcopServerRegexpList->erase(it2);
    else
        ++it2;
    }
}

flush()

bool QCopChannel::flush ( )

static

Flushes all queued messages to the registered listeners.

Since

4.2

Note that this function returns false if no QApplication has been constructed, otherwise it returns true.

See also

send()

Definition at line 395 of file qcopchannel_qws.cpp.

{
    if (!qt_fbdpy) {
        qFatal("QCopChannel::flush: Must construct a QApplication "
                "before using QCopChannel");
        return false;
    }

    qt_fbdpy->flushCommands();

    return true;
}

init()

void QCopChannel::init ( const QString &  channel )

private

Definition at line 176 of file qcopchannel_qws.cpp.

Referenced by QCopChannel().

{
    d = new QCopChannelPrivate;
    d->channel = channel;

    if (!qt_fbdpy) {
        qFatal("QCopChannel: Must construct a QApplication "
                "before QCopChannel");
        return;
    }

    {
    QMutexLocker locker(qcopClientMapMutex());

    if (!qcopClientMap)
        qcopClientMap = new QCopClientMap;

    // do we need a new channel list ?
    QCopClientMap::Iterator it = qcopClientMap->find(channel);
    if (it != qcopClientMap->end()) {
        it.value().append(this);
        return;
    }

    it = qcopClientMap->insert(channel, QList< QPointer<QCopChannel> >());
    it.value().append(QPointer<QCopChannel>(this));
    }

    // inform server about this channel
    qt_fbdpy->registerChannel(channel);
}

isRegistered()

bool QCopChannel::isRegistered ( const QString &  channel )

static

Queries the server for the existence of the given channel.

Returns true if the channel is registered; otherwise returns false.

See also

channel(), send()

Definition at line 314 of file qcopchannel_qws.cpp.

{
    QByteArray data;
    QDataStream s(&data, QIODevice::WriteOnly);
    s << channel;
    if (!send(QLatin1String(""), QLatin1String("isRegistered()"), data))
        return false;

    QWSQCopMessageEvent *e = qt_fbdpy->waitForQCopResponse();
    bool known = e->message == "known";
    delete e;
    return known;
}

receive()

void QCopChannel::receive ( const QString &  message, const QByteArray &  data  )

virtual

Processes the incoming message and data.

This function is called by the server when this object's channel receives new messages. Note that the default implementation simply emits the received() signal; reimplement this function to process the incoming message and data.

Note that the format of the given data has to be well defined in order to extract the information it contains. In addition, it is recommended to use the DCOP convention. This is not a requirement, but you must ensure that the sender and receiver agree on the argument types. For example:

void MyClass::receive(const QString &message, const QByteArray &data)
{
    QDataStream in(data);
    if (message == "execute(QString,QString)") {
        QString cmd;
        QString arg;
        in >> cmd >> arg;
        ...
    } else if (message == "delete(QString)") {
        QString fileName;
        in >> fileName;
        ...
    } else {
        ...
    }
}

The above code assumes that the message is a DCOP-style function signature and the data contains the function's arguments.

See also

send(), channel(), received()

Definition at line 289 of file qcopchannel_qws.cpp.

Referenced by sendLocally().

{
    emit received(msg, data);
}

received

void QCopChannel::received ( const QString &  message, const QByteArray &  data  )

signal

This signal is emitted whenever this object's channel receives new messages (i.

e., it is emitted by the receive() function), passing the incoming message and data as parameters.

See also

receive(), channel()

Referenced by receive().

registerChannel()

void QCopChannel::registerChannel ( const QString &  ch, QWSClient *  cl  )

staticprivate

Server side: subscribe client cl on channel ch.

Warning

This function is not part of the public interface.

Definition at line 436 of file qcopchannel_qws.cpp.

Referenced by QWSServerPrivate::invokeRegisterChannel().

{
    if (!qcopServerMap)
        qcopServerMap = new QCopServerMap;

    // do we need a new channel list ?
    QCopServerMap::Iterator it = qcopServerMap->find(ch);
    if (it == qcopServerMap->end())
      it = qcopServerMap->insert(ch, QList<QWSClient*>());

    // If the channel name contains wildcard characters, then we also
    // register it on the server regexp matching list.
    if (containsWildcards( ch )) {
    QCopServerRegexp item(ch, cl);
    if (!qcopServerRegexpList)
        qcopServerRegexpList = new QCopServerRegexpList;
    qcopServerRegexpList->append( item );
    }

    // If this is the first client in the channel, announce the channel as being created.
    if (it.value().count() == 0) {
      QWSServerSignalBridge* qwsBridge = new QWSServerSignalBridge();
      connect(qwsBridge, SIGNAL(newChannel(QString)), qwsServer, SIGNAL(newChannel(QString)));
      qwsBridge->emitNewChannel(ch);
      delete qwsBridge;
    }

    it.value().append(cl);
}

reregisterAll()

void QCopChannel::reregisterAll ( )

static

Warning

This function is not part of the public interface.

Resend all channel registrations

Definition at line 213 of file qcopchannel_qws.cpp.

Referenced by QWSDisplay::Data::reinit().

{
    if(qcopClientMap)
        for(QCopClientMap::Iterator iter = qcopClientMap->begin();
            iter != qcopClientMap->end();
            ++iter)
            qt_fbdpy->registerChannel(iter.key());
}

send() [1/2]

bool QCopChannel::send ( const QString &  channel, const QString &  msg  )

static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 333 of file qcopchannel_qws.cpp.

Referenced by QtopiaPrintEngine::end(), isRegistered(), and ~QCopChannel().

{
    QByteArray data;
    return send(channel, msg, data);
}

send() [2/2]

bool QCopChannel::send ( const QString &  channel, const QString &  message, const QByteArray &  data  )

static

Sends the given message on the specified channel with the given data.

The message will be distributed to all clients subscribed to the channel. Returns true if the message is sent successfully; otherwise returns false.

It is recommended to use the DCOP convention. This is not a requirement, but you must ensure that the sender and receiver agree on the argument types.

Note that QDataStream provides a convenient way to fill the byte array with auxiliary data. For example:

QByteArray data;
QDataStream out(&data, QIODevice::WriteOnly);
out << QString("cat") << QString("file.txt");
QCopChannel::send("System/Shell", "execute(QString,QString)", data);

In the code above the channel is "System/Shell". The message is an arbitrary string, but in the example we've used the DCOP convention of passing a function signature. Such a signature is formatted as "functionname(types)" where types is a list of zero or more comma-separated type names, with no whitespace, no consts and no pointer or reference marks, i.e. no "*" or "&".

See also

receive(), isRegistered()

Definition at line 367 of file qcopchannel_qws.cpp.

{
    if (!qt_fbdpy) {
        qFatal("QCopChannel::send: Must construct a QApplication "
                "before using QCopChannel");
        return false;
    }

    qt_fbdpy->sendMessage(channel, msg, data);

    return true;
}

sendLocally()

void QCopChannel::sendLocally ( const QString &  ch, const QString &  msg, const QByteArray &  data  )

static

Client side: distribute received event to the QCop instance managing the channel.

Warning

This function is not part of the public interface.

Definition at line 606 of file qcopchannel_qws.cpp.

Referenced by QApplication::qwsProcessEvent().

{
    Q_ASSERT(qcopClientMap);

    // filter out internal events
    if (ch.isEmpty())
        return;

    // feed local clients with received data
    QList< QPointer<QCopChannel> > clients;
    {
    QMutexLocker locker(qcopClientMapMutex());
    clients = (*qcopClientMap)[ch];
    }
    for (int i = 0; i < clients.size(); ++i) {
    QCopChannel *channel = (QCopChannel *)clients.at(i);
    if ( channel )
        channel->receive(msg, data);
    }
}

Friends and Related Functions

QApplication

friend class QApplication

friend

Definition at line 99 of file qcopchannel_qws.h.

QWSServer

friend class QWSServer

friend

Definition at line 97 of file qcopchannel_qws.h.

QWSServerPrivate

friend class QWSServerPrivate

friend

Definition at line 98 of file qcopchannel_qws.h.

Properties

d

QCopChannelPrivate* QCopChannel::d

private

Definition at line 95 of file qcopchannel_qws.h.

Referenced by channel(), init(), and ~QCopChannel().

---

The documentation for this class was generated from the following files:

• /src/gui/embedded/qcopchannel_qws.h
• /src/gui/embedded/qcopchannel_qws.cpp