KMess - MSN Messenger client for Linux

1.5

About KMess

KMess is a MSN Messenger client for Linux. It enables Linux users to chat with friends online who are using MSN Messenger in Windows or Mac OS. The strength of KMess is it's integration with the KDE desktop environment, focus on MSN Messenger specific features and an easy-to-use interface.

About this documentation

This documentation is written towards developers, to be used as reference manual when writing code for KMess. As new developer, it's recommended to have a global understanding of the class structure KMess uses. This API documentation was created to lower that bar, so it becomes easier to contribute code back to KMess. A global introduction to KMess development process can be found online at:

http://www.kmess.org/development/

These pages document the classes and functions KMess is build from. The documentation also provides insight in the relation and interaction between classes, reasons behind a certain implementation, and aids developers to determine how code can be written. Because KMess is built on top of the KDE and Qt libraries, it's important to have a general understanding of the KDE and Qt libraries too:

About the MSN protocol

Most knowledge about the MSN protocol has been reverse engineered. There is no official documentation about how things are supposed to operate, and how clients should respond in certain situations.

Parts of the protocol are being documentated in a wiki-style site at: http://msnpiki.msnfanatic.com/ Other sites scattered arround the net also provide documentation about specialized parts of the protocol. These sites are listed at our development page, but hopefully this information will be merged with the msnpiki documentation soon.

To monitor the data exchanged between clients and servers, we use network sniffers (Ethereal). The debugging tools also help to see the exchanged data.

Debugging practices

Working with an undocumented protocol also means developers need to take care of situations that can't be forseen. It's impossible to make guesses about error handling; e.g. having a list of things which the server may send differently. Code needs to verify it's boundaries, and warn (e.g. with kdWarning()) when received data can't be processed correctly.

The code is filled with assertion tests and strict validations of the data being parsed. This is required to verify whether the application communicates with the servers as it should. For example, an 'if-else-if' always ends with a final 'else' to trap unforceen situations. The P2P classes contain lots of code to detect the exact message type received. Whenever possible, try to reproduce errors to test the code throughly.

To prevent crashes in unexpected situations, tests are added to detect null-pointers and warn appropriately. As rule of thumb:

Normal debugging messages are displayed with kdDebug().
Serious errors are displayed with kdWarning().
Debugging messages should only be displayed when the program is compiled in debug mode.
Warning messages may also be displayed by the final packaged executable.
Null pointers are checked using: if(KMESS_NULL(..)) return;.

When KMess is compiled in debug mode, the debug code between the #ifdef KMESSTEST and #ifdef KMESSDEBUG_... statements will be compiled. The macros for these statements are found in kmessdebug.h. The debug mode can be enabled in two ways:

in KDevelop, select the 'debug' build configuration.
for manual compiling, use CXXFLAGS="-g -ansi -pedantic -Wall" ./configure --enable-debug-output --enable-debug=full.

The debug mode adds:

filenames and line numbers to crash dumps.
filenames and line numbers to the KMESS_NULL macro output.
assertion tests to most functions.
verbose messages so code execution can be traced.
debug window to analyse the network traffic.

A special KMessTest class can be used to create use-case tests. This class can be activated by both disabling and uncommenting the various lines in main.cpp.