diff -r dcf0eedfc1a3 -r d189ee25cf9d emailservices/emailcommon/inc/CFSMailBox.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/emailservices/emailcommon/inc/CFSMailBox.h Tue Aug 31 15:04:17 2010 +0300 @@ -0,0 +1,467 @@ +/* +* Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: common mailbox object +* +*/ + + +#ifndef __CFSMAILBOX_H +#define __CFSMAILBOX_H + + +// +#include +// +#include "CFSMailBoxBase.h" + +// forward declarations +class CFSMailPlugin; +class MFSMailBoxSearchObserver; +class MFSMailEventObserver; +class MFSMailRequestObserver; + +// +class CFSMailFolder; +class CFSMailMessage; +class CFSMailRequestHandler; +// + +/** + * mailbox data handling + * + * @lib FSFWCommonLib + */ +NONSHARABLE_CLASS ( CFSMailBox ) : public CFSMailBoxBase +{ + public: + + /** + * Destructor. + */ + IMPORT_C ~CFSMailBox(); + + /** + * two based constructor + * + * @param aMailBoxId mailbox id in plugin containing mailbox + */ + IMPORT_C static CFSMailBox* NewL( TFSMailMsgId aMailBoxId ); + + /** + * two based constructor + * + * @param aMailBoxId mailbox id in plugin containing mailbox + */ + IMPORT_C static CFSMailBox* NewLC( TFSMailMsgId aMailBoxId ); + + /** + * Enables synchronization of the mailbox. This means + * that the framework can connect to server to do synchronization + * of the mailbox when necessary or stay connected all the time. + * The actual functionality depends on user settings and + * connection implementation. + * + * All collections (mail etc.) supported by the connection and + * enabled by user settings are synchronized. + * + * This function sets the mailbox online but it may + * have a side effect that also other mailboxes provided + * through the same connection are set online too. + * + * Connection is set offline normally by using specific function + * for this purpose. There are also other reasons for ending up + * in offline state like network error or scheduling. + * + */ + IMPORT_C void GoOnlineL(); + + /** + * Disables mailbox synchronization. Connection to server + * in order to synchronize the mailbox is not allowed + * after this. + * + * If GoOnlineL has effect on other mailboxes using the + * same connection then this function has effect on those + * mailboxes also. + * + */ + IMPORT_C void GoOfflineL(); + + /** + * Returns last synchronizing operation progress status. + * + * @return last sync operation progress status + * + */ + IMPORT_C TFSProgress GetLastSyncStatusL(); + + /** + * Forces synchronization of mailbox. This can be called + * whether the mailbox is currently offline or online. In the + * case the mailbox is offline in the beginning, connection + * is made up for the time of the synchronization. + * + * All collections (mail etc.) supported by the connection and + * enabled by user settings are synchronized. + * + * This is an asynchronous operation and the request id + * is returned for cancelling purpose. + * + * User can provide an observer as a parameter, + * which will pass progress notifications during the operation + * as callbacks related to this operation. + * + * Alternatively user can use overloaded parallel implementation + * of function without an observer function and rely only on + * general events. Notice that the general event system is not + * as comprehensive as the observing using dedicated observer. + * + * @param aOperationObserver optional observer given by user + * + * @return asynchronous request id + */ + IMPORT_C TInt RefreshNowL( MFSMailRequestObserver& aOperationObserver ); + + IMPORT_C TInt RefreshNowL( ); + + /** + * cancels all ongoing synchronizations in this mailbox regardless + * of initiator, by user or by plugin itself + * + */ + IMPORT_C void CancelSyncL(); + + /** + * creates into this mailbox new draft email + * + * @return new draft email object, ownership is transferred to user + */ + IMPORT_C CFSMailMessage* CreateMessageToSend( ); + +// + /** + * Creates a new draft email into this mailbox asynchronously. When the operation + * finishes, RequestResponseL is called on the observer and the created message is + * passed along with the TFSProgress data. UI should not use this method directly + * but via an NmMessageCreationOperation-derived object. + * + * @param aOperationObserver Observer for the operation + * + * @return id of the request, KErrFSMailPluginNotSupported if the protocol plugin this + * instance is attached to does not support the async method. + */ + IMPORT_C TInt CreateMessageToSendL( MFSMailRequestObserver& aOperationObserver ); +// + +// + /** + * update message flags + * + * ownership of message pointers is transferred + * + */ + IMPORT_C int UpdateMessageFlagsL( + const TFSMailMsgId aMailboxId, + RPointerArray &messages, + MFSMailRequestObserver& aOperationObserver ); +// + + /** + * creates into this mailbox new draft email to be forwarded + * + * @param aOriginalMessageId message id of the original message to be forwarded + * @param aHeaderDescriptor user can give quote headers data to plugin as + * parameter if needed + * + * @return new draft email object, ownership is transferred to user + */ + IMPORT_C CFSMailMessage* CreateForwardMessage( const TFSMailMsgId aOriginalMessageId, + const TDesC& aHeaderDescriptor = KNullDesC ); + +// + /** + * creates into this mailbox new draft email to be forwarded asynchronously + * When the operation finishes, RequestResponseL is called on the observer and + * the created message is passed along with the TFSProgress data. + * + * @param aOriginalMessageId message id of the original message to be forwarded + * @param aOperationObserver Observer for the operation + * @param aHeaderDescriptor user can give quote headers data to plugin as + * parameter if needed + * + * @return id of the request + */ + IMPORT_C TInt CreateForwardMessageL( const TFSMailMsgId aOriginalMessageId, + MFSMailRequestObserver& aOperationObserver, + const TDesC& aHeaderDescriptor = KNullDesC ); +// + + /** + * creates into this mailbox new email for reply + * + * @param aOriginalMessageId id of the original message to be replied + * @param aReplyToAll is set true if reply to all is requested + * @param aHeaderDescriptor user can give quote headers data to plugin as + * parameter if needed + * + * @return new draft email object, ownership is transferred to user + */ + IMPORT_C CFSMailMessage* CreateReplyMessage( const TFSMailMsgId aOriginalMessageId, + const TBool aReplyToAll, + const TDesC& aHeaderDescriptor = KNullDesC ); + +// + /** + * creates into this mailbox new email for reply + * + * @param aOriginalMessageId id of the original message to be replied + * @param aReplyToAll is set true if reply to all is requested + * @param aOperationObserver Observer for the operation + * @param aHeaderDescriptor user can give quote headers data to plugin as + * parameter if needed + * + * @return new draft email object, ownership is transferred to user + */ + IMPORT_C TInt CreateReplyMessageL( const TFSMailMsgId aOriginalMessageId, + const TBool aReplyToAll, + MFSMailRequestObserver& aOperationObserver, + const TDesC& aHeaderDescriptor = KNullDesC ); +// + + /** + * sends email + * + * @param aMessage message to be sent + */ + IMPORT_C void SendMessageL(CFSMailMessage& aMessage); + +// + /** + * sends email + * + * @param aMessage message to be sent + */ + IMPORT_C TInt SendMessageL( CFSMailMessage& aMessage, + MFSMailRequestObserver& aOperationObserver ); + +// + + /** + * List subfolders of given folder. + * Only direct subfolders of given folder are returned. + * + * folder data : + * - folder id + * - folder name + * - folder type ; Inbox, Outbox, Sent, Drafts, Deleted, Other + * - message count + * - unread message count + * - mailbox id + * - parent folder + * - subfolder count + * + * @param aFolderId defines parent folder id. TFSMailId::NullId() for root level list. + * @param aFolderList plugin writes results in this array owned by user + */ + IMPORT_C void ListFolders( const TFSMailMsgId aFolderId, RPointerArray& aFolderList); + + /** + * List all subfolders of mailbox. + * + * folder data : + * - folder id + * - folder name + * - folder type ; Inbox, Outbox, Sent Items, Drafts, Deleted Items, Other + * - message count + * - unread message count + * - mailbox id + * - parent folder + * - subfolder count + * + * @return results in this array owned by this object, caller must determine + * tree structure by examining parent id of each returned folder. + */ + IMPORT_C RPointerArray& ListFolders( ); + + /** + * Standard folder id accessor. + * + * @param aFolderType defines folder type + * @return standard folder id + */ + IMPORT_C TFSMailMsgId GetStandardFolderId( const TFSFolderType aFolderType ); + + + /** + * Branding id accessor for this mailbox. This function is used by Branding Manager + * to associate mailbox to a branding definition. + * + * @return branding id + */ + IMPORT_C TDesC& GetBrandingIdL( ); + + + /** + * Moves a messages between folders. + * + * @param aMessageIds ids of the messages to be transferred + * @param aSourceFolderId source folder id + * @param aDestinationFolderId destination folder id + */ + IMPORT_C void MoveMessagesL( const RArray& aMessageIds, + const TFSMailMsgId aSourceFolderId, + const TFSMailMsgId aDestinationFolderId ); + + /** + * Moves a messages between folders. Async version. + * + * @param MFSMailRequestObserver& aOperationObserver for callback + * @param aMessageIds ids of the messages to be transferred + * @param aSourceFolderId source folder id + * @param aDestinationFolderId destination folder id + */ + IMPORT_C TInt MoveMessagesL( MFSMailRequestObserver& aOperationObserver, + const RArray& aMessageIds, + const TFSMailMsgId aSourceFolderId, + const TFSMailMsgId aDestinationFolderId ); + /** + * Copies a messages from one folder to another folder. + * including the properties, content, and all attachments. + * (note only works if the store is in an authenticated state, + * otherwise this function leaves with KErrNotReady) + * + * @param aMessageIds ids of the messages to be copied + * @param aCopiedMessages table containing (new) ids of the copied messages + * owned by user + * @param aSourceFolderId source folder id + * @param aDestinationFolderId destination folder id + */ + IMPORT_C void CopyMessagesL( const RArray& aMessageIds, + RArray& aCopiedMessages, + const TFSMailMsgId aSourceFolderId, + const TFSMailMsgId aDestinationFolderId ); + + /** + * Asyncronous call for starting search for given string. Only one search can be + * performed at a time. + * + * This function will search for message's containing the given search string. + * The search will be performed on the all message fields: To, Cc, Bcc, subject, body. + * The search client will be notified of each found message, + * and upon completion of the search. Only one search can be performed at a time. + * + * To change the sort order in the search result, use the same search string in the + * but change the aSortCriteria parameter. The store "caches" the search + * results generated by the same search string. + * + * The function will leave with KErrInUse if a search is already in progress. + * + * note only works if the store is in an authenticated state, + * otherwise this function leaves with KErrNotReady + * + * @param aSearchStrings text strings that will be searched from different message fields. + * @param aSortCriteria sort criteria for the results + * @param aSortCriteria sort criteria for the results + * @param aFolderIds user can give list of folders to be searched + */ + IMPORT_C void SearchL( const RPointerArray& aSearchStrings, + const TFSMailSortCriteria& aSortCriteria, + MFSMailBoxSearchObserver& aSearchObserver ); + + /** + * Cancels current search. Does nothing if there is not any search ongoing. + * The search client will not be called back after this function is called. + * + * note CancelSearch() method does NOT clear the search result cached in the store. + * A different sort order can be used for the same search string, and the + * cache will be utilized. Only by using a different search string can the + * cache be cleaned. + */ + IMPORT_C void CancelSearch(); + + /** + * Inform the store to clean up its cache for search results. + * + * This method cancels the the ongoing search (if exists), and then clean ups store's cache. + * + * This function should be called by the UI when search results are no longer in display. + */ + IMPORT_C void ClearSearchResultCache(); + + /** + * DEPRECATED + * + * @param aFolderId... + * @param aObserver observer + */ + IMPORT_C void AddObserver(const TFSMailMsgId aFolderId, MFSMailEventObserver& aObserver); + + /** + * Returns the current synchronizing state of this mailbox. + * + * @return mailbox synchronizing state data structure + */ + IMPORT_C TSSMailSyncState CurrentSyncState() const; + + /** + * mailbox connection status accessor + * + * @return connection status, online / offline + */ + IMPORT_C TFSMailBoxStatus GetMailBoxStatus( ); + + +public: // from CExtendableEmail + + /** + * @see CExtendableEmail::ReleaseExtension() + */ + IMPORT_C void ReleaseExtension( CEmailExtension* aExtension ); + + /** + * Returns extension by uid, leaves KErrNotSupported if extension is + * not available. + * @param aInterfaceUid extension interface uid + * @return extension pointer. Ownership depends on extension. + */ + IMPORT_C CEmailExtension* ExtensionL( const TUid& aInterfaceUid ); + +private: + + /** + * Two-phased constructor + */ + void ConstructL( TFSMailMsgId aMailBoxId ); + + /** + * C++ default constructor. + */ + CFSMailBox(); + + + private: // data + + /** + * request handler for plugin requests + */ + CFSMailRequestHandler* iRequestHandler; + + /** + * mailbox folder list + */ + RPointerArray iFolders; + +}; + +#endif