<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
  <!ENTITY kmess '<application>KMess</application>'>
  <!ENTITY kapp "&kmess;"><!-- replace kmess here -->
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"><!-- change language only here -->
  
  
  <!-- Do not define any other entities; instead, use the entities
       from kde-genent.entities and $LANG/user.entities. -->
]>
<!-- kdoctemplate v0.8 October 1 1999 
     Minor update to "Credits and Licenses" section on August 24, 2000
     Removed "Revision history" section on 22 January 2001   -->

<!--
This template was designed by: David Rugge davidrugge@mindspring.com
with lots of help from: Eric Bischoff ebisch@cybercable.tm.fr
and Frederik Fouvry fouvry@sfs.nphil.uni-tuebingen.de
of the KDE DocBook team.

You may freely use this template for writing any sort of KDE documentation.
If you have any changes or improvements, please let us know.

In the future, we may want to change from SGML-based DocBook to XML-based
DocBook. To make this change easier, please be careful :
- in XML, the case of the <tags> and attributes is relevant ;
- also, quote all attributes.

Please don't forget to remove all these comments in your final documentation,
thanks ;-).
-->

<!-- ................................................................ -->

<!-- The language must NOT be changed here. -->

<book lang="&language;">

<!-- This header contains all of the meta-information for the document such
as Authors, publish date, the abstract, and Keywords -->

<bookinfo>
<title>The KMess Handbook</title>

<authorgroup>
<author>
<firstname>Mike</firstname>
<othername>K.</othername>
<surname>Bennett</surname>
<affiliation>
<address><email>mkb137b@hotmail.com</email></address>
</affiliation>
</author>
</authorgroup>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

<copyright>
<year>2002</year>
<holder>Mike K. Bennett</holder>
</copyright>
<!-- Translators: put here the copyright notice of the translation -->
<!-- Put here the FDL notice.  Read the explanation in fdl-notice.docbook
     and in the FDL itself on how to use it. -->
<legalnotice>&FDLNotice;</legalnotice>

<!-- Date and version information of the documentation
Don't forget to include this last date and this last revision number, we
need them for translation coordination !
Please respect the format of the date (DD/MM/YYYY) and of the version
(V.MM.LL), it could be used by automation scripts.
Do NOT change these in the translation. -->

<date>08/02/2003</date>
<releaseinfo>1.0</releaseinfo>

<!-- Abstract about this handbook -->

<abstract>
<para>
&kmess; is an instant messaging client using the MSN Messenger protocol.
</para>
</abstract>

<!-- This is a set of Keywords for indexing by search engines.
Please at least include KDE, the KDE package it is in, the name
 of your application, and a few relevant keywords. -->

<keywordset>
<keyword>KDE</keyword>
<keyword>Messenger</keyword>
<keyword>KMess</keyword>
<keyword>Chat</keyword>
<keyword>MSN</keyword>
</keywordset>

</bookinfo>

<!-- The contents of the documentation begin here.  Label
each chapter so with the id attribute. This is necessary for two reasons: it
allows you to easily reference the chapter from other chapters of your
document, and if there is no ID, the name of the generated HTML files will vary
from time to time making it hard to manage for maintainers and for the CVS
system. Any chapter labelled (OPTIONAL) may be left out at the author's
discretion. Other chapters should not be left out in order to maintain a
consistent documentation style across all KDE apps. -->

<chapter id="introduction">
<title>Introduction</title>

<!-- The introduction chapter contains a brief introduction for the
application that explains what it does and where to report
problems. Basically a long version of the abstract.  Don't include a
revision history. (see installation appendix comment) -->

<para>
&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.
</para>
<para>
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... .
</para>
</chapter>

<chapter id="using-kapp">
<title>Using KMess</title>

<!-- This chapter should tell the user how to use your app. You should use as
many sections (Chapter, Sect1, Sect3, etc...) as is necessary to fully document
your application. -->

<para>

<!-- Note that all graphics should be in .png format. Use no gifs because of
patent issues. -->

<screenshot>
<screeninfo>Here's a screenshot of &kapp;</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="kmessmainwindow.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>The main window and contact list</phrase>
	  </textobject>
	</mediaobject>
</screenshot>
</para>


<sect1 id="standart-features">
<title>Standard Features</title>
<para> </para>

<sect2 id="sf-login">
<title>Login</title>
<para>
&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.
</para>
<para>

<screenshot>
<screeninfo> The &kapp; startup screen </screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="kmessstartupscreen.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>Use the two fields at the bottom of the window if you don't want your account data saved </phrase>
	  </textobject>
	</mediaobject>
</screenshot>

</para>

</sect2>


<sect2 id="sf-contacts">
<title>Contact handling</title>

<sect3 id="sf-contacts-add">
<title>How to add a contact?</title>
<para>
  After a succesful login, look at <menuchoice> <guimenu>Actions</guimenu> <guimenuitem>New Contact</guimenuitem> </menuchoice>.
  Clicking it you will be asked for the email address of the contact you want to add. After confirming this
  by clicking <guibutton>OK</guibutton> the contact is added to your contact list.
</para>
</sect3>

<sect3 id="sf-contacts-remove">
<title>How to remove a contact?</title>
<para>
  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.
</para>
</sect3>

<sect3 id="sf-contacts-unblock">
<title>How to block or unblock a contact?</title>
<para>
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.
</para>
</sect3>

<sect3 id="sf-contacts-move">
<title>How to move a contact from one group to another</title>
<para>
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.
</para>

<para>
Contacts can be renamed, too. Read more about this feature in the <link linkend="af-contactproperties"> Contact Properties</link> section.

</para>

</sect3>

</sect2>


<sect2 id="sf-group">
<title>Group Handling</title>
<para> </para>


<sect3 id="sf-group-add">
<title>How to add a group?</title>
<para>
After a successful login, look at <menuchoice> <guimenu>Actions</guimenu> <guimenuitem>New Group</guimenuitem> </menuchoice>.
After clicking it you will be asked for a name. After confirming your choice by clicking <guibutton>OK</guibutton> you will
find a new group in your contact list.

</para>
</sect3>

<sect3 id="sf-group-remove">
<title>How to remove a group?</title>
<para>
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.
</para>
</sect3>

<sect3 id="sf-group-rename">
<title>How to rename a group?</title>
<para>
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 <guibutton>OK</guibutton> the group will be renamed.
</para>
</sect3>
</sect2>

<sect2 id="sf-actions">
<title> Standard Actions </title>

<sect3 id="sf-actions-contactlist">
<title>How to sort contacts by Online/Offline or by Groups?</title>
<para>
After a successful login, you will find in <menuchoice><guimenu>View</guimenu> <guimenuitem>Sort by</guimenuitem></menuchoice>.
Choose your prefered mode of sorting your contact list.
</para>
</sect3>


<sect3 id="sf-actions-changestatus">
<title>How to change my status?</title>
<para>
There are two ways to change the your current status when you are connected to the <ulink url="http://messenger.msn.com">MSN Messenger Service</ulink>.
One way is to use the dropdown menu in the main KMess window. The other way is changing the status in <guimenu>Connect</guimenu> from the main KMess window.
There are different statuses available:

<itemizedlist>
<listitem><para>Online</para></listitem>
<listitem><para>Away</para></listitem>
<listitem><para>Away with auto reply</para></listitem>
<listitem><para>Be right Back</para></listitem>
<listitem><para>Busy</para></listitem>
<listitem><para>Out for Lunch</para></listitem>
<listitem><para>On the Phone</para></listitem>
<listitem><para>Invisible</para></listitem>
</itemizedlist>

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 <link linkend="af-awaywithautoreply">Away with auto reply</link> and <link linkend="af-awayidle">Away-Idle</link> in the Advanced Features.


</para>
</sect3>

<sect3 id="sf-actions-chat">
<title>How to start a chat with a contact</title>
<para>
After a successful login, double click on an online contact, or choose "Chat" from its right-click menu
</para>
</sect3>

<sect3 id="sf-actions-multiplechat">
<title> How to chat with multiple contacts?</title>
<para>
Open a chat with a contact as described in <link linkend="sf-actions-chat">How to start a chat with a contact</link>.
In the opened chat window, go to <menuchoice><guimenu>Chat</guimenu> <guimenuitem>Invite</guimenuitem></menuchoice>.
In the submenu choose the contact you want to add to the existing chat. Do this
with all contacts you'd like to add.

</para>
</sect3>

<sect3 id="sf-actions-savechats">
<title>How to save chat sessions? </title>
<para>
Click in the chatwindow on <menuchoice> <guimenu>Chat</guimenu> <guimenuitem>Save</guimenuitem> </menuchoice>.
 Choose the directory where the chat should be saved
and give a name for the file.  Save the chat now by clicking <guibutton>OK</guibutton>.
See also <link linkend="af-autochattlog">Automatic chat logging</link>.

</para>
</sect3>

<sect3 id="sf-actions-soundnotifications">
<title>How to enable/disable the sound notofications?</title>
<para>
KMess has five different events that are by default set up with sound notifications. These five events are
</para>

<para>
<itemizedlist>
<listitem><para>A contact has started a chat with you</para></listitem>
<listitem><para>A contact has gone offline</para></listitem>
<listitem><para>A contact has come online</para></listitem>
<listitem><para>You have recieved a new mail</para></listitem>
<listitem><para>You have recieved a message from a contact</para></listitem>
</itemizedlist>
</para>

<para>
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".
</para>

</sect3>

<sect3 id="sf-actions-sendmail">
<title>How to send an email to a contact using my Hotmail Account?</title>
<para>
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 <guiicon>Send EMail
<inlinemediaobject> <imageobject> <imagedata fileref="kmesschatwindowcontactsidebaremailbutton.png" format="PNG"/>
</imageobject> </inlinemediaobject> </guiicon> in the <link linkend="af-contactsidebar">contact sidebar</link>
to send the person an email as well. See also <link linkend="af-email">Email options</link>.
</para>
</sect3>

<sect3 id="sf-actions-showcontactprofile">
<title>How to see the MSN-Profile of a contact?</title>
<para>
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 <guiicon>Show Profile <inlinemediaobject> <imageobject>
<imagedata fileref="kmesschatwindowcontactsidebarprofilebutton.png" format="PNG"/> </imageobject>
</inlinemediaobject> </guiicon> in the <link linkend="af-contactsidebar">contact sidebar</link> to open a contact's profile as well.
</para>
</sect3>

<sect3 id="sf-actions-showmyprofile">
<title>How can I view my personal MSN-Profile?</title>
<para>
After a successful login go to <menuchoice><guimenu>Connect</guimenu> <guimenuitem>Show My Profile</guimenuitem></menuchoice>.
KMess will then open your personal MSN-Profile in your prefered web browser.
</para>
</sect3>

<sect3 id="sf-actions-myinbox">
<title>How can I enter my Hotmail Inbox using KMess?</title>
<para>
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.
</para>
</sect3>

<sect3 id="sf-actions-searchmsn">
<title>How to search for Contacts in the MSN Member Directory?</title>
<para>
In <guimenu>Actions</guimenu> in the main KMess window will you find two entries:
</para>

<para>
<itemizedlist>
<listitem><para><guimenuitem>Search Contact</guimenuitem></para></listitem>
<listitem><para><guimenuitem>Search by Interest</guimenuitem></para></listitem>
</itemizedlist>
</para>

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

</sect3>

<sect3 id="sf-actions-emoticons">
<title>Emoticons</title>
<para>
KMess comes with the default Emoticons by David Vignoni.

	<mediaobject>
	  <imageobject>
	    <imagedata fileref="kmessemoticonchooser.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>The default KMess Emoticons</phrase>
	  </textobject>
	</mediaobject>


In the chat window you will find a button in the top in the toolbar, with a smilie. <guiicon>Emoticonchooser
<inlinemediaobject> <imageobject><imagedata fileref="kmessemoticonbutton.png" format="PNG"/> </imageobject>
</inlinemediaobject> </guiicon>  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.


	<mediaobject>
	  <imageobject>
	    <imagedata fileref="kmesschatwindow.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>The default view of the KMess chat window</phrase>
	  </textobject>
	</mediaobject>


See also <link linkend="af-emoticonthemes">Emoticonthemes</link>.

</para>
</sect3>

<sect3 id="sf-actions-filetransfer">
<title>File transfer</title>
<para>
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 <menuchoice><guimenu>Chat></guimenu> <guimenuitem>Send File</guimenuitem> </menuchoice>. Choose the file you want to
send to the contact. <!-- what about this dialog --> . Confirm the action by clicking <guibutton>OK</guibutton>. The file
will be transferred.
</para>
</sect3>

<sect3 id="sf-actions-deleteprofile">
<title>How to delete a saved KMess Profile?</title>
<para>
Start KMess and go to the preferences of the profile that you want to be deleted. Click on the <guibutton>Delete</guibutton>.
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.
</para>
</sect3>

</sect2>

</sect1>

<sect1 id="advanced-features">
<title>Advanced Features</title>
<para>

</para>

<sect2 id="af-contactimages">
<title>Contact Images</title>
<para>
KMess now allows you to associate images with particular contacts
</para>
<para>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="kmesspopupbaloon.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>A contact online with an associated image</phrase>
	  </textobject>
	</mediaobject>
</para>
<para>
To set an image for a given contact, make a right click on the contact you'd like to specify a picture for. Choose
<guimenuitem>Properties</guimenuitem>, browse to the picture (in PNG format) you'd like to use
for this contact and confirm everything by clicking <guibutton>OK</guibutton>
</para>
</sect2>

<sect2 id="af-contactsounds">
<title> Contact Sounds</title>
<para>
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
<guimenuitem>Properties</guimenuitem>, browse to the sound (in Ogg Vorbis format) you'd like to use
for this contact and confirm everything by clicking <guibutton>OK</guibutton>. This sound will be played every time now the contact logs in.
</para>
</sect2>

<sect2 id="af-emoticonthemes">
<title> Emoticonthemes</title>
<para>
KMess also supports different emoticon themes, which can be downloaded from the <ulink url="http://kmess.sourceforge.net">KMess Homepage</ulink>, or choose
<guimenuitem>Get New Emoticon or Sound Themes</guimenuitem> in <guimenu>Actions</guimenu>.

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:


<screen width="40">
<prompt>%</prompt> <userinput>mv EMOTICONTHEME.TAR.GZ ~/.kde/share/apps/kmess/emoticons/</userinput>
<prompt>%</prompt> <userinput>cd ~/.kde/share/apps/kmess/emoticons/</userinput>
<prompt>%</prompt> <userinput>tar <option>-xzvf</option> EMOTICONTHEME.TAR.GZ</userinput>
</screen>



The new emoticon theme will be available instantly.

</para>
</sect2>

<sect2 id="af-autochattlog">
<title>Automatic Chat Logging</title>
<para>
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.
</para>
</sect2>



<sect2 id="af-compactchat">
<title>Compact Chat</title>
<para>
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...
</para>
<para>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="kmesscompactchat.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>The difference between the default and the compact chat format.</phrase>
	  </textobject>
	</mediaobject>
</para>

</sect2>


<sect2 id="af-timestamps">
<title>Timestamps</title>
<para>
KMess has a function that displays in every sent and recieved message a timestamp. Take a look at the screenshot below.
</para>

<para>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="kmesstimestamp.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>A timestamp in a message</phrase>
	  </textobject>
	</mediaobject>
</para>

</sect2>

<sect2 id="af-awaywithautoreply">
<title>Away with auto reply</title>
<para>
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.
</para>
</sect2>


<sect2 id="af-awayidle">
<title>Away-Idle</title>
<para>
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.
</para>
</sect2>

<sect2 id="af-contactsidebar">
<title>Contact Sidebar</title>
<para>
You will find the contact sidebar in the chatwindow. You can display or hide it using the button in the toolbar
<guiicon>Contact Sidebar <inlinemediaobject> <imageobject><imagedata fileref="kmesscontactsidebarbutton.png" format="PNG"/>
</imageobject> </inlinemediaobject> </guiicon> or
using the menu entry <menuchoice> <guimenu>Preferences</guimenu> <guimenuitem>Show/Hide Contact Sidebar</guimenuitem></menuchoice>
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 <link linkend="af-contactimages">Contact Picture</link>
it displays this as well. If you didn't it displays the default picture for "unknown user" of <ulink url="http://www.kde.org">KDE</ulink>.
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 <link linkend="af-email">Email options </link>
as well.). Under the picture is the email address of the person displayed he/she is connected to the MSN Messenger Service with.
</para>

<para>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="kmesschatwindowwithsidebar.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>The KMess chatwindow with shown contact sidebar</phrase>
	  </textobject>
	</mediaobject>
</para>

</sect2>

<sect2 id="af-email">
<title>Email options</title>
<para>
KMess now provides the option to use an optional mail client instead of your <ulink url="http://www.hotmail.com">Hotmail</ulink> account.
To use eg, KMail instead of Hotmail open your profile preferences (<menuchoice> <guimenu>Actions</guimenu>
<guimenuitem>Accountpreferences</guimenuitem> <guisubmenu>YOUR NICKNAME</guisubmenu> </menuchoice>
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.
</para>
</sect2>

<sect2 id="af-contactproperties">
<title>Contact properties</title>
<para>
In the right click menu of your contacts in the contact list will you find a new entry called <guimenuitem>Properties
</guimenuitem>. Here do you have the option to rename a contact and/or specify a <link linkend="af-contactimages">
contact image</link> and/or a <link linkend="af-contactsounds">contact sound</link>
</para>
</sect2>

</sect1>
</chapter>

<chapter id="developers">
<title>Developer's Guide to KMess</title>

<!-- (OPTIONAL) A Programming/Scripting reference chapter should be
used for apps that use plugins or that provide their own scripting hooks
and/or development libraries. -->

<sect1 id="kapp-protocol">
<title>The MSN Messenger Protocol</title>

<para>
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".
</para>
<para>
You can find the draft document for the messenger protocol
<ulink url="http://www.tlsecurity.net/Textware/Misc/draft-movva-msn-messenger-protocol-00.txt">here</ulink> or
<ulink url="http://www.razorsoft.net/msnp/draft-movva-msn-messenger-protocol-00.txt">here</ulink>.
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.
</para>
<para>
An excellent tutorial on how to use this protocol can be found at
<ulink url="http://www.razorsoft.net/msnp/draft-movva-msn-messenger-protocol-00.txt">
http://www.razorsoft.net/msnp/draft-movva-msn-messenger-protocol-00.txt.</ulink>
</para>
</sect1>

<sect1 id="kapp-servers">
<title>Communicating with servers</title>

<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
</sect1>


<sect1 id="kapp-style">
<title>My programming style</title>
<para>
If you're looking at my source code, I'll give a little info on my programming style.
</para>
<para>
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.
</para>
<para>
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: <ulink url="http://www.geosoft.no/style.html">
http://www.geosoft.no/style.html</ulink>. 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.
</para>
</sect1>
<!-- Use refentries to describe APIs.  Refentries are fairly complicated and you
should consult the docbook reference for further details. The example below was
taken from that reference and shortened a bit for readability. -->
</chapter>

<chapter id="faq">
<title>Questions and Answers</title>

<!-- (OPTIONAL but recommended) This chapter should include all of the silly
(and not-so-silly) newbie questions that fill up your mailbox. This chapter
should be reserved for BRIEF questions and answers! If one question uses more
than a page or so then it should probably be part of the
"Using this Application" chapter instead. You should use links to
cross-reference questions to the parts of your documentation that answer them.
This is also a great place to provide pointers to other FAQ's if your users
must do some complicated configuration on other programs in order for your
application work. -->

&reporting.bugs;
&updating.documentation;
<qandaset id="faqlist">
<qandaentry>
<question>
<para>Why do the emoticons just show up as black squares?</para>
</question>
<answer>
<para>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]"</para>
</answer>
</qandaentry>


<qandaentry>
<question>
<para>How do I disable the email notifications?</para>
</question>
<answer>
<para>
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.
</para>
</answer>
</qandaentry>


<qandaentry>
<question>
<para>How do I disable the notifications of email in other folders, like junk mail?</para>
</question>
<answer>
<para>
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.
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para> How do I disable notification when a contact goes offline?</para>
</question>

<answer>
<para>
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.
</para>
</answer>
</qandaentry>



<!--
<qandaentry>
<question>
<para>Why can't I twiddle my documents?</para>
</question>
<answer>
<para>You can only twiddle your documents if you have the foobar.lib
installed.</para>
</answer>
</qandaentry>
-->
</qandaset>
</chapter>

<chapter id="credits">

<!-- Include credits for the programmers, documentation writers, and
contributors here. The license for your software should then be included below
the credits with a reference to the appropriate license file included in the KDE
distribution. -->

<title>Credits and License</title>

<para>
&kapp;
</para>
<para>
Program copyright 2002 Mike K. Bennett <email>mkb137b@hotmail.com</email>
</para>
<para>
The program's coders are:
  <itemizedlist>
    <listitem><para>Mike K. Bennett <email>mkb137b@hotmail.com</email></para></listitem>
    <listitem><para>Michael Curtis <email>mdcurtis@users.sourceforge.net</email></para></listitem>
  </itemizedlist>
</para>
<para>
Code was taken from:
  <itemizedlist>
    <listitem><para>KMerlin (which provided the original inspiration for this program)</para></listitem>
    <listitem><para>Kopete (from which the popup balloons were taken)</para></listitem>
    <listitem><para>KScreensaver (from which idle detection code was taken)</para></listitem>
  </itemizedlist>
</para>
<para>
Translators:
  <itemizedlist>
    <listitem><para>Johanna Gersch (Spanish) </para></listitem>
    <listitem><para>Jan Toenjes (German) <email>jan.toenjes@web.de</email></para></listitem>
    <listitem><para>Gorkem Cetin (Turkish) <email>gorkem@gelecek.com.tr</email></para></listitem>
    <listitem><para>Mauricio Rother (Brazilian Portuguese) <email>mauricio@digicomm.com.br</email></para></listitem>
    <listitem><para>David Vignoni (Italian) <email>dvgn@libero.it</email></para></listitem>
    <listitem><para>J.C.A Javi (more Spanish) <email>yovoya30ks@hotmail.com</email></para></listitem>
    <listitem><para>Arend Van Beelen (Dutch) <email>arend@auton.nl</email></para></listitem>
    <listitem><para>Mohamed Aser (Arabic)<email>mohasr@link.net</email></para></listitem>
    <listitem><para>Park Dong Cheon (Korean)<email>pdc@kaist.ac.kr</email></para></listitem>
    <listitem><para>Choplair (French) <email>pachilor@yahoo.co.jp</email></para></listitem>
    <listitem><para>Øyvind Sæther (Norsk Bokmål) <email>oyvind@sather.tk</email></para></listitem>
    <listitem><para>Rachan Hongpairote (Thai) <email>rachanh@yahoo.com</email></para></listitem>
    <listitem><para>Lin Hao Xiang (Chinese) <email>linhaoxiang@hotmail.com</email></para></listitem>
    <listitem><para>Jaume Cornado (Catalan) <email>jaumec@lleida.net</email></para></listitem>
    <listitem><para>Barbaros Ulutas (more Turkish) <email>tebarul@yahoo.com</email></para></listitem>
    <listitem><para>Lars Sommer (Danish) <email>admin@lasg.dk</email></para></listitem>
    <listitem><para>Jyri Toomessoo (Estonian) <email>nuubik@hotmail.com</email></para></listitem>
</itemizedlist>
</para>
<para>
Contributors:
<itemizedlist>
  <listitem><para>Laurence Anderson (Original file receive patch) <email>l.d.anderson@warwick.ac.uk</email>      </para></listitem>
  <listitem><para>Alexandre Peixoto Ferreira (Some internationalization fixes)<email>alexandref@o2.net.br</email></para></listitem>
  <listitem><para>Choe Hwanjin (Some internationalization fixes)<email>hjchoe@hancom.com</email>                 </para></listitem>
  <listitem><para>Scott Morgan (Xinerama fixes)<email>blumf@blumf.freeserve.co.uk</email>                        </para></listitem>
  <listitem><para>Dane Harnett (Web design)<email>dynamitedane@hotmail.com</email>                               </para></listitem>
</itemizedlist>
</para>
<!--
<para>
Contributors:
<itemizedlist>
<listitem><para>Konqui the KDE Dragon <email>konqui@kde.org</email></para>
</listitem>
<listitem><para>Tux the Linux Penguin <email>tux@linux.org</email></para>
</listitem>
</itemizedlist>
</para>
-->
<para>
Documentation copyright 2002 Mike K. Bennett <email>mkb137b@hotmail.com</email>
</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;               <!-- FDL: do not remove. Commercial development should -->
<!-- replace this with their copyright and either remove it or re-set this.-->

<!-- Determine which license your application is licensed under,
     and delete all the remaining licenses below:

     (NOTE:  All documentation are licensed under the FDL,
     regardless of what license the application uses) -->

&underGPL;        	 <!-- GPL License -->

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-kmess">
<title>How to obtain KMess</title>

<para>
&kmess; is not yet part of the KDE project, but we can all live in hope, can't we?
</para>
<para>
It's available thanks to the good people at Sourceforge at
<ulink url="http://www.kmess.sourceforge.net">http://kmess.sourceforge.net</ulink>.
</para>
</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<!--
List any special requirements for your application here. This should include:
.Libraries or other software that is not included in kdesupport,
kdelibs, or kdebase.
.Hardware requirements like amount of RAM, disk space, graphics card
capabilities, screen resolution, special expansion cards, etc.
.Operating systems the app will run on. If your app is designed only for a
specific OS, (you wrote a graphical LILO configurator for example) put this
information here.
-->

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

<!-- For a list of updates, you may refer to the application web site
or the ChangeLog file, or ... -->
<!--
<para>
You can find a list of changes at <ulink
url="http://apps.kde.org/kapp">http://apps.kde.org/kapp</ulink>.
</para>
-->
</sect1>
<sect1 id="compilation">
<title>Compilation and Installation</title>

<para>
In order to compile and install KMess on your system, type the following in the directory
into which you extracted the program:
<screen width="40">
<prompt>%</prompt> <userinput>./configure</userinput>
<prompt>%</prompt> <userinput>make</userinput>
<prompt>%</prompt> <userinput>make install</userinput>
</screen>
</para>

<para>Since KMess uses autoconf and automake you should have not trouble compiling it.
Should you run into problems please report them to me, <email>mkb137b@hotmail.com</email>.
</para>
<para>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:
<screen width="40">
<prompt>%</prompt> <userinput>./configure <option>--prefix=/opt/kde3</option></userinput>
</screen>
</para>
</sect1>
<!--
<sect1 id="configuration">
<title>Configuration</title>

<para>Don't forget to tell your system to start the <filename>dtd</filename>
dicer-toaster daemon first, or KApp won't work !</para>

</sect1>
-->
</appendix>

&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->













