/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!

\title MessageServer Daemon
\page messageserver.html
\tableofcontents

\section1 Introduction

The \i MessageServer application provides message transport services to Messaging Framework client applications.  
It can send and retrieve messages of various types, to and from external message service providers such as POP and IMAP servers, or local resources such as a SIM card.
Protocol implementations are loaded from plugin libraries, so that the system can be extended with new services, without modification to the MessageServer application.
 
The MessageServer application is a daemon process; it is designed to be always running and available to client applications.  
If the MessageServer experiences a fault and restarts, clients do not need to re-establish communication with the server process.

\section1 Features 

Messages provides the following features:

\table
\header \o Feature \o Description
\row
\o Send messages 
\o Send messages via the transport mechanism defined for the associated account.
\row
\o Retrieve folder and message lists
\o Report the list of folders and messages available at the server for an account.
\row
\o Retrieve messages
\o Retrieve the content of specified messages from the originating server, either partially or completely.
\row
\o Search messages
\o Search for messages via arbitrary criteria, performed at the originating server.
\row
\o Manage messages
\o Move, copy and delete messages on the originating server.
\row
\o Status reporting
\o Status and progress information is emitted during MessageServer operations, for the benefit of client applications.
\endtable
 
\section1 Accounts 
 
MessageServer supports the following aspects of messaging accounts:

\table
\header \o Feature \o Description
\row
\o Unrestricted accounts 
\o MessageServer supports any number of messaging accounts.
\row
\o Messaging types
\o MessageServer supports accounts using the following messaging types:
\list
\o SMS
\o MMS
\o Email
\o Instant Messaging servics
\endlist
\row
\o Email protocols 
\o The following email protocols are available:
\list
\o POP
\o SMTP
\o IMAP
\endlist
Other protocols can be supported by providing implementations as plugins.
\row
\o Instant Messaging protocols 
\o The following Instant Messaging protocols are available:
\list
\o XMPP (Jabber)
\endlist
Other protocols can be supported by providing implementations as plugins.
\endtable
 
\section1 Interface

MessageServer communicates with clients via QCop. The only supported method of passing messages over this channel is for each client to instantiate an object of the QMailMessageServer class, which converts between IPC messages and local signals and slots.

Some actions of the MessageServer process affect the Messaging Framework data store directly.  A client can respond to these actions by connecting to the relevant signals of the QMailStore class, such as QMailStore::messagesAdded(), and QMailStore::messagesRemoved().

\section1 Dependencies 
MessageServer has the following dependencies:
\list
\o the \l{Messaging Framework Client Library}
\o the \l{Message Server Support Library}
\endlist

\section1 Logging
MessageServer supports runtime-enabled logging. The logging levels in use can be changed by updating the configuration file and sending a HUP signal to the messageserver process.

The config file for logging is located at ~/.config/QtProject/QMF.conf. The logging configuration is in the \c{[Logging]} section. \c{qmaillog.h} defines the categories that can be used.

An example config file follows:

\code
[Logging]
Messaging=0
IMAP=0
SMTP=0
POP=0
\endcode

To inform the messageserver process that the logging levels have been changed you must send it a HUP signal.

\code
killall -HUP messageserver
\endcode

Note that the default for a runtime-enabled logging category in release builds is off and in debug builds
it is on. If a category is defined in the config file that definition will take precedence over the default.

*/
