--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/emailservices/emailframework/commonlib/inc/CFSMailBox.h Thu Dec 17 08:39:21 2009 +0200
@@ -0,0 +1,541 @@
+/*
+* 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 "cfsmailboxbase.h"
+
+// forward declarations
+class CFSMailPlugin;
+class MFSMailBoxSearchObserver;
+class MFSMailEventObserver;
+class MFSMailRequestObserver;
+
+/**
+ * mailbox data handling
+ *
+ * @lib FSFWCommonLib
+
+ */
+class CFSMailBox : public CFSMailBoxBase
+{
+ public:
+
+ /**
+ * Destructor.
+ */
+ ~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 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 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 );
+ /**
+ * sends email
+ *
+ * @param aMessage message to be sent
+ */
+ IMPORT_C void SendMessageL(CFSMailMessage& aMessage);
+
+ /**
+ * 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<CFSMailFolder>& 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<CFSMailFolder>& 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<TFSMailMsgId>& 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<TFSMailMsgId>& 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<TFSMailMsgId>& aMessageIds,
+ RArray<TFSMailMsgId>& 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<TDesC>& aSearchStrings,
+ const TFSMailSortCriteria& aSortCriteria,
+ MFSMailBoxSearchObserver& aSearchObserver );
+
+ IMPORT_C void SearchL( const RPointerArray<TDesC>& aSearchStrings,
+ const TFSMailSortCriteria& aSortCriteria,
+ MFSMailBoxSearchObserver& aSearchObserver,
+ RArray<TFSMailMsgId> aFolderIds );
+ /**
+ * 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);
+
+ /**
+ * Get a list of most recently used addresses of this mailbox.
+ * Each MRU entry consists of two descriptors placed sequentially
+ * in the array. First one is the display name and the second
+ * one is the actual email address. If for example some entry does
+ * not contain a name at all then a KNullDesC is found in place of
+ * the name.
+ *
+ * @return Array of descriptors containing MRUs. Ownership
+ * is transferred. Empty if no entries are found.
+ */
+ IMPORT_C MDesCArray* ListMrusL() const;
+
+ /**
+ * Returns the current synchronizing state of this mailbox.
+ *
+ * @return mailbox synchronizing state data structure
+ */
+ IMPORT_C TSSMailSyncState CurrentSyncState() const;
+
+ /**
+ * mailbox capability check for user
+ *
+ * @param aCapa mailbox capability to be checked
+ */
+ IMPORT_C TBool HasCapability(const TFSMailBoxCapabilities aCapability) const;
+
+ /**
+ * mailbox connection status accessor
+ *
+ * @return connection status, online / offline
+ */
+ IMPORT_C TFSMailBoxStatus GetMailBoxStatus( );
+
+ /**
+ * mailbox authentication data mutator
+ *
+ * @param aUsername account user name
+ * @param aPassword account password
+ */
+ IMPORT_C void SetCredentialsL( const TDesC& aUsername, const TDesC& aPassword );
+
+ /**
+ * removes downloaded attachments from local/terminal memory
+ */
+ IMPORT_C void RemoveDownLoadedAttachmentsL();
+
+ /**
+ * reads connection id from plugin
+ *
+ * @param aConnectionId reference to connection id
+ * @return KErrNone or error code
+ */
+ IMPORT_C TInt GetConnectionId( TUint32& aConnectionId );
+
+ /**
+ * checks from plugin if connection is allowed when roaming
+ *
+ * @param aConnectionAllowed
+ * @return KErrNone or error code
+ */
+ IMPORT_C TInt IsConnectionAllowedWhenRoaming( TBool& aConnectionAllowed) ;
+
+ /**
+ * creates email from RFC822 format data stream located
+ * in given attachment file
+ *
+ * @param aFile access to file containing data stream contents
+ * given by user
+ *
+ * return new email object, ownership is transferred to user
+ */
+ IMPORT_C CFSMailMessage* CreateMessageFromFileL( const RFile& aFile );
+
+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();
+
+ /**
+ * Function used internally to inform that Mru list related to this
+ * mailbox should now be updated using the given recipient info. In
+ * other words this function makes sure that the given recipients are
+ * found from the mru list in which the mrus of this mailbox are stored.
+ * Mrus are stored in the plugin.
+ *
+ * @param aRecipients email recipients in TO-field
+ * @param aCCRecipients email recipients in CC-field
+ * @param aBCCRecipients email recipients in BCC-field
+ */
+ void UpdateMrusL(
+ const RPointerArray<CFSMailAddress>& aRecipients,
+ const RPointerArray<CFSMailAddress>& aCCRecipients,
+ const RPointerArray<CFSMailAddress>& aBCCRecipients ) const;
+
+ /**
+ * Function used to copy array contents to another array.
+ *
+ * @param aArrayToBeCopied Array that should be copied.
+ * @return Copy of the given array.
+ */
+ CDesCArraySeg* CopyArrayL( MDesCArray& aArrayToBeCopied ) const;
+
+
+ /**
+ * Function used to update given mru list with
+ * recently used address info. If this info is already found
+ * from the mru list then it is moved to the end of the mru list.
+ * This way the most recent ones are found from the end
+ * of the list.
+ *
+ * @param aMruList Mru list that should be updated.
+ * @param aNewRecentlyUsedOnes Addresses that should be used
+ * to update the given mru list.
+ */
+ void UpdateMruListL(
+ CDesCArraySeg& aMruList,
+ const RPointerArray<CFSMailAddress>& aNewRecentlyUsedOnes ) const;
+
+
+ /**
+ * Function used to search an address from given mru list.
+ * Fucntion goes through the addresses in the mru list
+ * and returns the first one matching the given address.
+ *
+ * @param aMruList Mru list that is searched through.
+ * @param searchedAddress Address that is searched from the
+ * given mru list.
+ * @param aPos Reference parameter used to return the position
+ * of a matching address if such was found.
+ * @return Integer value to indicate whether the searched address
+ * was found or not. Zero is returned if the address was found.
+ * Otherwise 1 is returned.
+ */
+ TInt FindAddressFromMruList( CDesCArraySeg& aMruList,
+ TDesC& searchedAddress,
+ TInt& aPos ) const;
+
+ /**
+ * Removes the oldest entry from the mru list and adds
+ * given address info to the mru list.
+ *
+ * @param aMruList Mru list.
+ * @param aToBeAdded Address info to be added into the mru list.
+ */
+ void AddAndRemoveExcessMruL( CDesCArraySeg& aMruList,
+ CFSMailAddress& aToBeAdded ) const;
+
+ /**
+ * Function to append mru entry to the mru list. This implementation
+ * adds display name and then the address in this order into the
+ * mru list.
+ *
+ * @param aMruList Mru list.
+ * @param aToBeAdded Address info to be added into the mru list.
+ */
+ void AppendMruItemL( CDesCArraySeg& aMruList,
+ CFSMailAddress& aToBeAppended ) const;
+
+ /**
+ * Function to set the already existing entry in the mru list
+ * as the most recent one.
+ *
+ * @param aMruList Mru list that should be edited.
+ * @param aPosition Position where from the address element of
+ * the most recent address is found. The display
+ * name of the address is found with index one less
+ * from the mru list.
+ * @param aMostRecent After removal of the mru entry with given index,
+ * this entry is added into the mru list as the
+ * most recently used one.
+ */
+ void SetAsMostRecentMruL( CDesCArraySeg& aMruList,
+ TInt aPosition,
+ CFSMailAddress& aMostRecent ) const;
+
+ private: // data
+
+ /**
+ * request handler for plugin requests
+ */
+ CFSMailRequestHandler* iRequestHandler;
+
+ /**
+ * mailbox folder list
+ */
+ RPointerArray<CFSMailFolder> iFolders;
+
+};
+
+#endif