/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** 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 Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example keepintouch
    \title 'Keep in Touch' Example

    This example demonstrates using the QtMobility Messaging API to
    extract useful information from the messages stored by the system.

    \image keepintouch-example.png

    The 'Keep in Touch' application locates people you have sent messages
    to in the past, but with whom you have not communicated recently.  It
    defines a user-selected date range in the past, beginning a certain
    amount of time ago and finishing more recently.  Any address that you
    sent a message to in this period is located.  Any address that you
    sent a message to more recently than this period will not be displayed.
    So, now might be a good time to say hello to the people whose addresses
    are reported!

    We find addresses when the user clicks the Search button.  First of all
    we find the dates that define the period that the user has selected.

    \snippet    ../../examples/keepintouch/addressfinder.cpp create-date-range

    We create filter objects that will constrain our message search to
    the date range that the user has selected:

    \snippet    ../../examples/keepintouch/addressfinder.cpp create-simple-filters

    Now we combine our filters to precisely specify the messages that we
    would like to inspect to perform our address search:

    \snippet    ../../examples/keepintouch/addressfinder.cpp create-composite-filters

    Now that we know what messages to search for, we use an instance of
    QMessageService to perform our first search:

    \snippet    ../../examples/keepintouch/addressfinder.cpp begin-search

    We could have queried the QMessageManager instance directly using the
    \l{QMessageManager::queryMessages()}{queryMessages} function, but that
    would keep our UI thread busy, and we wouldn't be able to keep our UI
    functioning at the same time.  Using the QMessageService interface
    allows us to process the search asynchronously.

    We receive the notification of matching messages by responding to the
    QMessageService::messagesFound() signal:

    \snippet    ../../examples/keepintouch/addressfinder.cpp accumulate-matches

    When the search is completed, the QMessageService::stateChanged()
    signal is emitted.  If the user specified an exclusion period then we have
    to perform two searches, so when the first finishes our handler initiates
    the second; when the second finishes, we begin processing the results:

    \snippet    ../../examples/keepintouch/addressfinder.cpp handle-search-result

    The \c continueSearch function processes the results of our searches, one
    message at a time.  Each address we sent a message to in the excluded
    time period is added to our exclusion list.  For each address we sent a
    message to in our included time period, and which is not in the exclusion
    list, we create a set of the messages that we sent to that address.

    \snippet    ../../examples/keepintouch/addressfinder.cpp continue-search

    We will display the resulting list of contacts in our Contacts pane.  If the
    system contains a contact definition that matches the address information
    we extracted, we will display the label for that contact - this matching
    process can be accomplished using the QtMobility Contacts API.  If we can't
    find a matching contact, we fall back to using the raw address information
    for display:

    \snippet    ../../examples/keepintouch/addressfinder.cpp contact-lookup

    If the user selects one of these contact addresses, we fill the Messages
    combo box with the list of messages that were previously sent to that contact:

    \snippet    ../../examples/keepintouch/addressfinder.cpp address-selected

    When the user has selected a message, two further actions become possible.
    We can use the QMessageService facility to either view the message
    or to compose a new message to the recipient of the earlier message. To
    view the message we only need to invoke the
    \l {QMessageService::show()}{show} function for the relevant QMessageId:

    \snippet    ../../examples/keepintouch/addressfinder.cpp show-message

    To compose a response, we will create a new message that forwards the
    existing message content to the same recipient, and requests that the
    system display a message composer prepared with the message content we
    have prepared:

    \snippet    ../../examples/keepintouch/addressfinder.cpp compose-message
*/