|  | 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.

- List of all members, including inherited members

## Public Types

enum | RetrievalSpecification { Flags, MetaData, Content, Auto }

## Public Functions

| QMailRetrievalAction ( QObject * parent = 0 )

- 4 public functions inherited from QMailServiceAction
- 29 public functions inherited from QObject

## 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)`

- 1 public slot inherited from QMailServiceAction
- 1 public slot inherited from QObject

### Additional Inherited Members

- 1 property inherited from QObject
- 4 signals inherited from QMailServiceAction
- 1 signal inherited from QObject
- 1 public type inherited from QObject
- 4 static public members inherited from QObject
- 2 protected functions inherited from QMailServiceAction
- 7 protected functions inherited from QObject
- 2 protected variables inherited from QObject

## 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.

Constant | Value | Description
--- | --- | ---
`QMailRetrievalAction::Flags` | `0` | Changes to the state of the message should be retrieved.
`QMailRetrievalAction::MetaData` | `1` | Only the meta data of the message should be retrieved.
`QMailRetrievalAction::Content` | `2` | The entire content of the message should be retrieved.
`QMailRetrievalAction::Auto` | `3` | Account specific settings are used during synchronization. For example, this may mean skipping the attachments.

## 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, and the lastSynchronized() time of the account updated. 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.

See also QMailAccount::lastSynchronized().

### 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.

On a successful synchronization the lastSynchronized() value of the account should be updated.

See also exportUpdates(), retrieveMessageList(), retrieveFolderList(), and QMailAccount::lastSynchronized().

### 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().