diff options
Diffstat (limited to 'src/messaging/qmessagemanager.cpp')
| -rw-r--r-- | src/messaging/qmessagemanager.cpp | 266 |
1 files changed, 134 insertions, 132 deletions
diff --git a/src/messaging/qmessagemanager.cpp b/src/messaging/qmessagemanager.cpp index 08f684190a..456307041f 100644 --- a/src/messaging/qmessagemanager.cpp +++ b/src/messaging/qmessagemanager.cpp @@ -51,47 +51,48 @@ QTM_BEGIN_NAMESPACE \brief The QMessageManager class represents the main interface for storage and retrieval of messages, folders and accounts in the system message store. - + \inmodule QtMessaging - + \ingroup messaging + \since 1.0 The system contains a single store for messages, which is accessed via the handle - class QMessageManager. QMessageManager provides the interface for adding, updating - and deleting messages in the system's message store. - + class QMessageManager. QMessageManager provides the interface for adding, updating + and deleting messages in the system's message store. + QMessageManager provides the countFolders() and queryFolders() functions for - counting and listing the folders contained by the messaging store, and the + counting and listing the folders contained by the messaging store, and the countAccounts() and queryAccounts() functions for counting and listing the accounts contained by the store. These functions use the QMessageFolderFilter - and QMessageFolderSortOrder classes, and the QMessageAccountFilter and + and QMessageFolderSortOrder classes, and the QMessageAccountFilter and QMessageAccountSortOrder classes to constrain their searches. - QMessageManager also implements functionality allowing the messages contained by the + QMessageManager also implements functionality allowing the messages contained by the store to be counted or listed, using various filtering and sortOrder constraints. Clients can access this functionality via the \l{QMessageService::countMessages()}{countMessages} and \l{QMessageService::queryMessages()}{queryMessages} functions of the QMessageService class. - - With the exception of Windows mobile and desktop platforms, QMessageManager functions - should not initiate network activity. Instead functions are restricted to operating - on data already on the device. See QMessageService for functions related to + + With the exception of Windows mobile and desktop platforms, QMessageManager functions + should not initiate network activity. Instead functions are restricted to operating + on data already on the device. See QMessageService for functions related to initiating network activity. If a QMessageManager operation fails, the error() function will return an error code - value indicating the failure mode encountered. A successful operation will set the + value indicating the failure mode encountered. A successful operation will set the error() result to QMessageManager::NoError. - Messages in the messaging store are identified by QMessageId objects. The data associated - with a message is retrieved in the form of a QMessage object using message(). Likewise - a folder is retrieved in the form of a QMessageFolder object using folder(), and an + Messages in the messaging store are identified by QMessageId objects. The data associated + with a message is retrieved in the form of a QMessage object using message(). Likewise + a folder is retrieved in the form of a QMessageFolder object using folder(), and an account is retrieved in the form of a QMessageAccount object using account(). - Messages can be inserted into the store using the addMessage() function, messages in the - store can be manipulated via the updateMessage() function, and removed by the + Messages can be inserted into the store using the addMessage() function, messages in the + store can be manipulated via the updateMessage() function, and removed by the removeMessage() functions. - - Messaging store manipulations involving messages are reported via the messagesAdded(), + + Messaging store manipulations involving messages are reported via the messagesAdded(), messagesUpdated() and messagesRemoved() signals. \sa QMessage, QMessageId, QMessageContentContainerId, QMessageService @@ -136,9 +137,9 @@ QTM_BEGIN_NAMESPACE /*! \fn QMessageManager::QMessageManager(QObject *parent) - + Constructs a handle to the message store. - + If \a parent is not 0 then the handle will be deleted when \a parent is deleted. */ QMessageManager::QMessageManager(QObject *parent) @@ -154,7 +155,7 @@ QMessageManager::QMessageManager(QObject *parent) /*! \fn QMessageManager::~QMessageManager() - + Destroys the handle to the message store. */ QMessageManager::~QMessageManager() @@ -163,7 +164,7 @@ QMessageManager::~QMessageManager() /*! \fn QMessageManager::error() const - + Returns the code of the last error condition reported by the messaging store. */ QMessageManager::Error QMessageManager::error() const @@ -173,19 +174,19 @@ QMessageManager::Error QMessageManager::error() const /*! \fn QMessageManager::queryMessages(const QMessageFilter &filter, const QMessageSortOrder &sortOrder, uint limit, uint offset) const - - Returns the \l{QMessageId}s of messages in the messaging store. If \a filter is not empty - only messages matching the parameters set by \a filter will be returned, otherwise + + Returns the \l{QMessageId}s of messages in the messaging store. If \a filter is not empty + only messages matching the parameters set by \a filter will be returned, otherwise identifiers for all messages will be returned. - If \a sortOrder is not empty, then the identifiers will be sorted by the parameters + If \a sortOrder is not empty, then the identifiers will be sorted by the parameters set by \a sortOrder. - If \a limit is not zero, then \a limit places an upper bound on the number of + If \a limit is not zero, then \a limit places an upper bound on the number of ids in the list returned. \a offset specifies how many ids to skip at the beginning of the list returned. - - The performance of querying messages is currently significantly less than + + The performance of querying messages is currently significantly less than optimal for some querying criteria on some platforms. - + \sa error(), countMessages() */ QMessageIdList QMessageManager::queryMessages(const QMessageFilter &filter, const QMessageSortOrder &sortOrder, uint limit, uint offset) const @@ -195,19 +196,19 @@ QMessageIdList QMessageManager::queryMessages(const QMessageFilter &filter, cons /*! \fn QMessageManager::queryMessages(const QMessageFilter &filter, const QList<QMessageSortOrder> &sortOrders, uint limit, uint offset) const - - Returns the \l{QMessageId}s of messages in the messaging store. If \a filter is not empty - only messages matching the parameters set by \a filter will be returned, otherwise + + Returns the \l{QMessageId}s of messages in the messaging store. If \a filter is not empty + only messages matching the parameters set by \a filter will be returned, otherwise identifiers for all messages will be returned. If \a sortOrders is not empty, then the identifiers will be sorted by applying each sort order element in sequence. - If \a limit is not zero, then \a limit places an upper bound on the number of + If \a limit is not zero, then \a limit places an upper bound on the number of ids in the list returned. \a offset specifies how many ids to skip at the beginning of the list returned. - - The performance of querying messages is currently significantly less than + + The performance of querying messages is currently significantly less than optimal for some querying criteria on some platforms. - + \sa error(), countMessages() */ QMessageIdList QMessageManager::queryMessages(const QMessageFilter &filter, const QList<QMessageSortOrder> &sortOrders, uint limit, uint offset) const @@ -225,21 +226,21 @@ QMessageIdList QMessageManager::queryMessages(const QMessageFilter &filter, cons /*! \fn QMessageManager::queryMessages(const QMessageFilter &filter, const QString &body, QMessageDataComparator::MatchFlags matchFlags, const QMessageSortOrder &sortOrder, uint limit, uint offset) const - - Returns the \l{QMessageId}s of messages in the messaging store. If \a filter is not empty - only messages matching the parameters set by \a filter and with a body containing the - string \a body will be returned, otherwise identifiers for all messages with + + Returns the \l{QMessageId}s of messages in the messaging store. If \a filter is not empty + only messages matching the parameters set by \a filter and with a body containing the + string \a body will be returned, otherwise identifiers for all messages with a body containing \a body will be returned. - If \a sortOrder is not empty, then the identifiers will be sorted by the parameters + If \a sortOrder is not empty, then the identifiers will be sorted by the parameters set by \a sortOrder. - If \a limit is not zero, then \a limit places an upper bound on the number of + If \a limit is not zero, then \a limit places an upper bound on the number of ids in the list returned. \a offset specifies how many ids to skip at the beginning of the list returned. \a matchFlags specifies the matching method to use. - - The performance of querying messages is currently significantly less than + + The performance of querying messages is currently significantly less than optimal for some querying criteria on some platforms. - + \sa error(), countMessages() */ QMessageIdList QMessageManager::queryMessages(const QMessageFilter &filter, const QString &body, QMessageDataComparator::MatchFlags matchFlags, const QMessageSortOrder &sortOrder, uint limit, uint offset) const @@ -249,21 +250,21 @@ QMessageIdList QMessageManager::queryMessages(const QMessageFilter &filter, cons /*! \fn QMessageManager::queryMessages(const QMessageFilter &filter, const QString &body, QMessageDataComparator::MatchFlags matchFlags, const QList<QMessageSortOrder> &sortOrders, uint limit, uint offset) const - - Returns the \l{QMessageId}s of messages in the messaging store. If \a filter is not empty - only messages matching the parameters set by \a filter and with a body containing the - string \a body will be returned, otherwise identifiers for all messages with + + Returns the \l{QMessageId}s of messages in the messaging store. If \a filter is not empty + only messages matching the parameters set by \a filter and with a body containing the + string \a body will be returned, otherwise identifiers for all messages with a body containing \a body will be returned. If \a sortOrders is not empty, then the identifiers will be sorted by applying each sort order element in sequence. - If \a limit is not zero, then \a limit places an upper bound on the number of + If \a limit is not zero, then \a limit places an upper bound on the number of ids in the list returned. \a offset specifies how many ids to skip at the beginning of the list returned. \a matchFlags specifies the matching method to use. - - The performance of querying messages is currently significantly less than + + The performance of querying messages is currently significantly less than optimal for some querying criteria on some platforms. - + \sa error(), countMessages() */ QMessageIdList QMessageManager::queryMessages(const QMessageFilter &filter, const QString &body, QMessageDataComparator::MatchFlags matchFlags, const QList<QMessageSortOrder> &sortOrders, uint limit, uint offset) const @@ -281,16 +282,16 @@ QMessageIdList QMessageManager::queryMessages(const QMessageFilter &filter, cons /*! \fn QMessageManager::queryFolders(const QMessageFolderFilter &filter, const QMessageFolderSortOrder &sortOrder, uint limit, uint offset) const - - Returns the \l{QMessageFolderId}s of folders in the messaging store. If \a filter + + Returns the \l{QMessageFolderId}s of folders in the messaging store. If \a filter is not empty only folders matching the parameters set by \a filter will be returned, otherwise identifiers for all folders will be returned. - If \a sortOrder is not empty, then the identifiers will be sorted by the parameters + If \a sortOrder is not empty, then the identifiers will be sorted by the parameters set by \a sortOrder. - If \a limit is not zero, then \a limit places an upper bound on the number of + If \a limit is not zero, then \a limit places an upper bound on the number of ids in the list returned. \a offset specifies how many ids to skip at the beginning of the list returned. - + \sa error(), countFolders() */ QMessageFolderIdList QMessageManager::queryFolders(const QMessageFolderFilter &filter, const QMessageFolderSortOrder &sortOrder, uint limit, uint offset) const @@ -300,16 +301,16 @@ QMessageFolderIdList QMessageManager::queryFolders(const QMessageFolderFilter &f /*! \fn QMessageManager::queryFolders(const QMessageFolderFilter &filter, const QList<QMessageFolderSortOrder> &sortOrders, uint limit, uint offset) const - - Returns the \l{QMessageFolderId}s of folders in the messaging store. If \a filter + + Returns the \l{QMessageFolderId}s of folders in the messaging store. If \a filter is not empty only folders matching the parameters set by \a filter will be returned, otherwise identifiers for all folders will be returned. If \a sortOrders is not empty, then the identifiers will be sorted by applying each sort order element in sequence. - If \a limit is not zero, then \a limit places an upper bound on the number of + If \a limit is not zero, then \a limit places an upper bound on the number of ids in the list returned. \a offset specifies how many ids to skip at the beginning of the list returned. - + \sa error(), countFolders() */ QMessageFolderIdList QMessageManager::queryFolders(const QMessageFolderFilter &filter, const QList<QMessageFolderSortOrder> &sortOrders, uint limit, uint offset) const @@ -327,16 +328,16 @@ QMessageFolderIdList QMessageManager::queryFolders(const QMessageFolderFilter &f /*! \fn QMessageManager::queryAccounts(const QMessageAccountFilter &filter, const QMessageAccountSortOrder &sortOrder, uint limit, uint offset) const - - Returns the \l{QMessageAccountId}s of accounts in the messaging store. If \a filter - is not empty only accounts matching the parameters set by \a filter will be returned, + + Returns the \l{QMessageAccountId}s of accounts in the messaging store. If \a filter + is not empty only accounts matching the parameters set by \a filter will be returned, otherwise identifiers for all accounts will be returned. - If \a sortOrder is not empty, then the identifiers will be sorted by the parameters + If \a sortOrder is not empty, then the identifiers will be sorted by the parameters set by \a sortOrder. - If \a limit is not zero, then \a limit places an upper bound on the number of + If \a limit is not zero, then \a limit places an upper bound on the number of ids in the list returned. \a offset specifies how many ids to skip at the beginning of the list returned. - + \sa error(), countAccounts() */ QMessageAccountIdList QMessageManager::queryAccounts(const QMessageAccountFilter &filter, const QMessageAccountSortOrder &sortOrder, uint limit, uint offset) const @@ -346,16 +347,16 @@ QMessageAccountIdList QMessageManager::queryAccounts(const QMessageAccountFilter /*! \fn QMessageManager::queryAccounts(const QMessageAccountFilter &filter, const QList<QMessageAccountSortOrder> &sortOrders, uint limit, uint offset) const - - Returns the \l{QMessageAccountId}s of accounts in the messaging store. If \a filter - is not empty only accounts matching the parameters set by \a filter will be returned, + + Returns the \l{QMessageAccountId}s of accounts in the messaging store. If \a filter + is not empty only accounts matching the parameters set by \a filter will be returned, otherwise identifiers for all accounts will be returned. If \a sortOrders is not empty, then the identifiers will be sorted by applying each sort order element in sequence. - If \a limit is not zero, then \a limit places an upper bound on the number of + If \a limit is not zero, then \a limit places an upper bound on the number of ids in the list returned. \a offset specifies how many ids to skip at the beginning of the list returned. - + \sa error(), countAccounts() */ QMessageAccountIdList QMessageManager::queryAccounts(const QMessageAccountFilter &filter, const QList<QMessageAccountSortOrder> &sortOrders, uint limit, uint offset) const @@ -371,14 +372,14 @@ QMessageAccountIdList QMessageManager::queryAccounts(const QMessageAccountFilter /*! \fn QMessageManager::countMessages(const QMessageFilter& filter) const - - Returns the number of messages which match the filtering criteria defined - in QMessageFilter \a filter. If \a filter is empty the count of all + + Returns the number of messages which match the filtering criteria defined + in QMessageFilter \a filter. If \a filter is empty the count of all available messages is returned. - - The performance of counting messages is currently significantly less than optimal + + The performance of counting messages is currently significantly less than optimal for some filters on some platforms. - + \sa error(), queryMessages() */ int QMessageManager::countMessages(const QMessageFilter& filter) const @@ -388,11 +389,11 @@ int QMessageManager::countMessages(const QMessageFilter& filter) const /*! \fn QMessageManager::countFolders(const QMessageFolderFilter& filter) const - - Returns the number of folders which match the filtering criteria defined - in QMessageFolderFilter \a filter. If \a filter is empty the count of all + + Returns the number of folders which match the filtering criteria defined + in QMessageFolderFilter \a filter. If \a filter is empty the count of all available folders is returned. - + \sa error(), queryFolders() */ int QMessageManager::countFolders(const QMessageFolderFilter& filter) const @@ -402,11 +403,11 @@ int QMessageManager::countFolders(const QMessageFolderFilter& filter) const /*! \fn QMessageManager::countAccounts(const QMessageAccountFilter& filter) const - - Returns the number of messages which match the filtering criteria defined - in QMessageAccountFilter \a filter. If \a filter is empty the count of all + + Returns the number of messages which match the filtering criteria defined + in QMessageAccountFilter \a filter. If \a filter is empty the count of all available accounts is returned. - + \sa error(), queryAccounts() */ int QMessageManager::countAccounts(const QMessageAccountFilter& filter) const @@ -416,17 +417,17 @@ int QMessageManager::countAccounts(const QMessageAccountFilter& filter) const /*! \fn QMessageManager::removeMessage(const QMessageId& id, RemovalOption option) - - Removes the message with QMessageId \a id from the messaging store. If \a option is - QMessageManager::RemoveOnOriginatingServer then when synchronization is performed the - message should be removed from both the local message store and the originating server + + Removes the message with QMessageId \a id from the messaging store. If \a option is + QMessageManager::RemoveOnOriginatingServer then when synchronization is performed the + message should be removed from both the local message store and the originating server if any. Returns \c true if the operation successfully updates the store; otherwise returns \c false. - + To ensure the change is propagated to any affected external server QMessageService::exportUpdates() should be subsequently called. - + \a option is ignored on Windows mobile and desktop platforms. \sa removeMessages(), addMessage(), updateMessage(), QMessageService::exportUpdates() @@ -438,19 +439,19 @@ bool QMessageManager::removeMessage(const QMessageId& id, QMessageManager::Remov /*! \fn QMessageManager::removeMessages(const QMessageFilter& filter, QMessageManager::RemovalOption option) - + Removes all messages identified by the filter \a filter from the messaging store. - If \a option is QMessageManager::RemoveOnOriginatingServer then when synchronization is performed the + If \a option is QMessageManager::RemoveOnOriginatingServer then when synchronization is performed the messages should be removed from both the local message store and the originating server if any. - Returns \c true if the operation successfully updates the store; otherwise returns \c false. - + Returns \c true if the operation successfully updates the store; otherwise returns \c false. + To ensure the change is propagated to any affected external server QMessageService::exportUpdates() should be subsequently called. \a option is ignored on Windows mobile and desktop platforms. - + For example: To implement a function to remove a list messages identified by QMessageIds @@ -476,6 +477,7 @@ bool QMessageManager::removeMessages(const QMessageFilter& filter, QMessageManag Remove account \a id and all associated information (folders, messages etc.) + On Windows mobile and desktop platforms, Maemo 5, and Symbian prior to SR1.11 this function performs no operation. */ bool QMessageManager::removeAccount(const QMessageAccountId &id) { @@ -484,21 +486,21 @@ bool QMessageManager::removeAccount(const QMessageAccountId &id) /*! \fn QMessageManager::addMessage(QMessage *message) - - Adds a copy of the message indicated by \a message to the messaging store - and modifies the message indicated by \a message to contain the identifier + + Adds a copy of the message indicated by \a message to the messaging store + and modifies the message indicated by \a message to contain the identifier of the created message. - Returns \c true if the operation successfully updates the store; otherwise returns \c false. - + Returns \c true if the operation successfully updates the store; otherwise returns \c false. + To ensure the change is propagated to any affected external server QMessageService::exportUpdates() should be subsequently called. - - On the Maemo 5 (Fremantle) platform for SMS type messages this function is not yet + + On the Maemo 5 (Fremantle) platform for SMS type messages this function is not yet supported. - + Using this function to explicitly set a size or date is not currently supported on some platforms. - + \sa message(), updateMessage(), removeMessage(), QMessageService::exportUpdates() */ bool QMessageManager::addMessage(QMessage *m) @@ -508,22 +510,22 @@ bool QMessageManager::addMessage(QMessage *m) /*! \fn QMessageManager::updateMessage(QMessage *message) - - Updates the messaging store so that the message whose identifier is contained + + Updates the messaging store so that the message whose identifier is contained by the message at \a message contains the content at \a message. If \a message does not contain a valid identifier, no changes will result. Internal data of the QMessage object at \a message can be modified by this operation. - - Returns \c true if the operation successfully updates the store; otherwise returns \c false. - To ensure the change is propagated to any affected external server + Returns \c true if the operation successfully updates the store; otherwise returns \c false. + + To ensure the change is propagated to any affected external server QMessageService::exportUpdates() should be subsequently called. Using this function to explicitly set a size or date is not currently supported on some platforms. - - On the Maemo 5 (Fremantle) platform this function may only be used to update the priority and + + On the Maemo 5 (Fremantle) platform this function may only be used to update the priority and status of email type messages. - + \sa addMessage(), removeMessage(), QMessageService::exportUpdates() */ bool QMessageManager::updateMessage(QMessage *m) @@ -533,7 +535,7 @@ bool QMessageManager::updateMessage(QMessage *m) /*! \fn QMessageManager::message(const QMessageId& id) const - + Returns the QMessage identified by \a id from the store. */ QMessage QMessageManager::message(const QMessageId& id) const @@ -543,7 +545,7 @@ QMessage QMessageManager::message(const QMessageId& id) const /*! \fn QMessageManager::folder(const QMessageFolderId& id) const - + Returns the QMessageFolder identified by \a id from the store. */ QMessageFolder QMessageManager::folder(const QMessageFolderId& id) const @@ -553,7 +555,7 @@ QMessageFolder QMessageManager::folder(const QMessageFolderId& id) const /*! \fn QMessageManager::account(const QMessageAccountId& id) const - + Returns the QMessageAccount identified by \a id from the store. */ QMessageAccount QMessageManager::account(const QMessageAccountId& id) const @@ -565,12 +567,12 @@ QMessageAccount QMessageManager::account(const QMessageAccountId& id) const \fn NotificationFilterId QMessageManager::registerNotificationFilter(const QMessageFilter &filter); Registers a message filter that will be used to generate messageAdded(), messageRemoved() - and messageUpdated() signals. Returns an identifier value that can be used to identify the + and messageUpdated() signals. Returns an identifier value that can be used to identify the reason that a signal was emitted, and to unregister the filter at a later time. - The \a filter is applied to the state of the data after the occurrence of the event for which + The \a filter is applied to the state of the data after the occurrence of the event for which a notification may be emitted. - + On Linux, Maemo 6 (Harmattan) and Meego.com it is only possible to filter messageRemoved() signals with an empty QMessageFilter() that matches all messages. @@ -584,7 +586,7 @@ QMessageManager::NotificationFilterId QMessageManager::registerNotificationFilte /*! \fn void QMessageManager::unregisterNotificationFilter(NotificationFilterId notificationFilterId); - Removes the message filter associated with \a notificationFilterId from the set used + Removes the message filter associated with \a notificationFilterId from the set used to generate message event signals. \sa registerNotificationFilter(), messageAdded(), messageRemoved(), messageUpdated() @@ -598,9 +600,9 @@ void QMessageManager::unregisterNotificationFilter(NotificationFilterId notifica \fn void QMessageManager::messageAdded(const QMessageId &id, const QMessageManager::NotificationFilterIdSet &matchingFilterIds); Signal that is emitted when the message identified by \a id is added to the message store. - \a matchingFilterIds contains a set of values identifiying registered notification filters + \a matchingFilterIds contains a set of values identifiying registered notification filters that matched the message. - + \sa messageRemoved(), messageUpdated(), registerNotificationFilter() */ @@ -608,10 +610,10 @@ void QMessageManager::unregisterNotificationFilter(NotificationFilterId notifica \fn void QMessageManager::messageRemoved(const QMessageId &id, const QMessageManager::NotificationFilterIdSet &matchingFilterIds); Signal that is emitted when the message identified by \a id is removed from the message store. - \a matchingFilterIds contains a set of values identifiying registered notification filters + \a matchingFilterIds contains a set of values identifiying registered notification filters that matched the message. - Since the filters apply to the state of the data after the message removal, the only + Since the filters apply to the state of the data after the message removal, the only data item that may be subject to filtration is the identifier of the removed message. \sa messageAdded(), messageUpdated(), registerNotificationFilter() @@ -621,11 +623,11 @@ void QMessageManager::unregisterNotificationFilter(NotificationFilterId notifica \fn void QMessageManager::messageUpdated(const QMessageId &id, const QMessageManager::NotificationFilterIdSet &matchingFilterIds); Signal that is emitted when the message identified by \a id is updated in the message store. - \a matchingFilterIds contains a set of values identifiying registered notification filters + \a matchingFilterIds contains a set of values identifiying registered notification filters that matched the message. - Since the filters apply to the state of the data after the message modification, updates - to messages which matched a given filter prior to modification but not afterwards will not + Since the filters apply to the state of the data after the message modification, updates + to messages which matched a given filter prior to modification but not afterwards will not result in the emission of the messageUpdated signal. \sa messageAdded(), messageRemoved(), registerNotificationFilter() |