/****************************************************************************
**
** 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$
**
****************************************************************************/

/*!
\page changes-qtopiamail.html
\code

*****************************************************************************
**
** API Change History
**
*****************************************************************************

Changes since the QMF-1.0 release on 15/05/09:

1. Added 'QMail::baseSubject(const QString &)',
         'QMail::messageIdentifiers(const QString &)',
         'QMail::messageServerPath()',
         'QMail::messageSettingsPath()', and
         'QMail::lastSystemErrorMessage()'.

2. Extracted 'QMailMessageModelBase' from 'QMailMessageListModel'.

3. Added 'QMailMessageThreadedModel'.

4. Added 'QMailMessageKey::conversation(...)'.

5. Added 'QMailStore::ContentNotRemoved'.

6. Added 'QMailMessagePart::indicativeSize() const'.

7. Added 'QMailMessagePartContainer::foreachPart(F)' and
         'QMailMessagePartContainer::foreachPart(F) const'.

8. Added 'QMailAccount::CanReferenceExternalData' and
         'QMailAccount::CanTransmitViaReference'.

9. Added 'QMailMessageMetaData::HasReferences' and
         'QMailMessageMetaData::HasUnresolvedReferences'.

10. Added 'QMailMessageFwd::ChunkType' and
          'QMailMessageFwd::MessageChunk'.

11. Added 'QMailMessage::toRfc2822Chunks(QMailMessage::EncodingFormat)'.

12. Changed 'QMailAccountSortKey::status(Qt::SortOrder)' to
            'QMailAccountSortKey::status(quint64, Qt::SortOrder)',
            'QMailFolderSortKey::status(Qt::SortOrder)' to
            'QMailFolderSortKey::status(quint64, Qt::SortOrder)', and
            'QMailMessageSortKey::status(Qt::SortOrder)' to
            'QMailMessageSortKey::status(quint64, Qt::SortOrder)'.

13. Added 'QMailMessagePartContainer::multipartTypeForName(const QByteArray&)' and
          'QMailMessagePartContainer::nameForMultipartType(QMailMessagePartContainer::MultipartType)'.

14. Added 'QMailMessageMetaData::LocalOnly'.

15. Added 'QMailMessage::contains(const QMailMessagePart::Location&) const'.

16. Added 'void QMailMessageServer::actionStarted(QMailActionData)'.

17. Added 'void QMailMessageServer::messagesFailedTransmission(quint64, const QMailMessageIdList&, QMailServiceAction::Status::ErrorCode)'.

18. Added 'void QMailMessageServer::actionsListed(const QMailActionDataList &)' signal.

19. Added 'void QMailMessageServer::listActions()' slot.

20. Added 'QMailServiceAction(quint64 actionId, QObject *parent = 0)' constructor.

21. Added 'QString QMailServiceAction::description()'

22. Added 'void QMailRetrievalAction::messagesTransmitted(const QMailMessageIdList &ids)' signal.

23. Added 'void QMailRetrievalAction::messagesFailedTransmission(const QMailMessageIdList &ids, QMailServiceAction::Status::ErrorCode)' signal.

24. Added QMailActionInfo class.

25. Added QMailActionObserver class.

26. Added 'QMailMessage::Important', and
          'QMailMessage::ImportantElsewhere'.

27. Added 'QMailStore::lock()' and
          'QMailStore::unlock()'.

28. Added QMailActionInfo and QMailActionObserver classes.

29. Added QMailDisconnected class.

30. Changed 'QMailRetrievalAction::synchronize(const QMailAccountId &accountId)' to
            'QMailRetrievalAction::synchronizeAll(const QMailAccountId &accountId)'

31. Added 'QMailDisconnected::destinationKey(const QMailFolderId &)'

32. Added 'QMailRetrievalAction::synchronize(const QMailAccountId &accountId, uint minimum)'

33. Added 'QMailAccount::lastSynchronized() const' and
          'QMailAccount::setSynchronized(const QMailTimeStamp &synced)'

34. File Rename:
      qmf.pro -> messagingframework.pro (To avoid it conflicting with its child project)

    Library Renames:
      libmessageserver -> libqmfmessageserver
      libqtopiamail -> libqmf

    Directory Changes:
      src/libraries/messageserver -> src/libraries/qmfmessageserver
      src/libraries/qtopiamail -> src/libraries/qmf
      src/plugins/contentmanagers/qtopiamailfile -> qmfstoragemanager
      src/plugins/messageservices/qtopiamailfile -> qmfsettings

    Class changes:
      QtopiamailfileConfigurator -> QmfConfigurator
      QtopiamailfileSettings -> QmfSettings
      QtopiamailfileServicePlugin -> QmfServicePlugin
      QtopiamailfileManager -> QmfStorageManager

35. Library rename:
      libqmf -> libqmfclient

    Directory Changes:
      src/libraries/qmf -> src/libraries/qmfclient

36. Changed 'bool QMailStore::restoreToPreviousFolder(const QMailMessageId& id)' and
            'bool QMailStore::restoreToPreviousFolder(const QMailMessageKey& key)' to
            'void QMailDisconnected::restoreToPreviousFolder(const QMailMessageId& id)' and
            'void QMailDisconnected::restoreToPreviousFolder(const QMailMessageKey& key)'

37. Added 'QMailStore::messageDataAdded(const QMailMessageMetaDataList &data)'
          'QMailStore::messageDataUpdated(const QMailMessageMetaDataList &data)
          'QMailStore::messagePropertyUpdated(const QMailMessageIdList& ids, 
                                              const QMailMessageKey::Properties& properties,
                                              const QMailMessageMetaData& data)'
          'QMailStore::messageStatusUpdated(const QMailMessageIdList& ids, 
                                            quint64 status, bool set)' signals.

38. Remove unintentionally exported QMailId that should not have been included in the public API.

39. Move Location inner class from QMailMessagePart to QMailMessagePartContainer

    Added following functions to QMailMessagePartContainer:
    'QMailMessagePartContainer* findPlainTextContainer() const'
    'QMailMessagePartContainer* findHtmlContainer() const'
    'QList<QMailMessagePartContainer::Location> findAttachmentLocations() const'
    'bool hasPlainTextBody() const'
    'bool hasHtmlBody() const'
    'bool hasAttachments() const'
    'void setPlainTextBody(const QMailMessageBody& plainTextBody)'
    'void setHtmlAndPlainTextBody(const QMailMessageBody& htmlBody, const QMailMessageBody& plainTextBody)'
    'void setAttachments(const QStringList& attachments)'
    'void setAttachments(const QList<const QMailMessagePart*> attachments)'

40. Add 'QMailRetrievalAction::Auto'

41. Removed QMailMessage::latestInConversation() 

    Added QMailThreadId, QMailThread, QMailThreadKey and QMailThreadSortKey classes

    Added 'QMailStore::addThread(QMailThread *t)',
      'QMailStore::removeThread(const QMailThreadId &id, MessageRemovalOption option = NoRemovalRecord)', 
      'QMailStore::removeThreads(const QMailThreadKey& key, QMailStore::MessageRemovalOption option = NoRemovalRecord)', 
      'QMailStore::updateThread(QMailThread* t)', 
      'QMailStore::countThreads(const QMailThreadKey & key = QMailThreadKey())',
      'QMailStore::queryThreadsconst QMailThreadKey &key = QMailThreadKey(), const QMailThreadSortKey &sortKey = QMailThreadSortKey(), uint limit = 0, uint offset = 0) const',
      'QMailStore::thread(const QMailThreadId &id)',
      'QMailStore::threadsAdded(const QMailThreadIdList& ids)',
      'QMailStore::threadsRemoved(const QMailThreadIdList& ids)',
      'QMailStore::threadsUpdated(const QMailThreadIdList& ids)',
      'QMailStore::threadContentsModified(const QMailThreadIdList& ids)',
      'QMailThreadId QMailMessageKey::parentThreadId() const',
      'void QMailMessageKey::setParentThreadId(const QMailThreadId &id)',
      'static QMailMessageKey QMailMessageKey::parentThreadId(const QMailThreadId &id, QMailDataComparator::EqualityComparator cmp = QMailDataComparator::Equal)',
      'static QMailMessageKey QMailMessageKey::parentThreadId(const QMailThreadIdList &ids, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes)' and
      'static QMailMessageKey QMailMessageKey::parentThreadId(const QMailThreadKey &key, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes)'.

42.  Change return type of 'QMailHeartBeatTimer::interval() const' from 'int' to 'QPair<int, int>'
     Added QMailHeartBeatTimer::setInterval(int)
     Remove inline keyword from QMailHeartBeatTimer member functions

43.  Binary compatibility broken in qmailthread.h (change of QMailThread d ptr type)

44.  Added dependency on libicu-dev (for autodetection of charset)

45.  Added dependency on zlib (for IMAP COMPRESS support)

46.  Added 'QMailAccount::CanSearchOnServer'.

47.  Added 'void QMailSearchAction::searchMessages(const QMailMessageKey &filter, const QString &bodyText, SearchSpecification spec, quint64 limit, const QMailMessageSortKey &sort)',
       'uint QMailSearchAction::remainingMessagesCount()' functions, and 
       'QMailMessageServer::remainingMessagesCount(uint count)' signal.

48.  Added 'void QMailSearchAction::countMessages(const QMailMessageKey &filter, const QString &bodyText)',
       'uint QMailSearchAction::messagesCount()' functions, and 
       'QMailMessageServer::messagesCount(uint count)' signal.

49.  Added 'QList<QMailAddress> QMailMessage::to() const',
           'virtual QList<QMailAddress> QMailMessageMetaData::recipients() const',
        protected:
           'virtual void QMailMessageMetaData::setRecipients(const QList<QMailAddress>& s)',
           'virtual void QMailMessageMetaData::setRecipients(const QMailAddress& s)' functions.

     Removed 'QList<QMailAddress> QMailMessageMetaData::to() const',
             'void QMailMessageMetaData::setTo(const QList<QMailAddress>& s)',
             'void QMailMessageMetaData::setTo(const QMailAddress& s)' functions.

50. Added 'static QByteArray QMailCodec::bestCompatibleCharset(const QByteArray& charset, bool translateAscii)' function.

51. Renamed 'void QMailStorageAction::deleteMessages(const QMailMessageIdList &ids)' to onlineDeleteMessages,
            'void QMailStorageAction::copyMessages(const QMailMessageIdList &ids, const QMailFolderId &destinationId)' to onlineCopyMessages,
            'void QMailStorageAction::moveMessages(const QMailMessageIdList &ids, const QMailFolderId &destinationId)' to onlineMoveMessages,
            'void QMailStorageAction::flagMessages(const QMailMessageIdList &ids, quint64 setMask, quint64 unsetMask)' to onlineFlagMessagesAndMoveToStandardFolder,
            'void QMailStorageAction::createFolder(const QString &name, const QMailAccountId &accountId, const QMailFolderId &parentId)' to onlineCreateFolder,
            'void QMailStorageAction::renameFolder(const QMailFolderId &folderId, const QString &name)' to onlineRenameFolder,
            'void QMailStorageAction::deleteFolder(const QMailFolderId &folderId)' to onlineDeleteFolder.
            'void QMailMessageServer::deleteMessages(const QMailMessageIdList &ids)' to onlineDeleteMessages,
            'void QMailMessageServer::copyMessages(const QMailMessageIdList &ids, const QMailFolderId &destinationId)' to onlineCopyMessages,
            'void QMailMessageServer::moveMessages(const QMailMessageIdList &ids, const QMailFolderId &destinationId)' to onlineMoveMessages,
            'void QMailMessageServer::flagMessages(const QMailMessageIdList &ids, quint64 setMask, quint64 unsetMask)' to onlineFlagMessagesAndMoveToStandardFolder,
            'void QMailMessageServer::createFolder(const QString &name, const QMailAccountId &accountId, const QMailFolderId &parentId)' to onlineCreateFolder,
            'void QMailMessageServer::renameFolder(const QMailFolderId &folderId, const QString &name)' to onlineRenameFolder,
            'void QMailMessageServer::deleteFolder(const QMailFolderId &folderId)' to onlineDeleteFolder.

52. Added 'void QMailStorageAction::deleteMessages(quint64, const QMailMessageIdList &ids)',
          'void QMailStorageAction::rollBackUpdates(quint64, const QMailAccountId &mailAccountId)',
          'void QMailStorageAction::moveToStandardFolder(quint64, const QMailMessageIdList& ids, QMailFolder::StandardFolder standardFolder)',
          'void QMailStorageAction::moveToFolder(quint64, const QMailMessageIdList& ids, const QMailFolderId& folderId)',
          'void QMailStorageAction::flagMessages(quint64, const QMailMessageIdList& ids, quint64 setMask, quint64 unsetMask)',
          'void QMailStorageAction::restoreToPreviousFolder(quint64, const QMailMessageKey& key)',
          'void QMailMessageServer::deleteMessages(quint64, const QMailMessageIdList &ids)',
          'void QMailMessageServer::rollBackUpdates(quint64, const QMailAccountId &mailAccountId)',
          'void QMailMessageServer::moveToStandardFolder(quint64, const QMailMessageIdList& ids, quint64 standardFolder)',
          'void QMailMessageServer::moveToFolder(quint64, const QMailMessageIdList& ids, const QMailFolderId& folderId)',
          'void QMailMessageServer::flagMessages(quint64, const QMailMessageIdList& ids, quint64 setMask, quint64 unsetMask)' and
          'void QMailMessageServer::restoreToPreviousFolder(quint64, const QMailMessageKey& key)'.

53. Added 'void QMailMessageServer::transmitMessage(quint64 action, const QMailMessageId &messageId)'.

54. Added 'void QMailRetrievalAction::createStandardFolders(const QMailAccountId &accountId)'.

55. Added 'void QMailRetrievalAction::retrieveNewMessages(const QMailAccountId &accountId, const QMailFolderIdList &folderIds)' and
          'void QMailMessageServer::retrieveNewMessages(quint64, const QMailAccountId &accountId, const QMailFolderIdList &folderIds)'.

56. Binary compatibility broken.
    Change 'void qmf_registerLoggingFlag(const char *flag)' to 
    'void qmf_registerLoggingFlag(char *flag)'. 

*****************************************************************************

Changes since the development preview release on 03/04/09:

1. Added 'QMailFolder::serverUndiscoveredCount() const' and
         'QMailFolder::setServerUndiscoveredCount()'.

2. Added 'QMailStore::retrievalInProgress()',
         'QMailStore::setRetrievalInProgress()',
         'QMailStore::transmissionInProgress()' and
         'QMailStore::setTransmissionInProgress()'.

3. Replaced 'QMailStore::initialized() const' and
            'QMailStore::storeInitialized()' with
            'QMailStore::InitializationState QMailStore::initializationState()'.

4. Changed 'QMailMessageKey::status(...)',
           'QMailFolderKey::status(...)' and
           'QMailMessageKey::status(...)' so that the overload taking a QMailDataComparator::InclusionComparator has the default argument.


*****************************************************************************

Changes since the development preview release on 06/03/09:

1. Added 'QMailContentManager::init()' and 
         'QMailContentManagerFactory::init()'.

2. Added 'QMailMessage::contentSize() const' and 
         'QMailMessage::setContentSize(uint)'.

3. Added 'QMailCodec::name() const',
         'QMailBase64Codec::name() const',
         'QMailQuotedPrintableCodec::name() const',
         'QMailPassThroughCodec::name() const' and
         'QMailLineEndingCodec::name() const'.


*****************************************************************************

Changes since the development preview release on 16/01/09:

1. Added 'QMailAccountConfiguration::id() const'

2. Added 'QMailMessagePart::Location::Location(const QString&)'

3. Changed 'QMailMessagePart::Location::isValid() const' to
           'QMailMessagePart::Location::isValid(bool = true) const'.

4. Added 'QMailMessagePart::setReference(const QMailMessageId&, const QMailMessageContentType&, QMailMessageBody::TransferEncoding)' and
         'QMailMessagePart::setReference(const QMailMessagePart::Location&, const QMailMessageContentType&, QMailMessageBody::TransferEncoding)'.

5. Added 'QMailMessagePart::contentModified() const' and
         'QMailMessagePart::setUnmodified()'.

6. Changed 'QMailMessageMetaData::dataModified() const' from private to public accessibility.

7. Renamed 'QMailMessageMetaData::committed()' to 
           'QMailMessageMetaData::setUnmodified()'.

8. Changed 'QMailMessage::contentModified() const' from private to public accessibility.

9. Added 'QMailStore::ErrorCode' enum.

10. Added 'QMailStore::lastError() const',
          'QMailStore::errorOccurred(QMailStore::ErrorCode)' and
          'QMailStore::emitErrorNotification(QMailStore::ErrorCode)'.

11. Added 'QMailStoreImplmentation::lastError() const',
          'QMailStoreImplmentation::setLastError() const' and
          'QMailStoreImplementation::errorCode'.

12. Changed 'QMailContentManager::add(QMailMessage*)',
            'QMailContentManager::update(QMailMessage*)',
            'QMailContentManager::remove(const QString&)' and
            'QMailContentManager::load(const QString&, QMailMessage*)' 
    to return QMailStore::ErrorCode instead of bool.

13. Changed to use type-safe construction interface for 'QMailAccountKey',
                                                        'QMailFolderKey' and
                                                        'QMailMessageKey'.

14. Changed to equivalent construction interface for 'QMailAccountSortKey',
                                                     'QMailFolderSortKey' and
                                                     'QMailMessageSortKey'.

15. Removed 'QMailAccount::mailboxes() const',
            'QMailAccount::mailbox(const QString &)',
            'QMailAccount::serverUids() const',
            'QMailAccount::serverUids(const QMailFolderId &) const',
            'QMailAccount::serverUids(const QMailFolderId &, quint64, bool) const',
            'QMailAccount::deletedMessages() const' and
            'QMailAccount::deletedMessages(const QMailFolderId &) const'.

16. Renamed 'QMailAccount::accountName() const' to 'QMailAccount::name() const',
            'QMailAccount::setAccountName(const QString &)' to 'QMailAccount::setName(const QString &)' and
            'QMailAccountKey::accountName()' to 'QMailAccountKey::name()'.

17. Removed 'QMailAccount::displayName() const'.

18. Renamed 'QMailFolder::name() const' to 'QMailFolder::path() const',
            'QMailFolder::setName(const QString &)' to 'QMailFolder::setPath(const QString &)' and
            'QMailFolderKey::name(...)' to 'QMailFolderKey::path(...)'.

19. Renamed 'QMailFolder::parentId() const' to 'QMailFolder::parentFolderId() const',
            'QMailFolder::setParentId(const QMailFolderId &)' to 'QMailFolder::setParentFolderId(const QMailFolderId &)' and
            'QMailFolderKey::parentId(...)' to 'QMailFolderKey::parentFolderId(...)'.

20. Added 'QMailMessageMetaData::receivedDate() const',
          'QMailMessageMetaData::setReceivedDate(const QMailTimeStamp &) const',
          'QMailMessageKey::receptionTimeStamp(...)' and
          'QMailMessageSortKey::receptionTimeStamp(...)'.

21. Renamed 'QMailMessageSortKey::type(Qt::SortOrder)' to
            'QMailMessageSortKey::messageType(Qt::SortOrder)'.

22. Added 'QMailMessagePart::Location::setContainingMessageId(const QMailMessageId &)'.

23. Changed 'QMailRetrievalAction::retrieveMessagePart(const QMailMessageId &, const QMailMessagePart::Location &)' to
            'QMailRetrievalAction::retrieveMessagePart(QMailMessagePart::Location &)',
            'QMailRetrievalAction::retrieveMessagePartRange(const QMailMessageId &, const QMailMessagePart::Location &, uint)' to
            'QMailRetrievalAction::retrieveMessagePartRange(QMailMessagePart::Location &, uint)',
            'QMailMessageServer::retrieveMessagePart(const QMailMessageId &, const QMailMessagePart::Location &)' to
            'QMailMessageServer::retrieveMessagePart(QMailMessagePart::Location &)' and 
            'QMailMessageServer::retrieveMessagePartRange(const QMailMessageId &, const QMailMessagePart::Location &, uint)' to
            'QMailMessageServer::retrieveMessagePartRange(QMailMessagePart::Location &, uint)'.

24. Added 'Flags' value to 'QMailRetrievalAction::RetrievalSpecification'.

25. Changed 'QMailRetrievalAction::retrieveAll(const QMailAccountId &, QMailRetrievalAction::RetrievalSpecification)' to
            'QMailRetrievalAction::retrieveAll(const QMailAccountId &)',
            'QMailRetrievalAction::synchronize(const QMailAccountId &, QMailRetrievalAction::RetrievalSpecification)' to
            'QMailRetrievalAction::synchronize(const QMailAccountId &)',
            'QMailMessageServer::retrieveAll(const QMailAccountId &, QMailRetrievalAction::RetrievalSpecification)' to
            'QMailMessageServer::retrieveAll(const QMailAccountId &)' and 
            'QMailMessageServer::synchronize(const QMailAccountId &, QMailRetrievalAction::RetrievalSpecification)' to
            'QMailMessageServer::synchronize(const QMailAccountId &)'.

26. Renamed 'QMailMessageMetaData::Downloaded' to 'QMailMessageMetaData::ContentAvailable'.

27. Added 'QMailMessageMetaData::PartialContentAvailable' and 'QMailMessageMetaData::HasAttachments'.

28. Added 'QMailMessagePartContainer::contentAvailable() const',
          'QMailMessagePartContainer::partialContentAvailable() const',
          'QMailMessageMetaData::contentAvailable() const' and
          'QMailMessageMetaData::partialContentAvailable() const'.

29. Changed 'QMailMessageModelBase::emitDataChanged(const QModelIndex &idx)' to 
            'QMailMessageModelBase::emitDataChanged(const QModelIndex &idx, const QModelIndex &jdx)'.

30. Added 'QMailStorageAction::addMessages(const QMailMessageList &list)',
          'QMailStorageAction::updateMessages(const QMailMessageList &list)',
          'QMailMessageIdList QMailStorageAction::messagesAdded() const',
          'QMailMessageIdList QMailStorageAction::messagesUpdated() const'.
          'QMailMessageServer::addMessages(quint64, const QString &filename)',
          'QMailMessageServer::updateMessages(quint64, const QString &filename)',
          'QMailMessageServer::messagesAdded(quint64, QMailMessageIdList)' and
          'QMailMessageServer::messagesUpdated(quint64, QMailMessageIdList)'.

31. Added 'QMailMessage::hasCalendarInvitation()'

32. Added 'QMailContentManager::NoDurability' enum value,
          'QMailContentManager::ensureDurability(const QList<QString> &)',
          'QMailMessageServer::addMessages(quint64, const QMailMessageMetaDataList &)' and
          'QMailMessageServer::updateMessages(quint64, const QMailMessageMetaDataList &)'.

32. Added 'QMailStore::ensureDurabiilty()'.

33. Added 'QMailMessageServer::connectionDown()', and
          'QMailMessageServer::reconnectionTimeout()' signals.

34. Added 'QMailStorageAction::updateMessages(const QMailMessageMetaDataList &list)'.

35. Added 'static QString QMailCodec::autoDetectEncoding(const QByteArray& text)'.

*****************************************************************************

\endcode
*/
