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