Development/Tutorials/Decibel/GettingStarted

Getting Started with Decibel

Tutorial Series	Decibel Tutorial
Previous	C++, Qt
What's Next	Handling TextChannels
Further Reading

Getting started with Decibel

This is a short tutorial describing how to set up the Decibel realtime communication system. It is intended for developers interested in working on or with Decibel.

Note: Decibel is no IM client. You can not use Decibel to chat with your friends without additional software!

Note: This guide assumes that you have the telepathy Gabble connection manager installed which enables Jabber access. Other connection managers may work as well, but are not as well tested. Telepathy Gabble is part of most recent linux distributions and can be found here.

Requirements

All demos shipped with Decibel require the Decibel daemon to be up and running. After building Decibel this daemon is located in src/server/decibel. The daemon does (so far) not fork and blocks the terminal it is run from: Very useful behaviour when debugging problems.

The Decibel daemon in turn requires an active D-Bus session bus. This is a precondition for all KDE 4 applications, so it is mentioned for completeness sake only.

Walkthrough

This section describes a sequence of command line demos recommended to try and test decibel.

1. Make one or more of your accounts known to the Account Manager in Decibel. (see decibel_registeraccount_demo).
2. List all stored accounts and find the account handle. (See decibel_listaccounts_demo).
3. Set the desired presence state of an account to "online" using decibel_setpresence_demo.
4. Have someone connect to and send a "ping?" message to your now online account. Decibel will launch a ping-handler which in turn will reply with a "pong!". See decibel_simpleclient_demo).
5. Use Decibel to connect to other accounts. See decibel_chatstarter_demo.

Note: Steps 1 to 3 can be done using the account manager KControl module as well. Run kcmshell4 decibel_accountmanager if you prefer to use this more convenient method.

Demos

Accounthandling

The demos in demos/accounthandling are showing how to manipulate the account storage of the Decibel daemon. They can be used as simple command line tools to manipulate accounts known to Decibel.

Please note that the accountmanager KControl Module that is installed together with Decibel provides the same functionality as these command line demos. See the Walkthrough section for instructions on how to use the KControl module.

decibel_registeraccount_demo

Warning: When not using KDE4, then passwords that are part of the account data are stored in clear text in the configuration files of the Decibel daemon. When KDE4 is found during configuration of Decibel then KWallet is used to store passwords in a secure location.

This demo registers an account with the Decibel daemon. Note that this command does not create new accounts and can only register already existing accounts with Decibel.

The demo expects several sets of key-value pairs. These are of the following form: key=type:value where type is either i for integer values or s for string values. Other types are not supported by this simplistic demo.

You must register all the keys the connection manager you wish to use for the account requires (see the documentation of the connection manager for a complete list). In addition to those settings Decibel requires a further key-value pair: decibel_protocol of type s containing the protocol this account is for.

decibel_deleteaccount_demo

This demo removes a account from Decibel's account storage. This demo expects a account handle (see decibel_listaccounts_demo) and removes the account associated with that handle.

decibel_listaccounts_demo

The listaccounts demo prints a list of all accounts known to Decibel together with the account handle associated with it. It expects no parameters.

decibel_setpresence_demo

The instructions for using this demo are currently incorrect due to changes to the Telepathy API.

This demo is used to manipulate the presence state of an account managed by Decibel.

It expects two parameters and accepts an optional third. The first is the handle to the account to change (see decibel_listaccounts_demo). The second is the new presence level. This is an integer value in the range of 1 to 6. 1 is Offline, 2 Available, 3 Away, 4 XA, 5 Hidden and 6 Busy.

The optional third argument is a presence message.

Note: Changing the presence state from 1 to any other valid value causes Decibel to create a connection to the server the account is for. Changing from a valid value not equal to 1 to 1 disconnects the account again.

Protocolhandling

The demos in demos/protocolhandling can be used to examine various settings on the Telepathy Connection Managers.

decibel_listcms_demo

This demo lists all Telepathy Connection Managers installed in the system. This demo does not expect any parameters.

decibel_supportedprotocols_demo

This demo lists all protocols supported by Telepathy Connection Managers installed on the system. This demo does not expect any parameters.

decibel_listcmsfor_demo

This demo lists all Telepathy Connection Managers installed in the system that support a protocol. This protocol has to be given as the first parameter to the demo.

decibel_defaultcmfor_demo

This demo expects a protocol name as its only argument. It reports the Telepathy connection manager configured in Decibel to handle all connections made using this protocol.

decibel_setdefaultcmfor_demo

This demo expects two parameters. The first is a protocol name and the second a name of a Telepathy Connection Manager installed.

Using this demo the Connection Manager used by Decibel to handle a protocol can be changed. By default one of the possible Connection Managers is chosen for each protocol supported.

Contacthandling

The demos in demos/contacthandling can be used to create connections to contacts. Decibel communicates with the users personal information management (PIM) system to get contact data and identifies contacts by the IDs they got in that system.

Note: Proper integration into KDE4's Akonadi is still in development.

Note: If you have not choosen to integrate Decibel with the KDE 4 environment then the SimplisticContactConnector was configured to provide a really simplistic contact management tool. It reads contact data from an INI file in ~/.decibel_contact_data.ini. For the contacthandling demos to work you need to set up some contacts in this file. See docs/examples/decibel_contact_data.ini for an example file.

decibel_chatstarter_demo

This demo expects an account handle (see decibel_listaccounts_demo) and a contact ID from the connected PIM system (or the INI file of the SimplisticContactConnector).

I will cause Decibel to bring up the account associated with the account handle checks whether the contact of the given ID is on line and sends him a little ping-message.

simpleclient

By default the decibel_simpleclient_demo is started on incoming (jabber) connections by the Decibel daemon. It uses D-Bus activation for this, so a .service file needs to be installed into a D-Bus service directory. During installation Decibel creates such a file (in demos/simpleclient of the build directory) and installs it into share/dbus-1/services. This directory should work out fine if Decibel is installed alongside KDE4.

If the simpleclient is not started on incoming jabber channels, then you might want to copy the .service file into the ~/.local/dbus-1/services directory and try again.

As its name advertises this client is pretty simple: It sends a "pong!" message in response to every "ping?" message it receives.