/*

* 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

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