Home

QMailRetrievalAction Class Reference

The QMailRetrievalAction class provides the interface for retrieving messages from external message services. More...

    #include <QMailRetrievalAction>

This class is under development and is subject to change.

Inherits QMailServiceAction.


Public Types

enum RetrievalSpecification { Flags, MetaData, Content }

Public Functions

QMailRetrievalAction ( QObject * parent = 0 )

Public Slots

void exportUpdates ( const QMailAccountId & accountId )
void retrieveAll ( const QMailAccountId & accountId )   (deprecated)
void retrieveFolderList ( const QMailAccountId & accountId, const QMailFolderId & folderId, bool descending = true )
void retrieveMessageList ( const QMailAccountId & accountId, const QMailFolderId & folderId, uint minimum = 0, const QMailMessageSortKey & sort = QMailMessageSortKey() )
void retrieveMessagePart ( const QMailMessagePart::Location & partLocation )
void retrieveMessagePartRange ( const QMailMessagePart::Location & partLocation, uint minimum )
void retrieveMessageRange ( const QMailMessageId & messageId, uint minimum )
void retrieveMessages ( const QMailMessageIdList & messageIds, RetrievalSpecification spec = MetaData )
void synchronize ( const QMailAccountId & accountId, uint minimum )
void synchronizeAll ( const QMailAccountId & accountId )   (deprecated)

Additional Inherited Members


Detailed Description

The QMailRetrievalAction class provides the interface for retrieving messages from external message services.

QMailRetrievalAction provides the mechanism for messaging clients to request that the message server retrieve messages from external services. The retrieval action object reports on the progress and outcome of its activities via the signals inherited from QMailServiceAction.

A range of functions are available to support varying client operations:

The retrieveFolderList() function allows a client to retrieve the list of folders available for an account. The retrieveMessageList() function allows a client to retrieve a subset of messages available for an account or folder.

The retrieveMessages() function allows a client to retrieve the flags, meta data or content of a specific list of messages.

The retrieveMessageRange() functions allows a portion of a message's content to be retrieved, rather than the entire content data.

The retrieveMessagePart() function allows a specific part of a multi-part message to be retrieved. The retrieveMessagePartRange() function allows a portion of a specific part of a multi-part message to be retrieved.

The exportUpdates() function allows a client to push local changes such as message-read notifications and pending disconnected operations to the external server.


Member Type Documentation

enum QMailRetrievalAction::RetrievalSpecification

This enum type is specify the form of retrieval that the message server should perform.

ConstantValueDescription
QMailRetrievalAction::Flags0Changes to the state of the message should be retrieved.
QMailRetrievalAction::MetaData1Only the meta data of the message should be retrieved.
QMailRetrievalAction::Content2The entire content of the message should be retrieved.


Member Function Documentation

QMailRetrievalAction::QMailRetrievalAction ( QObject * parent = 0 )

Constructs a new retrieval action object with the supplied parent.

void QMailRetrievalAction::exportUpdates ( const QMailAccountId & accountId )   [slot]

Requests that the message server update the external server with changes that have been effected on the local device for account accountId. Local changes to QMailMessage::Read, and QMailMessage::Important message status flags should be exported to the external server, messages that have been removed using the QMailStore::CreateRemovalRecord option should be removed from the external server, and any flag, copy or move operations that have been applied using QMailDisconnected should be applied to the external server.

void QMailRetrievalAction::retrieveAll ( const QMailAccountId & accountId )   [slot]

This function is deprecated.

Requests that the message server retrieve all folders and meta data for messages available for the account accountId.

All folders within the account will be discovered and searched for child folders. The QMailFolder::serverCount(), QMailFolder::serverUnreadCount() and QMailFolder::serverUndiscoveredCount() properties will be updated for each folder in the account.

Meta data will be retrieved for every message found in the account. New messages will be added to the mail store as they are retrieved, and marked with the QMailMessage::New status flag. Messages that are no longer available will be marked with the QMailMessage::Removed status flag.

See also retrieveFolderList() and retrieveMessageList().

void QMailRetrievalAction::retrieveFolderList ( const QMailAccountId & accountId, const QMailFolderId & folderId, bool descending = true )   [slot]

Requests that the message server retrieve the list of folders available for the account accountId. If folderId is valid, only the identified folder is searched for child folders; otherwise the search begins at the root of the account. If descending is true, the search should also recursively search for child folders within folders discovered during the search.

The QMailFolder::serverCount(), QMailFolder::serverUnreadCount() and QMailFolder::serverUndiscoveredCount() properties will be updated for each folder that is searched for child folders; these properties are not updated for folders that are merely discovered by searching.

See also retrieveMessageList().

void QMailRetrievalAction::retrieveMessageList ( const QMailAccountId & accountId, const QMailFolderId & folderId, uint minimum = 0, const QMailMessageSortKey & sort = QMailMessageSortKey() )   [slot]

Requests that the message server retrieve the list of messages available for the account accountId. If folderId is valid, then only messages within that folder should be retrieved; otherwise messages within all folders in the account should be retrieved. If minimum is non-zero, then that value will be used to restrict the number of messages to be retrieved from each folder; otherwise, all messages will be retrieved.

If sort is not empty, the external service will report the discovered messages in the ordering indicated by the sort criterion, if possible. Services are not required to support this facility.

If a folder messages are being retrieved from contains at least minimum messages then the messageserver should ensure that at least minimum messages are available from the mail store for that folder; otherwise if the folder contains less than minimum messages the messageserver should ensure all the messages for that folder are available from the mail store. If a folder has messages locally available, then all previously undiscovered messages will be retrieved for that folder, even if that number exceeds minimum.

The QMailFolder::serverCount(), QMailFolder::serverUnreadCount() and QMailFolder::serverUndiscoveredCount() properties will be updated for each folder from which messages are retrieved.

New messages will be added to the mail store as they are discovered, and marked with the QMailMessage::New status flag. Messages that are present in the mail store but found to be no longer available are marked with the QMailMessage::Removed status flag.

void QMailRetrievalAction::retrieveMessagePart ( const QMailMessagePart::Location & partLocation )   [slot]

Requests that the message server retrieve the message part that is indicated by the location partLocation.

The QMailFolder::serverCount(), QMailFolder::serverUnreadCount() and QMailFolder::serverUndiscoveredCount() properties will be updated for the folder from which the part is retrieved.

void QMailRetrievalAction::retrieveMessagePartRange ( const QMailMessagePart::Location & partLocation, uint minimum )   [slot]

Requests that the message server retrieve a subset of the message part that is indicated by the location partLocation. The messageserver should ensure that at least minimum bytes are available from the mail store.

The total size of the part on the server is given by QMailMessagePart::contentDisposition().size(), the amount of the part available locally is given by QMailMessagePart::body().length().

The QMailFolder::serverCount(), QMailFolder::serverUnreadCount() and QMailFolder::serverUndiscoveredCount() properties will be updated for the folder from which the part is retrieved.

void QMailRetrievalAction::retrieveMessageRange ( const QMailMessageId & messageId, uint minimum )   [slot]

Requests that the message server retrieve a subset of the message messageId, such that at least minimum bytes are available from the mail store.

The QMailFolder::serverCount(), QMailFolder::serverUnreadCount() and QMailFolder::serverUndiscoveredCount() properties will be updated for the folder from which the message is retrieved.

void QMailRetrievalAction::retrieveMessages ( const QMailMessageIdList & messageIds, RetrievalSpecification spec = MetaData )   [slot]

Requests that the message server retrieve data regarding the messages identified by messageIds.

If spec is QMailRetrievalAction::Flags, then the message server should detect if the messages identified by messageIds have been marked as read or have been removed. Messages that have been read will be marked with the QMailMessage::ReadElsewhere flag, and messages that have been removed will be marked with the QMailMessage::Removed status flag.

If spec is QMailRetrievalAction::MetaData, then the message server should retrieve the meta data of the each message listed in messageIds.

If spec is QMailRetrievalAction::Content, then the message server should retrieve the entirety of each message listed in messageIds.

The QMailFolder::serverCount(), QMailFolder::serverUnreadCount() and QMailFolder::serverUndiscoveredCount() properties will be updated for each folder from which messages are retrieved.

void QMailRetrievalAction::synchronize ( const QMailAccountId & accountId, uint minimum )   [slot]

Essentially performs the same functions as calling exportUpdates(), retrieveFolderList() and retrieveMessageList() consecutively using the given accountId and minimum, but may perform optimizations such as retrieving the folder list at the same time as retrieving messages, and retrieving messages in multiple folder simultaneously by using multiple connections to the server.

See also exportUpdates(), retrieveMessageList(), and retrieveFolderList().

void QMailRetrievalAction::synchronizeAll ( const QMailAccountId & accountId )   [slot]

This function is deprecated.

Requests that the message server synchronize the set of known folder and message identifiers with those currently available for the account identified by accountId. Newly discovered messages should have their meta data retrieved, messages that have been removed locally using the QMailStore::CreateRemovalRecord option should be removed from the external server.

Changes to the QMailMessage::Read, and QMailMessage::Important status flags of a message should be exported to the external server, and the status flags of the message should be updated to reflect any changes to the message on the external server.

New messages will be added to the mail store as they are discovered, and marked with the QMailMessage::New status flag. Messages that are no longer available will be marked with the QMailMessage::Removed status flag.

The folder structure of the account will be synchronized with that available from the external server. The QMailFolder::serverCount(), QMailFolder::serverUnreadCount() and QMailFolder::serverUndiscoveredCount() properties will be updated for each folder.

See also retrieveFolderList(), retrieveMessageList(), and exportUpdates().


Copyright © 2010 QtSoftware
Messaging Framework