|  | Home |

# Messaging

## Introduction

The Messaging Framework provides the following messaging features:

1. a library for developing applications that work with messages
2. a server application supporting multiple messaging transport mechanisms
3. an example client application supporting common messaging functionality

The Client library provides classes giving access to all messages stored on the device, via a uniform interface. It simplifies the task of creating messaging client applications, and permits other Messaging Framework applications to interact with messaging data where appropriate. New types of messages can be supported by the library without modification to existing client applications.

The MessageServer application is a daemon, designed to run continuously while providing services to client applications. It provides messaging transport functionality, communicating with external servers on behalf of Messaging Framework client applications. New types of messaging (such as Instant Messages or video messages) can be handled by the server application without modification to existing client applications.

The Messages example client application provides an implementation of standard functionality for creating and viewing messages.

## Architecture

The Messaging Framework uses a database to store all messaging-related data. Rather than providing access via Structured Query Language, the Client library wraps the database with classes providing structured, focussed access to the database. Clients can add, remove or update messaging data via the wrapper classes, with appropriate guarantees of isolation, and with automatic propagation of updates between clients.

Clients access messaging data via the Client library which provides a direct connection to the messaging database. Notifications of database changes that occur as a result of other clients' actions are received by IPC, and the messaging library automatically reflects those changes in all clients.

A set of model/view classes are provided for clients to access the messaging data content. A flexible system of filtering and sorting keys is provided, enabling clients to display a specific subset of the library's data with minimal resource overhead.

Rather than requiring each client application to perform transmission and retrieval of messages from external sources, a server application provides these services to any Client library client. The server receives service requests from clients via IPC, and reports events and status information back over the same channel. However, to avoid the overhead of passing message data within the system, the server reads and writes messages directly to and from the messaging database, via the library class interface. Messaging clients do not need to communicate with the server directly.

For detailed information refer to:

- Client library
- MessageServer server daemon
- Messages client application

## Building and Compiling

To build the Messaging Framework, run `qmake` on the top level `messagingframework.pro` file as follows:

        qmake "QMF_INSTALL_ROOT=<image directory path>" messagingframework.pro

Where `<image` `directory` `path>` is the location that `make` `install` will put the resultant binary files. It is optional but desirable to set this variable as it is not possible to run the applications from within their build directories due to dependencies. The `debug` configuration parameter is also optional.

Following this simply run:

        make
        make install

It is also recommended to build in a separate path to the source tree. This is just a matter of running the above commands from within a separate build directory.

Note: If there are build errors referring to valgrind (tst_messageserver), please ensure that valgrind development headers are installed, or optionally remove unwanted tests from the messagingframework.pro.

Note: By default the QMF libraries, messageserver and protocol plugins depend on the QtGui library. This is so that protocol plugins (e.g. IMAP/SMTP/POP) can provide GUI account editors. To remove this dependency use the define QMF_NO_MESSAGE_SERVICE_EDITOR e.g:

        qmake -r messagingframework.pro DEFINES+=QMF_NO_MESSAGE_SERVICE_EDITOR

## Running Messaging Framework

After `make install` has run, the following layout should exist in your image directory:

        bin
        include
        lib
        plugins
        tests

The binary files `messageserver` and `qtmail` and `messagingaccounts` should be located in the `bin` directory. Set the following evironment variables prior to running these files:

        PATH=<imagedir/bin>:$PATH
        LD_LIBRARY_PATH=<imagedir/lib>:$LD_LIBRARY_PATH
        QMF_PLUGINS=<imagedir/plugins>

Optionally set `QMF_DATA` to the location where you want the framework data files stored. If this is not set, the default of `$HOME/.qmf` will be used.

Note: When running the example client application `qtmail`, if the `messageserver` is not already running it will be started as a child process of the application, whose output is not visible. If you prefer to see the output of the `messageserver` daemon, ensure it is running separately before running `qtmail`.

## Testing the Messaging Framework

The messaging framework includes a series of unit tests designed to ensure that it is functioning correctly in an operating environment. Unit tests are located in the `tests` top-level directory.

To run the tests:

        cd tests
        make test

Normal `make` options control the operation of the testing - `-j` controls the number of concurrent tests invoked, `-k` instructs make to keep running in the event of a failure.

Note: some tests alter or remove data from the mailstore they operate against. It is prudent to use a different value for the `QMF_DATA` environment variable when running tests than when operating normally.

To run a single test, perform `make test` within the subdirectory of the relevant test program. For example, to run just the `tst_QMailCodec` test:

        make -C tests/tst_qmailcodec test

To run a single test suite, provide the name of the test suite in the `ARGS` variable:

        make -C test/tst_qmailcodec ARGS="encode" test

To run a single test case, provide the name of the test case in the `ARGS` variable:

        make -C test/tst_qmailcodec ARGS="encode:'one padding byte'" test

## Changes Between Messaging Framework Versions

Historical changes in the Messaging Framework Client Library API are listed in CHANGES.qdoc.

Historical changes in the Message Server Support Library API are listed in CHANGES.qdoc.