# The KMess Handbook

## Introduction

&kapp; is an instant messaging client that uses the MSN Messenger protocol. It lets you chat with anybody else using MSN Messenger or any other client that uses this protocol.

Features of the program include email notifications, a contact list that can be organized by group or by online/offline, font support in chats, multiple accounts, autologin and much more... .

## Using KMess

Here's a screenshot of &kapp; The main window and contact list

### Standard Features

#### Login

&kapp; stores your saved accounts' unencrypted passwords in the .kde3/share/config/kmessrc file. This is not seen as a security problem since you will have already used a secure password to log into your KDE session. If you do not wish to have your password saved anywhere at all or if you are on a public computer, use the extra fields provided in KMess's startup screen.

The &kapp; startup screen Use the two fields at the bottom of the window if you don't want your account data saved

#### Contact handling

##### How to add a contact?

After a succesful login, look at Actions New Contact . Clicking it you will be asked for the email address of the contact you want to add. After confirming this by clicking OK the contact is added to your contact list.

##### How to remove a contact?

After a successful login, right-click on the contact you would like to remove. Choose "Delete Contact" from the right-click menu. The Contact will be removed from your list of friends but can still be seen among your "Removed" contacts.

##### How to block or unblock a contact?

After a successful login, right-click on the contact you would like to block/unblock. Choose "Block Contact"/"Unblock Contact" from the right click menu. The Contact will be blocked/unblocked.

##### How to move a contact from one group to another

After a successful login, right-click on the contact you would like to move to another group. Choose "Move to group" and then, from the resulting popup menu, choose the group that you'd like to move the contact to. The contact is then moved to the chosen group.

Contacts can be renamed, too. Read more about this feature in the Contact Properties section.

#### Group Handling

##### How to add a group?

After a successful login, look at Actions New Group . After clicking it you will be asked for a name. After confirming your choice by clicking OK you will find a new group in your contact list.

##### How to remove a group?

After a successful login, right-click on the name of the group you would like to remove. Choose "Delete Group" from the right click menu. You will need to confirm the action. Then the group will be deleted.

##### How to rename a group?

After a successful login, right-click on the name of the group you would like to rename. Choose "Rename Group" from the right click menu. You are now asked for the new name of the Group. After confirming the action by clicking OK the group will be renamed.

#### Standard Actions

##### How to sort contacts by Online/Offline or by Groups?

After a successful login, you will find in View Sort by. Choose your prefered mode of sorting your contact list.

##### How to change my status?

There are two ways to change the your current status when you are connected to the MSN Messenger Service. One way is to use the dropdown menu in the main KMess window. The other way is changing the status in Connect from the main KMess window. There are different statuses available:

- Online

- Away

- Away with auto reply

- Be right Back

- Busy

- Out for Lunch

- On the Phone

- Invisible

KMess differentiates between three 'Away's'. The standard 'Away' status is the one you may be familiar with from other MSN Messenger clients. Read more about Away with auto reply and Away-Idle in the Advanced Features.

##### How to start a chat with a contact

After a successful login, double click on an online contact, or choose "Chat" from its right-click menu

##### How to chat with multiple contacts?

Open a chat with a contact as described in How to start a chat with a contact. In the opened chat window, go to Chat Invite. In the submenu choose the contact you want to add to the existing chat. Do this with all contacts you'd like to add.

##### How to save chat sessions?

Click in the chatwindow on Chat Save . Choose the directory where the chat should be saved and give a name for the file. Save the chat now by clicking OK. See also Automatic chat logging.

##### How to enable/disable the sound notofications?

KMess has five different events that are by default set up with sound notifications. These five events are

- A contact has started a chat with you

- A contact has gone offline

- A contact has come online

- You have recieved a new mail

- You have recieved a message from a contact

KMess uses KNotify for it's notifications. You can enable/disable them using the KDE Control Center. Look for the section "Sounds" and from there choose "System Notifications".

##### How to send an email to a contact using my Hotmail Account?

After a successful login, right-click on the contact you wish to write an email to, and click on "Send Email". KMess will automatically open your Hotmail Account with the "Compose" interface and the contact's email address in the "To" line. When you are in a chat you can use the button Send EMail in the contact sidebar to send the person an email as well. See also Email options.

##### How to see the MSN-Profile of a contact?

After a successful login, right-click on the contact you want to see the profile of, and click on "Show Profile". KMess will open - if available - the MSN-Profile of the contact in your prefered web browser. When you are in a chat you can use the button Show Profile in the contact sidebar to open a contact's profile as well.

##### How can I view my personal MSN-Profile?

After a successful login go to Connect Show My Profile. KMess will then open your personal MSN-Profile in your prefered web browser.

##### How can I enter my Hotmail Inbox using KMess?

After a successful login you will find the number of emails in your inbox displayed. Clicking on this information will open your Hotmail Inbox in your prefered web browser.

##### How to search for Contacts in the MSN Member Directory?

In Actions in the main KMess window will you find two entries:

- Search Contact

- Search by Interest

Choose your prefered way of searching for a person. KMess will open the MSN Member Directory with the chosen option in your prefered web browser.

##### Emoticons

KMess comes with the default Emoticons by David Vignoni. The default KMess Emoticons In the chat window you will find a button in the top in the toolbar, with a smilie. Emoticonchooser By clicking this button a dropdown menu will open. Clicking on one emoticon will insert it in your textbox. Sending the message now will display the emoticon in the chat. The default view of the KMess chat window See also Emoticonthemes.

##### File transfer

KMess supports file transfer. Please note, that there are problems if you are behind a router or a NAT. Also, KMess has no proxy support. To send a file to a contact you first have to open a chat with him or her. Go to Chat> Send File . Choose the file you want to send to the contact. . Confirm the action by clicking OK. The file will be transferred.

##### How to delete a saved KMess Profile?

Start KMess and go to the preferences of the profile that you want to be deleted. Click on the Delete. at the bottom of the preferences dialog. You will be asked if you are sure if you want to delete the profile. The changes will applied after restarting KMess.

### Advanced Features

#### Contact Images

KMess now allows you to associate images with particular contacts

A contact online with an associated image

To set an image for a given contact, make a right click on the contact you'd like to specify a picture for. Choose Properties, browse to the picture (in PNG format) you'd like to use for this contact and confirm everything by clicking OK

#### Contact Sounds

KMess now allows you to associate sounds with particular contacts. To set a sound for a given contact, make a right click on the contact you'd like to specify a sound for. Choose Properties, browse to the sound (in Ogg Vorbis format) you'd like to use for this contact and confirm everything by clicking OK. This sound will be played every time now the contact logs in.

#### Emoticonthemes

KMess also supports different emoticon themes, which can be downloaded from the KMess Homepage, or choose Get New Emoticon or Sound Themes in Actions. After downloading a new emoticon theme you need to extract the tar file and copy the emoticons to the ~/.kde/share/apps/kmess/emoticons directory. You could do it like this:

    % mv EMOTICONTHEME.TAR.GZ ~/.kde/share/apps/kmess/emoticons/
    % cd ~/.kde/share/apps/kmess/emoticons/
    % tar -xzvf EMOTICONTHEME.TAR.GZ

The new emoticon theme will be available instantly.

#### Automatic Chat Logging

KMess gives you the opportunity to save all chats by default. To enable this open the preferences for your profile and switch to the "Chat Logging" section. Enable the checkbox "Save all Chats" and specify the directory where you want the chats to be stored. After applying the settings KMess will save all chats automatically.

#### Compact Chat

KMess has a Compact Chat feature. This lets KMess display the messages more compact. Take a look at the screenshot below to see the difference...

The difference between the default and the compact chat format.

#### Timestamps

KMess has a function that displays in every sent and recieved message a timestamp. Take a look at the screenshot below.

A timestamp in a message

#### Away with auto reply

An advanced feature of KMess is the auto reply function. When you set your status to 'Away with auto reply' a window appears and you can type in your auto reply message. This message will be send automatically to every person that starts a chat with you.

#### Away-Idle

KMess differentiates between Away, the status of a contact who has manually set their status to "Away", and Away-Idle, the status of a contact who has gone "Away" because he or she was away from their computer for some time. By default, users are set to switch to "Away-Idle" after 5 minutes of inactivity. This setting can be changed or disabled in the "Alerts" section of the profile settings.

#### Contact Sidebar

You will find the contact sidebar in the chatwindow. You can display or hide it using the button in the toolbar Contact Sidebar or using the menu entry Preferences Show/Hide Contact Sidebar The contact sidebar provides you with information and functions associated with each contact in the chat. It shows the current status of the contacts you are in a conversation with and their nicknames. If you specified a Contact Picture it displays this as well. If you didn't it displays the default picture for "unknown user" of KDE. When the person is writing a message the image gets lighter. Next to the image are two buttons. By clicking the top one it will display the person's profile in your standard web browser. The other one will automatically open your Hotmail Account with the "Compose" interface and the contact's email address in the "To" line. (See Email options as well.). Under the picture is the email address of the person displayed he/she is connected to the MSN Messenger Service with.

The KMess chatwindow with shown contact sidebar

#### Email options

KMess now provides the option to use an optional mail client instead of your Hotmail account. To use eg, KMail instead of Hotmail open your profile preferences ( Actions Accountpreferences YOUR NICKNAME Then change to the tab 'Email' and change the radiobutton from Hotmail to 'use special command'. The enter kmail in the textbox and apply the settings.

#### Contact properties

In the right click menu of your contacts in the contact list will you find a new entry called Properties . Here do you have the option to rename a contact and/or specify a contact image and/or a contact sound

## Developer's Guide to KMess

### The MSN Messenger Protocol

MSN Messenger uses the MSN Messenger protocol. These are defined commands that mostly take the form "XXX info1 info2 info3..." where XXX is a three-letter command designation, such as "MSG" for "message".

You can find the draft document for the messenger protocol here or here. Note that this document concerns the protocol back when your list of contacts was divided into "Online" and "Offline". New commands have been added for groups and other things. I still don't know what all the commands mean, but I presume some of them are for MS Windows specific things like whether your contact has MS NetMeeting and things like that.

An excellent tutorial on how to use this protocol can be found at http://www.razorsoft.net/msnp/draft-movva-msn-messenger-protocol-00.txt.

### Communicating with servers

Messenger communications are implemented through two main kinds of servers. The Notification server is the server through which we sign on and off, get email updates, get contact lists, get contact status changes, or change our own name or status. Chats with other users are done through a Switchboard server. When we want to start a chat with a user, we ask the notification server for the IP and port of a switchboard server and then establish a chat connection through that. The third type of server is the one that is initially connected to, solely to provide the address of the notification server that we will connect to.

The two servers are implemented in two classes, the MsnNotificationConnection and MsnSwitchboardConnection classes. These classes are both descendents of the MsnConnection class because they both share common functions and properties, such as the KExtendedSocket that implements the connection and the openConnection() and closeConnection methods.

When an instance of one of these classes connects to the server, the socket used is set so that it calls a dataReceived() function when data is received. The connection then grabs each message from the data read and parses it individually. Each message will have the 3-letter prefix indicating the type, and the message is then passed to the function getXXX where XXX is the prefix.

Thus the MsnConnection implements the connection to the server and has a virtual parseMessage(message) function that is defined by the child connections so that the message can then be identified by the 3-letter prefixes pertaining to that connection type.

Messages to the server are also sent using the three letter prefix style, which means that each connection class has several putXXX style functions. Though while getXXX functions are always called by parseMessage(), putXXX functions may be called by whatever connection function wants to send the message. Note that all putXXX style functions are private to the class.

When a connection class has received some sort of information from the server, it generally emits a Qt signal with the obtained information. What to do with that information is decided by the connection's owner. What class owns what connection is discussed in the next section.

### My programming style

If you're looking at my source code, I'll give a little info on my programming style.

First of all, the program was written with a tab width of 2. I like using small indentations because of something else you might have noticed, my preference for long, descriptive names. I'm also a big stickler for alphabetical order and try to order all my functions and most of my variable declarations this way. While functionally similar methods may not always end up together in my code, you always know which way to go to find a method.

Next, I try to give name class variables with an underscore, "_" at the end. Function variables without. This is to force home whether you're changing something in a function that will apply to the whole class or not. I try to follow the style guidelines given here: http://www.geosoft.no/style.html. While I follow this naming convention for all classes of my creation, when a class is created by Qt Designer, I sometimes get lazy and use the default names which don't follow the lower-case-first-letter, underscore-at-the-end format.

## Questions and Answers

&reporting.bugs; &updating.documentation;

Why do the emoticons just show up as black squares?

You installed KMess to the wrong directory. Basically, it should be configured to install to your KDE3 directory. Under Mandrake 8.2 and, I believe, the most recent SuSE, you do this with "./configure --prefix=/opt/kde3". Under RedHat and Mandrake 9.0, I believe it's "./configure --prefix=/usr". Basically, it's the directory under which you'll find "share/apps/[a bunch of K programs]"

How do I disable the email notifications?

Open KMess and go to the preferences of your Profile. Disable the Checkbox "Show email information in the contact list" and apply the Settings. KMess will disable the email notifications from now on and will not show it.

How do I disable the notifications of email in other folders, like junk mail?

Open KMess and go to the preferences of your Profile. Disable the Checkbox "Show 'other folders' notifications" and apply the Settings. KMess will disable the email notifications in other folders from now on and will not show it.

How do I disable notification when a contact goes offline?

Open KMess and go to the preferences of your Profile. Go to the "Alerts" section, disable the Checkbox "Show 'Contact is Offline' Notifications" and apply the Settings.

## Credits and License

&kapp;

Program copyright 2002 Mike K. Bennett mkb137b@hotmail.com

The program's coders are:

- Mike K. Bennett mkb137b@hotmail.com

- Michael Curtis mdcurtis@users.sourceforge.net

Code was taken from:

- KMerlin (which provided the original inspiration for this program)

- Kopete (from which the popup balloons were taken)

- KScreensaver (from which idle detection code was taken)

Translators:

- Johanna Gersch (Spanish)

- Jan Toenjes (German) jan.toenjes@web.de

- Gorkem Cetin (Turkish) gorkem@gelecek.com.tr

- Mauricio Rother (Brazilian Portuguese) mauricio@digicomm.com.br

- David Vignoni (Italian) dvgn@libero.it

- J.C.A Javi (more Spanish) yovoya30ks@hotmail.com

- Arend Van Beelen (Dutch) arend@auton.nl

- Mohamed Aser (Arabic)mohasr@link.net

- Park Dong Cheon (Korean)pdc@kaist.ac.kr

- Choplair (French) pachilor@yahoo.co.jp

- Øyvind Sæther (Norsk Bokmål) oyvind@sather.tk

- Rachan Hongpairote (Thai) rachanh@yahoo.com

- Lin Hao Xiang (Chinese) linhaoxiang@hotmail.com

- Jaume Cornado (Catalan) jaumec@lleida.net

- Barbaros Ulutas (more Turkish) tebarul@yahoo.com

- Lars Sommer (Danish) admin@lasg.dk

- Jyri Toomessoo (Estonian) nuubik@hotmail.com

Contributors:

- Laurence Anderson (Original file receive patch) l.d.anderson@warwick.ac.uk

- Alexandre Peixoto Ferreira (Some internationalization fixes)alexandref@o2.net.br

- Choe Hwanjin (Some internationalization fixes)hjchoe@hancom.com

- Scott Morgan (Xinerama fixes)blumf@blumf.freeserve.co.uk

- Dane Harnett (Web design)dynamitedane@hotmail.com

Documentation copyright 2002 Mike K. Bennett mkb137b@hotmail.com

&underFDL; &underGPL;

## Installation

### How to obtain KMess

&kmess; is not yet part of the KDE project, but we can all live in hope, can't we?

It's available thanks to the good people at Sourceforge at http://kmess.sourceforge.net.

### Requirements

In order to successfully use &kmess;, you need KDE 3.0 and Qt 3.something.

### Compilation and Installation

In order to compile and install KMess on your system, type the following in the directory into which you extracted the program:

    % ./configure
    % make
    % make install

Since KMess uses autoconf and automake you should have not trouble compiling it. Should you run into problems please report them to me, mkb137b@hotmail.com.

Note that if KDE is somewhere unusual, you need to specify the prefix in configure. For instance, in Mandrake 8.2, KDE3 is installed in opt/kde3, thus the configure line should be:

    % ./configure --prefix=/opt/kde3

&documentation.index;