Development/Tutorials/Decibel/Handling TextChannels

< Development‎ | Tutorials
Revision as of 19:13, 29 June 2011 by Neverendingo (Talk | contribs) (Text replace - "<code cppqt>" to "<syntaxhighlight lang="cpp-qt">")

Jump to: navigation, search
Handling TextChannels
Tutorial Series   Decibel Tutorial
Previous   C++, Qt, Getting Started with Decibel
What's Next  
Further Reading   CMake


This tutorial will walk you through the process of creating a simple application that uses Decibel's TextChannels to communicate via arbitrary instant messaging networks using telepathy. From the result of this tutorial, only a few more lines of code are needed to produce a functioning text based instant messaging client.

This tutorial is based on the simpleclient demo included with Decibel. An explanation of using the simpleclient demo can be found here.

In this tutorial, we only pick out the important parts of the source code to discuss. The complete working source code for this example can be found here in KDE's SVN Repository.

ChannelHandler class

The first class we will need to create is an implementation of the Decibel::ChannelHandler interface.

The Class Definition

Here is the class definition for our implementation of the Decibel::ChannelHandler interface. It is explained below.

class MyTextChannelHandler : public Decibel::ChannelHandler

    explicit MyTextChannelHandler(QObject * parent = 0);

    bool handleChannel(QtTapioca::Connection *, QtTapioca::Channel *, const bool);

public slots:
    void onMessageReceived();
    void onCloseChannel();

    QtTapioca::Connection *  m_connection;
    QtTapioca::TextChannel * m_channel;

We must inherit from <tt>Decibel::ChannelHandler</tt> which is the interface definition for handling incoming Channels. We reimplement the constructor, Destructor and the <tt>handleChannel()</tt> method as well as adding two slots of our own. We also create the member variables <tt>m_connecion</tt> and <tt>m_channel</tt> which will hold the <tt>QtTapioca::Connection</tt> and <tt>QtTapioca::Channel</tt> objects that are received by the <tt>handleChannel</tt> method.

===The Class Implementation===

Now that we have defined our <tt>Decibel::ChannelHandler</tt> subclass, we need to implement its methods.

<syntaxhighlight lang="cpp-qt">
MyTextChannelHandler::MyTextChannelHandler(QObject * parent) :
{ }
The constructor is very simple. We just pass the <tt>parent</tt> object on to the parent class and initialise our member variables to <tt>0</tt>.

<syntaxhighlight lang="cpp-qt">
{ }
The destructor is even simpler. We don't need to do anything in it because Qt will handle the deletion of child objects automatically.

<syntaxhighlight lang="cpp-qt">
bool MyTextChannelHandler::handleChannel(QtTapioca::Connection * connection,
                                         QtTapioca::Channel * channel,
                                         const bool)
    Q_ASSERT(connection != 0);
    Q_ASSERT(channel != 0);

    if (m_connection != 0) { return false; }

    m_channel = dynamic_cast<QtTapioca::TextChannel*>(channel);
    if (m_channel == 0)
        return false;
    m_connection = connection;

    connect(m_channel, SIGNAL(messageReceived(const QtTapioca::TextChannel *, const QtTapioca::TextChannel::Message &)),
            this, SLOT(onMessageReceived()));
    connect(m_channel, SIGNAL(closed()), this, SLOT(onCloseChannel()));


    return true;
This method is reimplemented from the <tt>Decibel::ChannelHandler</tt> interface. It is called when ever a new incoming communication channel (<tt>QtTapioca::Channel</tt>) comes into existence. In this method, we must decide whether to accept the incoming channel, and if so, to deal with it appropriately.

First we check the incoming channel and connection objects are not invalid (=0) and we fail if this is the case. In a proper application, these error cases should be handled more gracefully, but for the purpose of this demo, we will just use <tt>Q_ASSERT()</tt> to handle them.

Next we check if the <tt>m_connection</tt> member variable is set to 0. If it is not, then we are already handling a channel. This demo can only handle one channel at a time, so we return <tt>false</tt> to reject the new incoming channel.

There are multiple types of channel we could possible receive. In this demo we are only interested in the <tt>TextChannel</tt> type. So the next step is to try and cast it to a <tt>QtTapioca::TextChannel</tt> object. We then evaluate if this cast was successful (not = 0) and if it was not, we again return <tt>false</tt> to reject the channel. If the cast is successful, we assign the <tt>QtTapioca::TextChannel</tt> object to the member variable <tt>m_channel</tt> to store it.

Now that we are sure the incoming channel is one we want to handle, we assign the incoming connection object to a member variable <tt>m_connection</tt> as well.

We are also ready to connect the channel's signals to the slots in our class. We connect the channel's <tt>messageReceived()</tt> signal to our <tt>onMessageReceived()</tt> slot, and the channel's <tt>closed()</tt> signal to our <tt>onCloseChannel()</tt> slot.

Finally, we call the <tt>onMessageReceived()</tt> slot to process any messages that have already arrived on the channel, before returning <tt>true</tt> to tell Decibel that we have accepted the channel and are handling it.

<syntaxhighlight lang="cpp-qt">
void MyTextChannelHandler::onCloseChannel()
    m_connection = 0;
    m_channel = 0;
This slot is called when the current TextChannel is closed. It resets the <tt>m_connection</tt> and <tt>m_channel</tt> member variables to <tt>0</tt> so that the <tt>handleChannel()</tt> method will accept the next incoming channel.

<syntaxhighlight lang="cpp-qt">
void MyTextChannelHandler::onMessageReceived()
    QList<QtTapioca::TextChannel::Message> message_list = m_channel->pendingMessages();

    for (QList<QtTapioca::TextChannel::Message>::const_iterator
             message = message_list.constBegin();
         message != message_list.constEnd(); ++message)
        if (message->type() == QtTapioca::TextChannel::Message::Normal &&
            message->contents() == QString("ping?"))
        { m_channel->sendMessage(QString("pong!")); }

This slot is called when a new message is received on the channel we are currently handling. It is where the processing of the message takes place.

The first thing we do is to call the <tt>pendingMessages()</tt> method of the channel to receive *all* the unprocessed received messages on that channel.

Next we iterate over the list of these messages. For each message in the list, we check that it is a message of type <tt>Normal</tt>, as oposed to another type like <tt>Avatar</tt> or <tt>Emoticon</tt> which we are not interested in for this tutorial.

If it is a normal type of message, we check its contents, and if they are the string <tt>ping?</tt>, we reply with the string <tt>pong!</tt>.

We then call the <tt>acknowledge()</tt> method on the channel to confirm to the sender that we received the message.

==The main() function==

<syntaxhighlight lang="cpp-qt">
int main(int argc, char ** argv)
    QCoreApplication app(argc, argv);

    MyTextChannelHandler thandler(&app);


    QDBusConnection::sessionBus().registerService(Decibel::organisation_name + '.' + "SimpleClient");
    QDBusConnection::sessionBus().registerObject("/TextChannelHandler", thandler);

    return app.exec();
Since this is a console application, we set up a <tt>QCoreApplication</tt> first.

Then we create an instance of the <tt>MyTextChannelHandler</tt> (which is our implementation of the <tt>Decibel::ChannelHandler</tt> interface).

Before registering any of the DBus interfaces for our app, it is necessary to call <tt>Decibe::registerTypes()</tt> to set up the types used by Decibel.

Next we register our application as a DBus service, and a <tt>TextChannelHandler</tt> so that decibel can communicate with it and can pass incoming TextChannels to it.

Finally, we start the application event-loop.

==The .component File==
Since we want Decibel to pass incoming channels to our application, we need to tell it that our program exists. We do this by creating a <tt>.component</tt> file. A component file is a simple <tt>.ini</tt>/<tt>.desktop</tt> style file.

The contents of our demo application's <tt>.component</tt> file are as follows.
<code ini>

The only group in this file is the <tt><nowiki>[Component]</nowiki></tt> group. It contains a series of keys idntifying our application to Decibel and detailing the funcionality it supports.

In this example, the important keys are the <tt>Service%20Name</tt> which tells Decibel the dbus name of our application, and the <tt>Object%20Path</tt> which tells Decibel the dbus object path that should be called on our application.

==The .service File==
In order to have dbus automatically start our application when Decibel tries to communicate with it, we must create a <tt>.service</tt> file.

<code ini>
[D-BUS Service]
This is a standard dbus autostart file. It contains the dbus name of our application and the absolute path to it. <tt>@INSTALL_DIR</tt> will be replaced automatically by the installation directory using cmake in the next step.

Since this example program is built as part of the main Decibel sources, I will not explain here how to create a standalone <tt>CMakeLists.txt</tt> file to build it, but will instead explain the important parts of the <tt>CMakeLists.txt</tt> file as found in the Decibel sources for this subdirectory. For more information on how <tt>CMakeLists.txt</tt> files work, please see the [[Development/Tutorials/CMake|Introduction to cmake]] tutorial.
<code bash>

SET(SERVICE_FILE "org.kde.SimpleClient.service")



The <tt>CONFIGURE_FILE</tt> line above tells cmake tp fill in the variable to the <tt>.service.cmake</tt> file we previously created.

<code bash>
# ######### simpleclient demo #########



QT4_WRAP_CPP(simpleclient_MOC_SRCS ${simpleclient_MOC_HDRS})

ADD_EXECUTABLE(decibel_simpleclient_demo ${simpleclient_SRCS}

INSTALL(FILES org.kde.SimpleClient.TextChannel.component

==Running our Application==
In this tutorial, we have only looked at the important parts of the code of this application. The easiest way to build a working example from this tutorial is to check out the Decibel source code from the KDE SVN repository. The <tt>simpleclient</tt> demo which this tutorial explains will be built and installed automatically along with the rest of Decibel.

To see it working, you need to register an account with Decibel and bring it online. For information on how to do this, please see [[Development/Tutorials/Decibel/GettingStarted|Getting Started with Decibel]]. Then you should use another instant messaging program to send the message <tt>ping?</tt> to that account. The <tt>simpleclient</tt> demo will reply with the message <tt>pong!</tt>.

Content is available under Creative Commons License SA 4.0 unless otherwise noted.