QMailStore Class Reference
[QtMessagingModule, QtPimModule]

Detailed Description

The QMailStore class represents the main interface for storage and retrieval of messages and folders on the message store.

The QMailStore class is accessed through a singleton interface and provides functions for adding, updating and deleting of QMailAccounts, QMailFolders and QMailMessages on the message store.

QMailStore also provides functions for querying and counting of QMailFolders, QMailAccounts and QMailMessages when used in conjunction with QMailMessageKey, QMailFolderKey and QMailAccountKey classes.

See also QMailMessage, QMailFolder, QMailMessageKey, QMailFolderKey, and QMailAccountKey.

Member Type Documentation

enum QMailStore::MessageRemovalOption

Defines whether or not a QMailMessageRemovalRecord is created upon message removal.

enum QMailStore::ReturnOption

This enum defines the meta data list return option for QMailStore::messagesMetaData()

Member Function Documentation

QMailStore::~QMailStore ()   [virtual]

Destroys this QMailStore object.

QMailAccount QMailStore::account ( const QMailAccountId & id ) const

Returns the QMailAcount defined by a QMailAccountId id from the store.

void QMailStore::accountContentsModified ( const QMailAccountIdList & ids )   [signal]

Signal that is emitted when changes to messages and folders in the mail store affect the content of the accounts in the list ids.

See also messagesAdded(), messagesUpdated(), messagesRemoved(), foldersAdded(), foldersUpdated(), and foldersRemoved().

void QMailStore::accountsAdded ( const QMailAccountIdList & ids )   [signal]

Signal that is emitted when the accounts in the list ids are added to the store.

See also accountsRemoved() and accountsUpdated().

void QMailStore::accountsRemoved ( const QMailAccountIdList & ids )   [signal]

Signal that is emitted when the accounts in the list ids are removed from the store.

See also accountsAdded() and accountsUpdated().

void QMailStore::accountsUpdated ( const QMailAccountIdList & ids )   [signal]

Signal that is emitted when the accounts in the list ids are updated within the store.

See also accountsAdded() and accountsRemoved().

bool QMailStore::addAccount ( QMailAccount * account, AccountConfiguration * config = 0 )

Adds a new QMailAccount object account into the messsage store, with the configuration details optionally specified by config. Returns true if the operation completed successfully, false otherwise.

bool QMailStore::addFolder ( QMailFolder * folder )

Adds a new QMailFolder object folder into the message store, performing respective integrity checks. Returns true if the operation completed successfully, false otherwise.

bool QMailStore::addMessage ( QMailMessage * msg )

Adds a new QMailMessage object msg into the message store, performing respective integrity checks. Returns true if the operation completed successfully, false otherwise.

bool QMailStore::addMessage ( QMailMessageMetaData * metaData )

This is an overloaded member function, provided for convenience.

Adds a new QMailMessageMetaData object metaData into the message store, performing respective integrity checks. Returns true if the operation completed successfully, false otherwise.

bool QMailStore::asynchronousEmission () const

Returns true if the running process is in the act of emitting an asynchronous QMailStore signal caused by another process. This can only be true when called from a slot invoked by a QMailStore signal.

int QMailStore::countAccounts ( const QMailAccountKey & key = QMailAccountKey() ) const

Returns the count of the number of accounts which pass the filtering criteria defined in QMailAccountKey key. If key is empty a count of all accounts is returned.

int QMailStore::countFolders ( const QMailFolderKey & key = QMailFolderKey() ) const

Returns the count of the number of folders which pass the filtering criteria defined in QMailFolderKey key. If key is empty a count of all folders is returned.

int QMailStore::countMessages ( const QMailMessageKey & key = QMailMessageKey() ) const

Returns the count of the number of messages which pass the filtering criteria defined in QMailMessageKey key. If key is empty a count of all messages is returned.

void QMailStore::flushIpcNotifications ()

Forces any queued event notifications to immediately be synchronously emitted, and processed synchronously by recipient processes.

Any events occurring before flushIpcNotifications() is invoked will be processed by recipient processes before any IPC packets generated after the invocation.

QMailFolder QMailStore::folder ( const QMailFolderId & id ) const

Returns the QMailFolder defined by a QMailFolderId id from the message store.

void QMailStore::folderContentsModified ( const QMailFolderIdList & ids )   [signal]

Signal that is emitted when changes to messages in the mail store affect the content of the folders in the list ids.

See also messagesAdded(), messagesUpdated(), and messagesRemoved().

quint64 QMailStore::folderStatusMask ( const QString & name ) const

Returns the status bitmask needed to test the result of QMailFolder::status() against the QMailFolder status flag registered with the identifier name.

See also registerFolderStatusFlag() and QMailFolder::statusMask().

void QMailStore::foldersAdded ( const QMailFolderIdList & ids )   [signal]

Signal that is emitted when the folders in the list ids are added to the mail store.

See also foldersRemoved() and foldersUpdated().

void QMailStore::foldersRemoved ( const QMailFolderIdList & ids )   [signal]

Signal that is emitted when the folders in the list ids are removed from the mail store.

See also foldersAdded() and foldersUpdated().

void QMailStore::foldersUpdated ( const QMailFolderIdList & ids )   [signal]

Signal that is emitted when the folders in the list ids are updated within the mail store.

See also foldersAdded() and foldersRemoved().

bool QMailStore::initialized () const

Returns true if the QMailStore object was correctly initialized.

QMailStore * QMailStore::instance ()   [static]

Returns an instance of the QMailStore object.

QMailMessage QMailStore::message ( const QMailMessageId & id ) const

Returns the QMailMessage defined by a QMailMessageId id from the message store.

QMailMessage QMailStore::message ( const QString & uid, const QMailAccountId & accountId ) const

This is an overloaded member function, provided for convenience.

Returns the QMailMessage defined by the unique identifier uid from the account with id accountId.

QMailMessageMetaData QMailStore::messageMetaData ( const QMailMessageId & id ) const

Returns the meta data for the message identified by the QMailMessageId id from the message store.

QMailMessageMetaData QMailStore::messageMetaData ( const QString & uid, const QMailAccountId & accountId ) const

This is an overloaded member function, provided for convenience.

Returns the meta data for the message identified by the unique identifier uid from the account with id accountId.

const QMailMessageRemovalRecordList QMailStore::messageRemovalRecords ( const QMailAccountId & accountId, const QString & fromMailbox = QString() ) const

Retrieves a list of QMailMessageRemovalRecord objects containing information about messages that have been removed from local storage. Records are retrived for messages whose account Id's match accountId and whose optional mailbox matches fromMailbox. This information is primarily for synchronization of local changes to remote message storage services such as IMAP servers.

Returns a list of QMailMessageRemovalRecord objects if successfully completed, or an empty list for an error or no data.

void QMailStore::messageRemovalRecordsAdded ( const QMailAccountIdList & ids )   [signal]

Signal that is emitted when QMailMessageRemovalRecords are added to the store, affecting the accounts listed in ids.

See also messageRemovalRecordsRemoved().

void QMailStore::messageRemovalRecordsRemoved ( const QMailAccountIdList & ids )   [signal]

Signal that is emitted when QMailMessageRemovalRecords are removed from the store, affecting the accounts listed in ids.

See also messageRemovalRecordsAdded().

quint64 QMailStore::messageStatusMask ( const QString & name ) const

Returns the status bitmask needed to test the result of QMailMessage::status() against the QMailMessage status flag registered with the identifier name.

See also registerMessageStatusFlag() and QMailMessage::statusMask().

void QMailStore::messagesAdded ( const QMailMessageIdList & ids )   [signal]

Signal that is emitted when the messages in the list ids are added to the mail store.

See also messagesRemoved() and messagesUpdated().

const QMailMessageMetaDataList QMailStore::messagesMetaData ( const QMailMessageKey & key, const QMailMessageKey::Properties & properties, ReturnOption option = ReturnAll ) const

Retrieves a list of QMailMessageMetaData objects containing meta data elements specified by properties, for messages which match the criteria defined by key. If option is ReturnAll then duplicate objects are included in the list; otherwise duplicate objects are excluded from the returned list.

Returns a list of QMailMessageMetaData objects if successfully completed, or an empty list for an error or no data.

void QMailStore::messagesRemoved ( const QMailMessageIdList & ids )   [signal]

Signal that is emitted when the messages in the list ids are removed from the mail store.

See also messagesAdded() and messagesUpdated().

void QMailStore::messagesUpdated ( const QMailMessageIdList & ids )   [signal]

Signal that is emitted when the messages in the list ids are updated within the mail store.

See also messagesAdded() and messagesRemoved().

bool QMailStore::purgeMessageRemovalRecords ( const QMailAccountId & accountId, const QStringList & serverUids = QStringList() )

Erases message deletion records from the account with id accountId and server uid listed in serverUids. If serverUids is empty, all message deletion records for the specified account are deleted.

Returns true if the operation completed successfully, false otherwise.

const QMailAccountIdList QMailStore::queryAccounts ( const QMailAccountKey & key = QMailAccountKey(), const QMailAccountSortKey & sortKey = QMailAccountSortKey() ) const

Returns the QMailAccountIds of accounts in the store. If key is not empty only accounts matching the parameters set by key will be returned, otherwise all accounts identifiers will be returned. If sortKey is not empty, the identifiers will be sorted by the parameters set by sortKey.

const QMailFolderIdList QMailStore::queryFolders ( const QMailFolderKey & key = QMailFolderKey(), const QMailFolderSortKey & sortKey = QMailFolderSortKey() ) const

Returns the QMailFolderIds of folders in the message store. If key is not empty only folders matching the parameters set by key will be returned, otherwise all folder identifiers will be returned. If sortKey is not empty, the identifiers will be sorted by the parameters set by sortKey.

const QMailMessageIdList QMailStore::queryMessages ( const QMailMessageKey & key = QMailMessageKey(), const QMailMessageSortKey & sortKey = QMailMessageSortKey() ) const

Returns the QMailMessageIds of messages in the message store. If key is not empty only messages matching the parameters set by key will be returned, otherwise all message identifiers will be returned. If sortKey is not empty, the identifiers will be sorted by the parameters set by sortKey.

bool QMailStore::registerFolderStatusFlag ( const QString & name )

Registers a status flag for QMailFolder objects, with the identifier name. Returns true if the flag is already registered, or if it is successfully registered; otherwise returns false.

See also folderStatusMask().

bool QMailStore::registerMessageStatusFlag ( const QString & name )

Registers a status flag for QMailMessage objects, with the identifier name. Returns true if the flag is already registered, or if it is successfully registered; otherwise returns false.

See also messageStatusMask().

bool QMailStore::removeAccount ( const QMailAccountId & id )

Removes a QMailAccount with QMailAccountId id from the store. Also removes any folder, message and message removal records associated with the removed account. Returns true if the operation completed successfully, false otherwise.

bool QMailStore::removeAccounts ( const QMailAccountKey & key )

Removes all QMailAccounts identified by the key key from the store. Also removes any folder, message and message removal records associated with the removed account. Returns true if the operation completed successfully, false otherwise.

bool QMailStore::removeFolder ( const QMailFolderId & id, MessageRemovalOption option = NoRemovalRecord )

Removes a QMailFolder with QMailFolderId id from the message store. Also removes any sub-folders of the identified folder, and any messages contained in any of the folders removed. If option is QMailStore::CreateRemovalRecord then removal records will be created for each removed message. Returns true if the operation completed successfully, false otherwise.

bool QMailStore::removeFolders ( const QMailFolderKey & key, MessageRemovalOption option = NoRemovalRecord )

Removes all QMailFolders identified by the key key from the message store. Also removes any sub-folders of the removed folders, and any messages contained in any of the folders removed. If option is QMailStore::CreateRemovalRecord then removal records will be created for each removed message. Returns true if the operation completed successfully, false otherwise.

bool QMailStore::removeMessage ( const QMailMessageId & id, MessageRemovalOption option = NoRemovalRecord )

Removes a QMailMessage with QMailMessageId id from the message store. If option is QMailStore::CreateRemovalRecord then a removal record will be created for the removed message. Returns true if the operation completed successfully, false otherwise.

bool QMailStore::removeMessages ( const QMailMessageKey & key, MessageRemovalOption option = NoRemovalRecord )

Removes all QMailMessages identified by the key key from the message store. If option is QMailStore::CreateRemovalRecord then removal records will be created for each removed message. Returns true if the operation completed successfully, false otherwise.

bool QMailStore::restoreToPreviousFolder ( const QMailMessageId & id )

Updates the QMailMessage with QMailMessageId id to move the message back to the previous folder it was contained by.

Returns true if the operation completed successfully, false otherwise.

bool QMailStore::restoreToPreviousFolder ( const QMailMessageKey & key )

This is an overloaded member function, provided for convenience.

Updates all QMailMessages identified by the key key to move the messages back to the previous folder they were contained by.

Returns true if the operation completed successfully, false otherwise.

int QMailStore::sizeOfMessages ( const QMailMessageKey & key = QMailMessageKey() ) const

Returns the total size of the messages which pass the filtering criteria defined in QMailMessageKey key. If key is empty the total size of all messages is returned.

bool QMailStore::storeInitialized ()   [static]

Returns true if the QMailStore was correctly initialized.

bool QMailStore::updateAccount ( QMailAccount * account, AccountConfiguration * config = 0 )

Updates the existing QMailAccount account on the store, with the configuration details optionally specified by config. Returns true if the operation completed successfully, false otherwise.

bool QMailStore::updateFolder ( QMailFolder * folder )

Updates the existing QMailFolder folder on the message store. Returns true if the operation completed successfully, false otherwise.

bool QMailStore::updateMessage ( QMailMessage * msg )

Updates the existing QMailMessage msg on the message store. Returns true if the operation completed successfully, or false otherwise.

bool QMailStore::updateMessage ( QMailMessageMetaData * metaData )

This is an overloaded member function, provided for convenience.

Updates the meta data of the existing message on the message store, to match metaData. Returns true if the operation completed successfully, or false otherwise.

bool QMailStore::updateMessagesMetaData ( const QMailMessageKey & key, const QMailMessageKey::Properties & properties, const QMailMessageMetaData & data )

Updates the message properties defined in properties to match the respective element contained in the data, for all messages which match the criteria defined by key.

Returns true if the operation completed successfully, or false otherwise.

bool QMailStore::updateMessagesMetaData ( const QMailMessageKey & key, quint64 status, bool set )

This is an overloaded member function, provided for convenience.

Updates message status flags set in status according to set, for messages which match the criteria defined by key.

Returns true if the operation completed successfully, or false otherwise.