This tutorial is based on the simpleclient demo included with Decibel. An explanation of using the simpleclient demo can be [[Development/Tutorials/Decibel/GettingStarted#simpleclient|found here]].

This tutorial is based on the simpleclient demo included with Decibel. An explanation of using the simpleclient demo can be [[Development/Tutorials/Decibel/GettingStarted#simpleclient|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 [http://websvn.kde.org/trunk/kdereview/decibel/demos/simpleclient here in KDE's SVN Repository].

+

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 [http://websvn.kde.org/trunk/kdesupport/decibel/demos/simpleclient here in KDE's SVN Repository].

==ChannelHandler class==

==ChannelHandler class==

Line 24:

Line 23:

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

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

−

<code cppqt>

+

<syntaxhighlight lang="cpp-qt">

class MyTextChannelHandler : public Decibel::ChannelHandler

class MyTextChannelHandler : public Decibel::ChannelHandler

{

{

Line 43:

Line 42:

QtTapioca::TextChannel * m_channel;

QtTapioca::TextChannel * m_channel;

};

};

−

</code>

+

</syntaxhighlight>

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.

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.

Line 52:

Line 51:

====Constructor====

====Constructor====

−

<code cppqt>

+

<syntaxhighlight lang="cpp-qt">

MyTextChannelHandler::MyTextChannelHandler(QObject * parent) :

MyTextChannelHandler::MyTextChannelHandler(QObject * parent) :

ChannelHandler(parent),

ChannelHandler(parent),

Line 58:

Line 57:

m_channel(0)

m_channel(0)

{ }

{ }

−

</code>

+

</syntaxhighlight>

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>.

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>.

====Destructor====

====Destructor====

−

<code cppqt>

+

<syntaxhighlight lang="cpp-qt">

MyTextChannelHandler::~MyTextChannelHandler()

MyTextChannelHandler::~MyTextChannelHandler()

{ }

{ }

−

</code>

+

</syntaxhighlight>

The destructor is even simpler. We don't need to do anything in it because Qt will handle the deletion of child objects automatically.

The destructor is even simpler. We don't need to do anything in it because Qt will handle the deletion of child objects automatically.

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.

====onCloseChannel()====

====onCloseChannel()====

−

<code cppqt>

+

<syntaxhighlight lang="cpp-qt">

void MyTextChannelHandler::onCloseChannel()

void MyTextChannelHandler::onCloseChannel()

{

{

Line 103:

Line 115:

m_channel = 0;

m_channel = 0;

}

}

−

</code>

+

</syntaxhighlight>

+

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.

====onMessageReceived()====

====onMessageReceived()====

−

<code cppqt>

+

<syntaxhighlight lang="cpp-qt">

void MyTextChannelHandler::onMessageReceived()

void MyTextChannelHandler::onMessageReceived()

{

{

Line 122:

Line 135:

}

}

}

}

−

</code>

+

</syntaxhighlight>

+

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 main.cpp file==

+

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.

−

TODO

+

+

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.

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==

==The .component File==

−

TODO

+

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.

+

<syntaxhighlight lang="ini">

+

[Component]

+

Name=Simpleclient

+

Protocols=

+

Types=0

+

Targets=

+

Service%20Name=org.kde.SimpleClient

+

Object%20Path=/TextChannelHandler

+

</syntaxhighlight>

+

+

The only group in this file is the <tt><nowiki>[Component]</nowiki></tt> group. It contains a series of keys identifying 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==

==The .service File==

−

TODO

+

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

+

+

<syntaxhighlight lang="ini">

+

[D-BUS Service]

+

Name=org.kde.SimpleClient

+

Exec=@INSTALL_DIR@/decibel_simpleclient_demo

+

</syntaxhighlight>

+

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.

==CMakeLists.txt==

==CMakeLists.txt==

−

<code bash>

+

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.

+

<syntaxhighlight lang="cmake">

SET(QT_DONT_USE_QTGUI "YES")

SET(QT_DONT_USE_QTGUI "YES")

INCLUDE(${QT_USE_FILE})

INCLUDE(${QT_USE_FILE})

Line 153:

Line 224:

"${CMAKE_CURRENT_BINARY_DIR}/${SERVICE_FILE}"

"${CMAKE_CURRENT_BINARY_DIR}/${SERVICE_FILE}"

)

)

+

</syntaxhighlight>

+

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

+

+

<syntaxhighlight lang="cpp">

# ######### simpleclient demo #########

# ######### simpleclient demo #########

Line 183:

Line 258:

DESTINATION ${COMPONENT_SEARCH_DIR}

DESTINATION ${COMPONENT_SEARCH_DIR}

)

)

−

</code>

+

</syntaxhighlight>

==Running our Application==

==Running our Application==

−

TODO

+

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>.

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.

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

This method is reimplemented from the Decibel::ChannelHandler interface. It is called when ever a new incoming communication channel (QtTapioca::Channel) 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 Q_ASSERT() to handle them.

Next we check if the m_connection 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 false 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 TextChannel type. So the next step is to try and cast it to a QtTapioca::TextChannel object. We then evaluate if this cast was successful (not = 0) and if it was not, we again return false to reject the channel. If the cast is successful, we assign the QtTapioca::TextChannel object to the member variable m_channel 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 m_connection as well.

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

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

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 pendingMessages() 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 Normal, as oposed to another type like Avatar or Emoticon 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 ping?, we reply with the string pong!.

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

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 .component file. A component file is a simple .ini/.desktop style file.

The contents of our demo application's .component file are as follows.

The only group in this file is the [Component] group. It contains a series of keys identifying our application to Decibel and detailing the funcionality it supports.

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

This is a standard dbus autostart file. It contains the dbus name of our application and the absolute path to it. @INSTALL_DIR 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 CMakeLists.txt file to build it, but will instead explain the important parts of the CMakeLists.txt file as found in the Decibel sources for this subdirectory. For more information on how CMakeLists.txt files work, please see the Introduction to cmake tutorial.

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 simpleclient 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 Getting Started with Decibel. Then you should use another instant messaging program to send the message ping? to that account. The simpleclient demo will reply with the message pong!.