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