diff -r cfcbf08528c4 -r 2b40d63a9c3d qtmobility/src/messaging/qmessageservice.cpp --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/qtmobility/src/messaging/qmessageservice.cpp Fri Apr 16 15:51:22 2010 +0300 @@ -0,0 +1,348 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the Qt Mobility Components. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +#include "qmessageservice.h" +#ifdef Q_OS_SYMBIAN +#include "qmessageservice_symbian_p.h" +#endif + + +QTM_BEGIN_NAMESPACE + +/*! + \class QMessageService + + \preliminary + \ingroup messaging + + \brief The QMessageService class provides the interface for requesting + messaging service operations. + + QMessageService provides the mechanisms for messaging clients to request services, + and to receive information in response. All requestable service operations present + the same interface for communicating status, and progress information. + + All service request operations communicate changes in their operational state + by emitting the activityChanged() signal. + + Service request operations report progress information by emitting the + progressChanged() signal. + + If a requested operation fails after being initiated then the error() + function will return a value indicating the failure mode encountered. + + A client may attempt to cancel a requested operation after it has been + initiated. The cancel() slot is provided for this purpose. Cancelation + is not guaranteed to succeed, and is not possible on all platforms. + + A QMessageService instance supports only a single request at a time. Attempting + to initiate an operation on a QMessageService while another operation is already + in progress will result in function initiating the latter request returning + false. A client may, however, use multiple QMessageService instances to + concurrently initiate a queue of requests that will be serviced sequentially. + + Each QMessageService instance will report only the changes pertaining to + the request that instance initiated. + + Except where noted QMessageServices may initiate network activity. + Other functions in the mobility messaging API will not initiate network + activity, with the exception of Windows mobile and desktop platforms which + may initiate network activity during the evaluation of any function call. +*/ + +/*! + \enum QMessageService::State + + This enum type is used to describe the state of the requested operation. + + \value InactiveState The operation has not yet begun execution. + \value ActiveState The operation is currently executing. + \value CanceledState The operation was canceled. + \value FinishedState The operation has finished execution; succesfully completed or otherwise. +*/ + +/*! + \fn QMessageService::QMessageService(QObject *parent) + + Constructs a message service representation object. + + The \a parent is passed to the QObject constructor. +*/ + +/*! + \fn QMessageService::~QMessageService() + + Destroys the message service representation. +*/ + +/*! + \fn QMessageService::queryMessages(const QMessageFilter &filter, const QMessageSortOrder &sortOrder, uint limit, uint offset) + + Emits via messagesFound() signals \l{QMessageId}s of messages in the messaging + store. If \a filter is not empty only identifiers for messages matching the parameters + set by \a filter will be emitted, otherwise identifiers for all messages will be emitted. + 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 + ids in the list returned. + \a offset specifies how many ids to skip at the beginning of the list returned. + + Calling this function may result in the messagesFound() and progressChanged() + signals being emitted multiple times. An emission of the progressChanged() + signal with a total of 0 indicates that the number of progress steps is + unknown. + + Returns true if the operation can be initiated; otherwise returns false. + + Note: This function should not initiate network activity, instead only message data + already stored on the device will be used during evaluation of the function. + + \sa QMessage, QMessageFilter, QMessageSortOrder, messagesFound(), progressChanged(), countMessages() +*/ + +/*! + \fn QMessageService::queryMessages(const QMessageFilter &filter, const QString &body, QMessageDataComparator::MatchFlags matchFlags, const QMessageSortOrder &sortOrder, uint limit, uint offset) + + Emits via the messagesFound() signal \l{QMessageId}s of messages in the messaging + store. If \a filter is not empty only identifiers for messages matching the parameters + set by \a filter and with a body containing the string \a body will be emitted, + otherwise identifiers for all messages with a body containing \a body using + matching flags \a matchFlags will be emitted. + 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 + ids in the list returned. + \a offset specifies how many ids to skip at the beginning of the list returned. + + Calling this function may result in the messagesFound() and progressChanged() + signals being emitted multiple times. An emission of the progressChanged() + signal with a total of 0 indicates that the number of progress steps is + unknown. + + Returns true if the operation can be initiated; otherwise returns false. + + Note: This function should not initiate network activity, instead only message data + already stored on the device will be used during evaluation of the function. + + \sa QMessage, QMessageFilter, QMessageSortOrder, messagesFound(), progressChanged(), countMessages() +*/ + +/*! + \fn QMessageService::countMessages(const QMessageFilter &filter) + + Emits via a messagesCounted() signal the number messages in the messaging + store matching \a filter. + + Calling this function may result in the progressChanged() + signal being emitted multiple times. An emission of the progressChanged() + signal with a total of 0 indicates that the number of progress steps is + unknown. + + Returns true if the operation can be initiated; otherwise returns false. + + Note: This function should not initiate network activity, instead only message data + already stored on the device will be used during evaluation of the function. + + \sa QMessage, QMessageFilter, messagesCounted(), progressChanged(), queryMessages() +*/ + +/*! + \fn QMessageService::send(QMessage &message) + + Transmit \a message using the account identified by the message's \l{QMessage::parentAccountId()}{parentAccountId} function. + If the message does not have a valid parentAccountId, it will be set to the + result of QMessageAccount::defaultAccount() for the message's \l{QMessage::Type}{type}. + + The message will be stored in the standard Outbox folder for the account before + transmission, or moved to that folder if it is already stored in another folder. + If transmission is successful, the message will be moved to the standard Sent + folder for the account. + + Returns true if the operation can be initiated; otherwise returns false. + + \sa QMessage, QMessageAccountId +*/ + +/*! + \fn QMessageService::compose(const QMessage &message) + + Open a composer application using \a message as a prototype. + + The default application for handling the type of \a message should be used. + + Returns true if the operation can be initiated; otherwise returns false. + + On the QMF platform implementation of this function is left as a task for system + integrators. + + \sa QMessage::type() +*/ + +/*! + \fn QMessageService::retrieveHeader(const QMessageId& id) + + Retrieve meta data of the message identified by \a id. + + The meta data (including flags, from, to, subject, and date fields where applicable) of + the message identified by \a id should be retrieved. If only the message envelope + information is present, any other accessible header information should be retrieved. + + If the message can not be found on the originating server it will be marked as removed. + + Returns true if the operation can be initiated; otherwise returns false. + + \sa QMessageId, QMessage::Removed +*/ + +/*! + \fn QMessageService::retrieveBody(const QMessageId& id) + + Retrieve the body of the message identified by \a id. + + If the message can not be found on the originating server it will be marked as removed. + + Returns true if the operation can be initiated; otherwise returns false. + + \sa QMessageId, QMessage::Removed +*/ + +/*! + \fn QMessageService::retrieve(const QMessageId &messageId, const QMessageContentContainerId& id) + + Retrieve the container identified by \a messageId and \a id, the contents of the container should also be + retrieved. + + Returns true if the operation can be initiated; otherwise returns false. + + \sa QMessageContentContainerId +*/ + +/*! + \fn QMessageService::show(const QMessageId& id) + + Show the message identified by \a id. + + The default application for handling the type of message that \a id identifies should be used. + + Returns true if the operation can be initiated; otherwise returns false. + + On the QMF platform implementation of this function is left as a task for system + integrators. + + \sa QMessageId, QMessage::type() +*/ + +/*! + \fn QMessageService::exportUpdates(const QMessageAccountId &id) + + Initiate synchronization with external servers of local changes that have been queued by message store operations, + for messages with parent account \a id. + + On Windows mobile and desktop platforms this function performs no operation, as when a connection is available, + local changes are opportunistically synchronized with external servers. + + Returns true if the operation can be initiated; otherwise returns false. + + \sa QMessageManager::addMessage(), QMessageManager::updateMessage(), QMessageManager::removeMessage(), QMessageManager::removeMessages() +*/ + +/*! + \fn QMessageService::state() const + + Returns the current state of the operation. + + \sa stateChanged() +*/ + +/*! + \fn QMessageService::cancel() + + Attempts to cancel the last requested operation. +*/ + +/*! + \fn QMessageService::stateChanged(QMessageService::State newState) + + This signal is emitted when the state of the operation changes, with the new state described by \a newState. + + \sa state() +*/ + +/*! + \fn QMessageService::messagesFound(const QMessageIdList &ids); + + This signal is emitted when a queryMessages() operation has found + messages. + + \a ids is the list of identifiers of messages found. + + \sa queryMessages() +*/ + +/*! + \fn QMessageService::messagesCounted(int count); + + This signal is emitted when a countMessages() operation has counted + messages. + + \a count is the number of matching messages found. + + \sa queryMessages() +*/ + +/*! + \fn QMessageService::progressChanged(uint value, uint total) + + This signal is emitted when the operation operation has progressed. + + \a total is the total number of progress steps to perform, or zero if + the number of progress steps is unknown. + + \a value is the number of progress steps completed so far. +*/ + +/*! + \fn QMessageService::error() const + + Returns a value indicating the last error condition encountered by the operation. +*/ + +#include "moc_qmessageservice.cpp" +QTM_END_NAMESPACE