diff -r 000000000000 -r 8466d47a6819 emailservices/emailframework/commonlib/inc/CFSMailBox.h --- /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& 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 ); + + IMPORT_C void SearchL( const RPointerArray& aSearchStrings, + const TFSMailSortCriteria& aSortCriteria, + MFSMailBoxSearchObserver& aSearchObserver, + RArray 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& aRecipients, + const RPointerArray& aCCRecipients, + const RPointerArray& 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& 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 iFolders; + +}; + +#endif