|  | Home |

# QMailMessageSource Class Reference

The QMailMessageSource class defines the interface to objects that provide access to externally sourced messages to the messageserver. More...

        #include <QMailMessageSource>

Inherits QObject.

- List of all members, including inherited members

## Public Functions

virtual QMailStore::MessageRemovalOption | messageRemovalOption () const

- 29 public functions inherited from QObject

## Public Slots

virtual bool | cancelSearch ()
virtual bool | cancelSearch ( quint64 action )
virtual bool | copyMessages ( const QMailMessageIdList & ids, const QMailFolderId & destinationId )
virtual bool | copyMessages ( const QMailMessageIdList & ids, const QMailFolderId & destinationId, quint64 action )
virtual bool | createFolder ( const QString & name, const QMailAccountId & accountId, const QMailFolderId & parentId )
virtual bool | createFolder ( const QString & name, const QMailAccountId & accountId, const QMailFolderId & parentId, quint64 action )
virtual bool | deleteFolder ( const QMailFolderId & folderId )
virtual bool | deleteFolder ( const QMailFolderId & folderId, quint64 action )
virtual bool | deleteMessages ( const QMailMessageIdList & ids )
virtual bool | deleteMessages ( const QMailMessageIdList & ids, quint64 action )
virtual bool | exportUpdates ( const QMailAccountId & accountId )
virtual bool | exportUpdates ( const QMailAccountId & accountId, quint64 action )
virtual bool | flagMessages ( const QMailMessageIdList & ids, quint64 setMask, quint64 unsetMask )
virtual bool | flagMessages ( const QMailMessageIdList & ids, quint64 setMask, quint64 unsetMask, quint64 action )
virtual bool | moveMessages ( const QMailMessageIdList & ids, const QMailFolderId & destinationId )
virtual bool | moveMessages ( const QMailMessageIdList & ids, const QMailFolderId & destinationId, quint64 action )
virtual bool | prepareMessages ( const QList<QPair<QMailMessagePart::Location, QMailMessagePart::Location> > & ids )
virtual bool | prepareMessages ( const QList<QPair<QMailMessagePart::Location, QMailMessagePart::Location> > & ids, quint64 action )
virtual bool | protocolRequest ( const QMailAccountId & accountId, const QString & request, const QVariant & data )
virtual bool | protocolRequest ( const QMailAccountId & accountId, const QString & request, const QVariant & data, quint64 action )
virtual bool | renameFolder ( const QMailFolderId & folderId, const QString & name )
virtual bool | renameFolder ( const QMailFolderId & folderId, const QString & name, quint64 action )
virtual bool | retrieveAll ( const QMailAccountId & accountId )
virtual bool | retrieveAll ( const QMailAccountId & accountId, quint64 action )
virtual bool | retrieveFolderList ( const QMailAccountId & accountId, const QMailFolderId & folderId, bool descending )
virtual bool | retrieveFolderList ( const QMailAccountId & accountId, const QMailFolderId & folderId, bool descending, quint64 action )
virtual bool | retrieveMessageList ( const QMailAccountId & accountId, const QMailFolderId & folderId, uint minimum, const QMailMessageSortKey & sort )
virtual bool | retrieveMessageList ( const QMailAccountId & accountId, const QMailFolderId & folderId, uint minimum, const QMailMessageSortKey & sort, quint64 action )
virtual bool | retrieveMessagePart ( const QMailMessagePart::Location & partLocation )
virtual bool | retrieveMessagePart ( const QMailMessagePart::Location & partLocation, quint64 action )
virtual bool | retrieveMessagePartRange ( const QMailMessagePart::Location & partLocation, uint minimum )
virtual bool | retrieveMessagePartRange ( const QMailMessagePart::Location & partLocation, uint minimum, quint64 action )
virtual bool | retrieveMessageRange ( const QMailMessageId & messageId, uint minimum )
virtual bool | retrieveMessageRange ( const QMailMessageId & messageId, uint minimum, quint64 action )
virtual bool | retrieveMessages ( const QMailMessageIdList & ids, QMailRetrievalAction::RetrievalSpecification spec )
virtual bool | retrieveMessages ( const QMailMessageIdList & messageIds, QMailRetrievalAction::RetrievalSpecification spec, quint64 action )
virtual bool | searchMessages ( const QMailMessageKey & searchCriteria, const QString & bodyText, const QMailMessageSortKey & sort )
virtual bool | searchMessages ( const QMailMessageKey & filter, const QString & bodyText, const QMailMessageSortKey & sort, quint64 action )
virtual bool | synchronize ( const QMailAccountId & accountId )
virtual bool | synchronize ( const QMailAccountId & accountId, quint64 action )

- 1 public slot inherited from QObject

## Signals

void | matchingMessageIds ( const QMailMessageIdList & ids )
void | matchingMessageIds ( const QMailMessageIdList & ids, quint64 action )
void | messagesCopied ( const QMailMessageIdList & ids )
void | messagesCopied ( const QMailMessageIdList & ids, quint64 action )
void | messagesDeleted ( const QMailMessageIdList & ids )
void | messagesDeleted ( const QMailMessageIdList & ids, quint64 action )
void | messagesFlagged ( const QMailMessageIdList & ids )
void | messagesFlagged ( const QMailMessageIdList & ids, quint64 action )
void | messagesMoved ( const QMailMessageIdList & ids )
void | messagesMoved ( const QMailMessageIdList & ids, quint64 action )
void | messagesPrepared ( const QMailMessageIdList & ids )
void | messagesPrepared ( const QMailMessageIdList & ids, quint64 action )
void | newMessagesAvailable ()
void | newMessagesAvailable ( quint64 action )
void | protocolResponse ( const QString & response, const QVariant & data )
void | protocolResponse ( const QString & response, const QVariant & data, quint64 action )

- 1 signal inherited from QObject

## Protected Functions

| QMailMessageSource ( QMailMessageService * service )
void | notImplemented ( quint64 action )

- 7 protected functions inherited from QObject

### Additional Inherited Members

- 1 property inherited from QObject
- 1 public type inherited from QObject
- 4 static public members inherited from QObject
- 2 protected variables inherited from QObject

## Detailed Description

The QMailMessageSource class defines the interface to objects that provide access to externally sourced messages to the messageserver.

The Qt Extended messageserver uses the QMailMessageSource interface to cooperate with components loaded from plugin libraries, that act as sources of messaging data for the messaging framework. Instances of QMailMessageSource are not created directly by the messageserver, but are exported by QMailMessageService objects via their source function.

See also QMailMessageService and QMailStore.

## Member Function Documentation

### QMailMessageSource::QMailMessageSource ( QMailMessageService * service ) `[protected]`

Creates a message source object associated with the service service.

### bool QMailMessageSource::cancelSearch () `[virtual slot]`

This method is obsolete. It is no longer invoked. QMailMessageService::cancelOperation is used instead.

Previously was invoked by the message server to initiate a request to stop remote searching.

Searches in progress will be stopped, and no further results returned.

See also QMailMessageService::cancelOperation.

### bool QMailMessageSource::cancelSearch ( quint64 action ) `[virtual slot]`

### bool QMailMessageSource::copyMessages ( const QMailMessageIdList & ids, const QMailFolderId & destinationId ) `[virtual slot]`

Invoked by the message server to initiate a message copy operation.

For each message listed in ids, create a new copy in the folder identified by destinationId.

Successfully copied messages should be progressively reported via messagesCopied().

Return true if an operation is initiated.

See also messagesCopied().

### bool QMailMessageSource::copyMessages ( const QMailMessageIdList & ids, const QMailFolderId & destinationId, quint64 action ) `[virtual slot]`

### bool QMailMessageSource::createFolder ( const QString & name, const QMailAccountId & accountId, const QMailFolderId & parentId ) `[virtual slot]`

Invoked by the message server to create a new folder.

Creates a new folder named name, created in the account identified by accountId. If parentId is a valid folder identifier the new folder will be a child of the parent; otherwise the folder will be have no parent and will be created at the highest level.

Return true if an operation is initiated.

See also deleteFolder().

### bool QMailMessageSource::createFolder ( const QString & name, const QMailAccountId & accountId, const QMailFolderId & parentId, quint64 action ) `[virtual slot]`

### bool QMailMessageSource::deleteFolder ( const QMailFolderId & folderId ) `[virtual slot]`

Invoked by the message server to delete a folder.

Deletes the folder identified by folderId. It is the responsibility of the message source to ensure all subfolders and messages are also deleted.

Return true if an operation is initiated.

See also createFolder().

### bool QMailMessageSource::deleteFolder ( const QMailFolderId & folderId, quint64 action ) `[virtual slot]`

### bool QMailMessageSource::deleteMessages ( const QMailMessageIdList & ids ) `[virtual slot]`

Invoked by the message server to initiate a message deletion operation.

Delete all messages listed in ids from the local mail store and the external server.

Return true if an operation is initiated.

See also messagesDeleted().

### bool QMailMessageSource::deleteMessages ( const QMailMessageIdList & ids, quint64 action ) `[virtual slot]`

### bool QMailMessageSource::exportUpdates ( const QMailAccountId & accountId ) `[virtual slot]`

Invoked by the message server to initiate an export operation.

Update the external server with any changes to message status that have been effected on the local device for account accountId.

Return true if an operation is initiated.

See also synchronize().

### bool QMailMessageSource::exportUpdates ( const QMailAccountId & accountId, quint64 action ) `[virtual slot]`

### bool QMailMessageSource::flagMessages ( const QMailMessageIdList & ids, quint64 setMask, quint64 unsetMask ) `[virtual slot]`

Invoked by the message server to initiate a message flag operation.

Modify each message listed in ids such that the status flags set in setMask are set, and the status flags set in unsetMask are unset. If further changes are implied by modification of the flags (including message movement or deletion), thse actions should also be performed by the service.

Successfully modified messages should be progressively reported via messagesFlagged().

Return true if an operation is initiated.

See also messagesFlagged().

### bool QMailMessageSource::flagMessages ( const QMailMessageIdList & ids, quint64 setMask, quint64 unsetMask, quint64 action ) `[virtual slot]`

### void QMailMessageSource::matchingMessageIds ( const QMailMessageIdList & ids ) `[signal]`

Signal emitted by the source to report the messages listed in ids as matching the current search.

### void QMailMessageSource::matchingMessageIds ( const QMailMessageIdList & ids, quint64 action ) `[signal]`

### QMailStore::MessageRemovalOption QMailMessageSource::messageRemovalOption () const `[virtual]`

Returns the removal option used when deleting messages via this message source.

See also QMailStore::removeMessages().

### void QMailMessageSource::messagesCopied ( const QMailMessageIdList & ids ) `[signal]`

Signal emitted by the source to report the copying of the messages listed in ids.

### void QMailMessageSource::messagesCopied ( const QMailMessageIdList & ids, quint64 action ) `[signal]`

### void QMailMessageSource::messagesDeleted ( const QMailMessageIdList & ids ) `[signal]`

Signal emitted by the source to report the deletion of the messages listed in ids.

### void QMailMessageSource::messagesDeleted ( const QMailMessageIdList & ids, quint64 action ) `[signal]`

### void QMailMessageSource::messagesFlagged ( const QMailMessageIdList & ids ) `[signal]`

Signal emitted by the source to report the modification of the messages listed in ids.

### void QMailMessageSource::messagesFlagged ( const QMailMessageIdList & ids, quint64 action ) `[signal]`

### void QMailMessageSource::messagesMoved ( const QMailMessageIdList & ids ) `[signal]`

Signal emitted by the source to report the moving of the messages listed in ids.

### void QMailMessageSource::messagesMoved ( const QMailMessageIdList & ids, quint64 action ) `[signal]`

### void QMailMessageSource::messagesPrepared ( const QMailMessageIdList & ids ) `[signal]`

Signal emitted by the source to report the successful preparation for transmission of the messages listed in ids.

### void QMailMessageSource::messagesPrepared ( const QMailMessageIdList & ids, quint64 action ) `[signal]`

### bool QMailMessageSource::moveMessages ( const QMailMessageIdList & ids, const QMailFolderId & destinationId ) `[virtual slot]`

Invoked by the message server to initiate a message move operation.

Move each message listed in ids into the folder identified by destinationId.

Successfully moved messages should be progressively reported via messagesMoved().

Return true if an operation is initiated.

See also messagesMoved().

### bool QMailMessageSource::moveMessages ( const QMailMessageIdList & ids, const QMailFolderId & destinationId, quint64 action ) `[virtual slot]`

### void QMailMessageSource::newMessagesAvailable () `[signal]`

Signal emitted by the source to report the availability of new messages.

### void QMailMessageSource::newMessagesAvailable ( quint64 action ) `[signal]`

### void QMailMessageSource::notImplemented ( quint64 action ) `[protected]`

### bool QMailMessageSource::prepareMessages ( const QList<QPair<QMailMessagePart::Location, QMailMessagePart::Location> > & ids ) `[virtual slot]`

Invoked by the message server to initiate a message preparation operation.

Prepare each message listed in ids for transmission by resolving any external references into URLs, and updating the reference in the associated location.

Messages successfully prepared for transmission should be progressively reported via messagesPrepared().

Return true if an operation is initiated.

See also messagesPrepared().

### bool QMailMessageSource::prepareMessages ( const QList<QPair<QMailMessagePart::Location, QMailMessagePart::Location> > & ids, quint64 action ) `[virtual slot]`

### bool QMailMessageSource::protocolRequest ( const QMailAccountId & accountId, const QString & request, const QVariant & data ) `[virtual slot]`

Invoked by the message server to initiate a protocol-specific operation.

If request corresponds to a protocol-specific action implemented by the source, initiate the requested operation for accountId, using any relevant information extracted from data.

Any responses resulting from the action should be progressively reported via protocolResponse().

Return true if an operation is initiated.

See also protocolResponse().

### bool QMailMessageSource::protocolRequest ( const QMailAccountId & accountId, const QString & request, const QVariant & data, quint64 action ) `[virtual slot]`

### void QMailMessageSource::protocolResponse ( const QString & response, const QVariant & data ) `[signal]`

Signal emitted by the source to report the response response resulting from a protocol-specific request, with any associated data.

### void QMailMessageSource::protocolResponse ( const QString & response, const QVariant & data, quint64 action ) `[signal]`

### bool QMailMessageSource::renameFolder ( const QMailFolderId & folderId, const QString & name ) `[virtual slot]`

Invoked by the message server to rename a folder.

Renames the folder identified by folderId to name. The location of the folder in the existing hierarchy should not change.

Return true if an operation is initiated.

See also deleteFolder() and createFolder().

### bool QMailMessageSource::renameFolder ( const QMailFolderId & folderId, const QString & name, quint64 action ) `[virtual slot]`

### bool QMailMessageSource::retrieveAll ( const QMailAccountId & accountId ) `[virtual slot]`

Invoked by the message server to initiate a retrieval operation.

Retrieve all folders and meta data for all messages available for the account accountId.

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

New messages should be added to the mail store in meta data form 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 should be marked with the QMailMessage::Removed status flag.

Return true if an operation is initiated.

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

### bool QMailMessageSource::retrieveAll ( const QMailAccountId & accountId, quint64 action ) `[virtual slot]`

### bool QMailMessageSource::retrieveFolderList ( const QMailAccountId & accountId, const QMailFolderId & folderId, bool descending ) `[virtual slot]`

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.

Return true if an operation is initiated.

See also retrieveMessageList().

### bool QMailMessageSource::retrieveFolderList ( const QMailAccountId & accountId, const QMailFolderId & folderId, bool descending, quint64 action ) `[virtual slot]`

### bool QMailMessageSource::retrieveMessageList ( const QMailAccountId & accountId, const QMailFolderId & folderId, uint minimum, const QMailMessageSortKey & sort ) `[virtual slot]`

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.

Return true if an operation is initiated.

See also QMailAccount::lastSynchronized().

### bool QMailMessageSource::retrieveMessageList ( const QMailAccountId & accountId, const QMailFolderId & folderId, uint minimum, const QMailMessageSortKey & sort, quint64 action ) `[virtual slot]`

### bool QMailMessageSource::retrieveMessagePart ( const QMailMessagePart::Location & partLocation ) `[virtual slot]`

Invoked by the message server to initiate a message part retrieval operation.

Retrieve the content of the message part indicated by the location partLocation.

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

Return true if an operation is initiated.

### bool QMailMessageSource::retrieveMessagePart ( const QMailMessagePart::Location & partLocation, quint64 action ) `[virtual slot]`

### bool QMailMessageSource::retrieveMessagePartRange ( const QMailMessagePart::Location & partLocation, uint minimum ) `[virtual slot]`

Invoked by the message server to initiate a message part range retrieval operation.

Retrieve a portion of the content of the message part indicated by the location partLocation, ensuring that at least minimum bytes are available in the mail store.

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

Return true if an operation is initiated.

### bool QMailMessageSource::retrieveMessagePartRange ( const QMailMessagePart::Location & partLocation, uint minimum, quint64 action ) `[virtual slot]`

### bool QMailMessageSource::retrieveMessageRange ( const QMailMessageId & messageId, uint minimum ) `[virtual slot]`

Invoked by the message server to initiate a message range retrieval operation.

Retrieve a portion of the content of the message identified by messageId, ensuring that at least minimum bytes are available in the mail store.

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

Return true if an operation is initiated.

### bool QMailMessageSource::retrieveMessageRange ( const QMailMessageId & messageId, uint minimum, quint64 action ) `[virtual slot]`

### bool QMailMessageSource::retrieveMessages ( const QMailMessageIdList & ids, QMailRetrievalAction::RetrievalSpecification spec ) `[virtual slot]`

Invoked by the message server to initiate a message retrieval operation.

Retrieve data regarding each of the messages listed in ids.

If spec is QMailRetrievalAction::Flags, then the message server should detect if the messages identified by ids 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 ids.

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

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

Return true if an operation is initiated.

### bool QMailMessageSource::retrieveMessages ( const QMailMessageIdList & messageIds, QMailRetrievalAction::RetrievalSpecification spec, quint64 action ) `[virtual slot]`

### bool QMailMessageSource::searchMessages ( const QMailMessageKey & searchCriteria, const QString & bodyText, const QMailMessageSortKey & sort ) `[virtual slot]`

Invoked by the message server to initiate a remote message search operation.

Search the remote server for messages that match the search criteria encoded by searchCriteria. If bodyText is non-empty, matching messages must also contain the specified string. Messages whose content is already present on the local device should be excluded from the remote search.

If sort is not empty, matched messages should be discovered by testing for matches in the ordering indicated by the sort criterion, if possible.

Messages matching the search criteria should be added to the mail store in meta data form marked with the QMailMessage::New status flag, and progressively reported via matchingMessageIds().

Return true if a search operation is initiated.

See also matchingMessageIds() and retrieveMessages().

### bool QMailMessageSource::searchMessages ( const QMailMessageKey & filter, const QString & bodyText, const QMailMessageSortKey & sort, quint64 action ) `[virtual slot]`

### bool QMailMessageSource::synchronize ( const QMailAccountId & accountId ) `[virtual slot]`

Invoked by the message server to initiate a synchronization operation.

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, and local changes to message status should be exported to the external server.

New messages should be added to the mail store in meta data form 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 should be marked with the QMailMessage::Removed status flag.

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

Return true if an operation is initiated.

See also QMailAccount::lastSynchronized(), retrieveAll(), and exportUpdates().

### bool QMailMessageSource::synchronize ( const QMailAccountId & accountId, quint64 action ) `[virtual slot]`