View source for Development/Tutorials/Decibel/GettingStarted

{{Archived}}

{{TutorialBrowser|

series=Decibel Tutorial|

name=Getting Started with Decibel|

pre=[http://mindview.net/Books/TICPP/ThinkingInCPP2e.html C++], [http://www.trolltech.com/products/qt/ Qt]| 
next=[[Development/Tutorials/Decibel/Handling_TextChannels|Handling TextChannels]]| 

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 [http://telepathy.freedesktop.org/releases/telepathy-gabble/ here].''

== Requirements ==

All demos shipped with Decibel require the Decibel daemon to be up and running. After building Decibel this daemon is located in {{path|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.

# Make one or more of your accounts known to the Account Manager in Decibel. (see decibel_registeraccount_demo).
# List all stored accounts and find the account handle. (See decibel_listaccounts_demo).
# Set the desired presence state of an account to "online" using decibel_setpresence_demo.
# 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).
# 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 <tt>kcmshell4 decibel_accountmanager</tt> if you prefer to use this more convenient method.''

== Demos ==

=== Accounthandling ===

The demos in {{path|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 [[Development/Tutorials/Decibel/GettingStarted#Walkthrough|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: <tt>key=type:value</tt> where type is either <tt>i</tt> for integer values or <tt>s</tt> 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: <tt>decibel_protocol</tt> of type <tt>s</tt> 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 {{path|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 {{path|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 {{path|~/.decibel_contact_data.ini}}. For the contacthandling demos to work you need to set up some contacts in this file. See {{path|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 {{path|demos/simpleclient}} of the build directory) and installs it into {{path|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 {{path|~/.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.