Note: You might want to also check Decibel's Gitting Started Tutorial at KDE Techbase.

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

Note: Decibel is software under active development. This release is meant as a proof-of-concept implementation and was made public for developers to look at. This release is not meant for end users.

Note: This guide assumes that you have the Gabble connection manager from Telepathy installed. Other connection managers like haze, butterfly and others should work as well but are not as well tested.

Requirements

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

The Decibel daemon in turn requires a D-Bus session bus. Please see the manual page of dbus-launch if you need help setting up this service.

Walkthrough

This section gives a recommendation on which demos to run.

Store one of your registered accounts in the Decibel account manager (see decibel_registeraccount_demo).
List the stored accounts and note down the account handle (see decibel_listaccounts_demo).
Set the presence state of the account using the decibel_setpresence_demo.
Connect to the account using some other account and your favourite IM Client. Send a "ping?" message. Decibel will respond with a "pong!" (see decibel_simpleclient_demo).
Use Decibel to connect to your other account (see decibel_chatstarter_demo).

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.

decibel_registeraccount_demo

Warning: At this time passwords that are part of the account data are stored in clear text in the configuration files of the Decibel daemon. This will be fixed before Decibel 1.0.

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, b> for bools (true or false) 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

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.


Warning: 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: At this point in time the integration of Decibel with
the PIM system is not implemented yet. The SimplisticContactConnector
is 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. 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.