Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions codeless banner

QMailMessageServer Class Reference
[QtMessagingModule, QtPimModule]

The QMailMessageServer class provides signals and slots which implement a convenient interface for communicating with the MessageServer process via IPC. More...

    #include <QMailMessageServer>

This class is under development and is subject to change.

Inherits QObject.

Public Types

Public Functions

Public Slots

Signals

Additional Inherited Members


Detailed Description

The QMailMessageServer class provides signals and slots which implement a convenient interface for communicating with the MessageServer process via IPC.

Qt Extended messaging applications can send and receive messages of various types by communicating with the external MessageServer application. The MessageServer application is a separate process, communicating with clients via inter-process messages. QMailMessageServer acts as a proxy object for the server process, providing an interface for communicating with the MessageServer by the use of signals and slots in the client process. It provides Qt signals corresponding to messages received from the MessageServer application, and Qt slots which send messages to the MessageServer when invoked.

For most messaging client applications, the QMailServiceAction objects offer a simpler interface for requesting actions from the messageserver, and assessing their results.

Note: the functions performed by the message server and the interface to them provided by the QMailMessageServer class are expected to change in a future release of Qt Extended, to provide a finer-grained interface for communicating with external services.

New Messages

When a client initiates communication with the MessageServer, the server informs the client of the number and type of 'new' messages, via the newCountChanged() signal. 'New' messages are those that arrive without the client having first requested their retrieval. The client may choose to invalidate the 'new' status of these messages; if the acknowledgeNewMessages() slot is invoked, the count of 'new' messages is reset to zero for the nominated message types. If the count of 'new' messages changes while a client is active, the newCountChanged() signal is emitted with the updated information.

Sending Messages

To send messages, the client should construct instances of the QMailMessage class formulated to contain the desired content. These messages should be stored to the mail store, then submitted for transmission by their QMailMessageId values, via the send() slot. The MessageServer will determine how to transmit each message by inspecting the account associated with the message.

If the MessageServer application succeeds in sending a message, the messageSent() signal is emitted to notify the client. After transmission has been attempted for each message in the list, the sendCompleted() signal is emitted; any messages for which a messageSent() signal was not emitted were not successfully transmitted.

After a send operation is initiated, the MessageServer emits the sendTotal() signal to indicate the approximate extent of the transmission effort. As progress is made in performing the transmission operation, the sendProgress() signal is repeatedly emitted to report the progress toward completion of the operation.

Retrieving Messages

To retrieve messages, the client should invoke the retrieve() slot with the identifier for the account to retrieve new messages for. If new messages are discovered, the messageRetrieved() signal is emitted for each message. After retrieval has been attempted for all new messages, the retrievalCompleted() signal is emitted.

After a retrieval operation is initiated, the MessageServer emits the retrievalTotal() signal to indicate the approximate extent of the retrieval effort. As progress is made in performing the retrieval operation, the retrievalProgress() signal is repeatedly emitted to report the progress toward completion of the operation.

Partial Retrieval

If the message type supports partial retrieval (such as with POP or IMAP email messages), the partialMessageRetrieved() signal is emitted for each message once it has been partially retrieved. After all new messages have been partially retrieved, the partialRetrievalCompleted() signal is emitted.

Completing Partial Retrievals

The client must invoke the completeRetrieval() operation in response to receiving the partialRetrievalCompleted() signal, to complete the retrieval operation. A client may also invoke the completeRetrieval() slot without first performing a retrieval operation. If the list of messages to complete is empty, no further retrieval action will be taken. For any messages contained in the list, the MessageServer will attempt to retrieve the remainder of the message. If the message whose retrieval is requested cannot be found on the external server, the mail store message record is updated to contain the Removed status flag. After retrieval completion has been attempted for all requested messages, the retrievalCompleted() signal is emitted.

Folder Retrieval

It is possible to retrieve only the folder structure of an account rather than the messages contained by the folders, by invoking retrieve() retrieve slot with the foldersOnly option set to true. When the folder retrieval operation is complete, it is not necessary to invoke the completeRetrieval() operation.

Cancellation

In order to cancel an operation previously initiated, the client can invoke the cancelTransfer() slot.

Server Status

As the MessageServer application performs the operations requested of it, it indicates the tasks it is performing by emitting the statusChanged() signal. If it encounters an error that prevents an operation from being performed, the errorOccurred() signal is emitted.

See also QMailServiceAction, QMailMessage, and QtopiaIpcAdaptor.


Member Type Documentation

enum QMailMessageServer::ErrorCode

This enum type defines error codes emitted by the MessageServer application.

ConstantValueDescription
QMailMessageServer::ErrNoError0No error has occurred.
QMailMessageServer::ErrUnknownResponseErrorCodeBaseThe response from an external server could not be processed correctly.
QMailMessageServer::ErrLoginFailed?The login attempt was refused by an external server.
QMailMessageServer::ErrCancel?The operation was cancelled by a user action.
QMailMessageServer::ErrFileSystemFull?The file system does not have enough space to support the requested operation.
QMailMessageServer::ErrNonexistentMessage?The specified message does not exist.
QMailMessageServer::ErrEnqueueFailed?The supplied message could not be enqueued for transmission.
QMailMessageServer::ErrNoConnection?No external network connection could be selected to use for transmission.
QMailMessageServer::ErrConnectionInUse?The external network connection is already in use.
QMailMessageServer::ErrConnectionNotReady?The external network connection could not be prepared for transmission.
QMailMessageServer::ErrConfiguration?The account in use does not have a valid configuration.
QMailMessageServer::ErrInvalidAddress?The supplied message does not have a conforming address specification.

enum QMailMessageServer::Operation

This enum type is used to indicate the type of server operation to which a status notification relates.

ConstantValueDescription
QMailMessageServer::None0The notification is not specifically relating to a send or retrieve operation.
QMailMessageServer::Send1The notification relates to a send operation.
QMailMessageServer::Retrieve2The notification relates to a retrieve operation.


Member Function Documentation

QMailMessageServer::QMailMessageServer ( QObject * parent = 0 )

Constructs a QMailMessageServer object with parent parent, and initiates communication with the MessageServer application.

QMailMessageServer::~QMailMessageServer ()

Destroys the QMailMessageServer object.

void QMailMessageServer::acknowledgeNewMessages ( const QMailMessageTypeList & types )   [slot]

Requests that the MessageServer reset the counts of 'new' messages to zero, for each message type listed in types.

See also newCountChanged().

void QMailMessageServer::cancelSearch ()   [slot]

Requests that the MessageServer cancel any pending search operations.

void QMailMessageServer::cancelTransfer ()   [slot]

Requests that the MessageServer cancel any pending transfer operations.

See also send(), retrieve(), and completeRetrieval().

void QMailMessageServer::completeRetrieval ( const QMailMessageIdList & mailList )   [slot]

Requests that the MessageServer complete the retrieval process for the messages in mailList. If the list contains messages from multiple accounts, only those from the account associated with the first message in the list will be retrieved.

See also partialRetrievalCompleted() and retrievalCompleted().

void QMailMessageServer::deleteMessages ( const QMailMessageIdList & mailList )   [slot]

Requests that the MessageServer delete the messages in mailList from the external server, if necessary for the relevant message type.

Deleting messages using this slot does not initiate communication with any external server; instead the information needed to delete the messages is recorded. Deletion from the external server will occur when messages are next retrieved from that server. Invoking this slot does not remove a message from the mail store.

See also QMailStore::removeMessage().

void QMailMessageServer::errorOccurred ( const QMailAccountId & accountId, const QString & text, int errorCode )   [signal]

Emitted when the MessageServer encounters an error while performing an action relating to the account with id accountId. The error is described by text and errorCode.

See also statusChanged().

void QMailMessageServer::matchingMessageIds ( const QMailMessageIdList & ids )   [signal]

Emitted after the successful completion of a search operation; ids contains the list of message identifiers located by the search.

See also searchMessages().

void QMailMessageServer::messageRetrieved ( const QMailMessageMetaData & message )   [signal]

Emitted when message has been retrieved from the external server. message is delivered in meta-data-only form, since the size of the entire message may be prohibitive.

See also retrieve().

void QMailMessageServer::messageSent ( const QMailMessageId & id )   [signal]

Emitted when the message identified by id has been transmitted to the external server.

See also send().

void QMailMessageServer::newCountChanged ( const QMailMessageCountMap & counts )   [signal]

Emitted when the count of 'new' messages changes; the new count is described by counts.

See also acknowledgeNewMessages().

void QMailMessageServer::partialMessageRetrieved ( const QMailMessageMetaData & message )   [signal]

Emitted when message has been partially retrieved from the external server. message is delivered in meta-data-only form, since the remainder of the message has not yet been retrieved from the server.

See also retrieve() and completeRetrieval().

void QMailMessageServer::partialRetrievalCompleted ()   [signal]

Emitted when all new messages have been partially retrieved.

See also retrieve().

void QMailMessageServer::retrievalCompleted ()   [signal]

Emitted when a retrieval operation is completed.

See also retrieve().

void QMailMessageServer::retrievalProgress ( uint value )   [signal]

Emitted during a retrieval operation; value reports the progress of the current retrieval operation.

See also retrievalTotal() and retrieve().

void QMailMessageServer::retrievalTotal ( uint total )   [signal]

Emitted when a retrieval operation is initiated; total indicates the extent of the retrieval operation to be performed.

See also retrievalProgress() and retrieve().

void QMailMessageServer::retrieve ( const QMailAccountId & id, bool foldersOnly )   [slot]

Requests that the MessageServer retrieve any new messages from the account with id id. If foldersOnly is true, only the folder structure of the account will be retrieved from the external service.

See also retrievalCompleted().

void QMailMessageServer::searchCompleted ()   [signal]

Emitted when a search operation is completed.

See also send().

void QMailMessageServer::searchMessages ( const QMailMessageKey & filter, const QString & bodyText )   [slot]

Requests that the MessageServer search for messages that meet the criteria encoded in filter. If bodyText is non-empty, messages must also contain the specified text in their content to be considered matching. If the content of a message is not stored locally, the MessageServer may connect to the originating server to request a content search, if necessary.

The identifiers of all matching messages are returned via matchingMessageIds() after the search is completed.

See also matchingMessageIds().

void QMailMessageServer::searchProgress ( uint value )   [signal]

Emitted during a search operation; value reports the progress of the current search operation.

See also searchTotal() and searchMessages().

void QMailMessageServer::searchTotal ( uint total )   [signal]

Emitted when a search operation is initiated; total indicates the extent of the search operation to be performed.

See also searchProgress() and searchMessages().

void QMailMessageServer::send ( const QMailMessageIdList & mailList )   [slot]

Sends the messages in mailList to the MessageServer application for transmission.

See also sendCompleted().

void QMailMessageServer::sendCompleted ()   [signal]

Emitted when a send operation is completed.

See also send().

void QMailMessageServer::sendProgress ( uint value )   [signal]

Emitted during a send operation; value reports the progress of the current send operation.

See also sendTotal() and send().

void QMailMessageServer::sendTotal ( uint total )   [signal]

Emitted when a send operation is initiated; total indicates the extent of the send operation to be performed.

See also sendProgress() and send().

void QMailMessageServer::statusChanged ( QMailMessageServer::Operation operation, const QString & accountName, const QString & text )   [signal]

Emitted whenever the MessageServer performs an action that may be of interest to the client. The server status is described by text, and relates to operation performed on the account named accountName.

See also errorOccurred().


Copyright © 2009 Nokia Trademarks
Qt Extended 4.4.3