/*

* Copyright (c) 2007-2008 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:  email framework user interface

*

*/

#ifndef __FSMAILCLIENT_H

#define __FSMAILCLIENT_H

#include <e32std.h>

#include <e32base.h>

#include "CFSMailClient.hrh"

#include "cemailextensionbase.h"

#include "mfsmailbrandmanager.h"

#include "cfsmailplugin.h"

class CFSFWImplementation;

class CFSMailPluginManager;

	/**

	* @mainpage Freestyle Email API

	*

	* @section sec1 Introduction

	*

	*    This is the mail API and framework used by the Freestyle email

	*    client. It provides access to the message store for reading email

	*    and to the sync engine for starting and stopping synchronizations.

	*

	* @section sec2 Typical Usage From UI

	*

	*  	// Initialize the access to the mail framework

	*  	CFSMailClient* mail = CFSMailClient::NewL();

	*  	CleanupClosePushL(*mail);

    * 

	*  	// List mailboxes for user to select which one to open

	*	RPointerArray<CFSMailBox> mailBoxes;

	*	mailBoxes.Reset();

	*	TFSMailMsgId plugin; // null id if all mailboxes required

	*	mail->ListMailBoxes(plugin,mailBoxes);

    *   // Lets select the first one this time

	*  	CFSMailBox * currentMailbox = mailboxes[0]; 

    * 

	*   // list all mailbox folders for user

	*   RPointerArray<CFSMailFolder> folders = currentMailBox->ListFolders( );

	*

	*   // or get default folder, for example inbox

	*	TFSMailMsgId folderId;

	*	folderId = mailBox->GetStandardFolderId( EFSInbox );

	*  	CFSMailFolder* inbox = mail->GetFolderByUid(currentMailBox->GetId(),folderId);

	*

	*   // List messages in inbox

	*   // select message details to be listed

	*   TFSMailDetails details(EFSMsgDataStructure);

    *	

	*   // set sorting criteria

    *   TFSMailSortCriteria criteria;

    *   criteria.iField = EFSMailSortByDate;

    *   criteria.iOrder = EFSMailAscending;

    *   RArray<TFSMailSortCriteria> sorting;

    *   sorting.Append(criteria);

    *

    *   // get email list iterator from plugin

	*   MFSMailIterator* iterator = folder->ListMessagesL(details,sorting);

    *

    *   //  list all messages from folder

    *   TFSMailMsgId currentMessageId; // first call contains NULL id as begin id

    *   RPointerArray<CFSMailMessage> messages;

    *   messages.Reset();

    *   iterator->NextL(currentMessageId, folder->GetMessageCount(), messages);

    *		

	*   // Show the first 5 messages to in the UI

	*   for(TInt i=0;i<messages.Count() && i<5;i++)

	*   {

    *       MyHeaderShowMethod(messages[i]->GetSender().GetEmailAddress(),

    *                          messages[i]->GetSubject()

    *                          messages[i]->GetDate());

    *

    *       // get email body

	*       CFSMailMessagePart* body = messages[i]->PlainTextBodyPartL();

    *       if(body)

    *       {

    *           TBuf<n> text;

    *           TInt startOffset = 0;

    *           body->GetContentToBufferL(text,startOffset);

    *           MyPlainTextBodyShowMethod(text);

    *           delete body;		

    *       }

    *

    *       //list email attachments

    *       RPointerArray<CFSMailMessagePart> attachments;

    *       attachments.Reset();

    *       messages[i]->AttachmentListL(attachments);

    *       for(TInt i=0;i<attachments.Count();i++)

    *       {

    *           MyShowAttachmentNameMethod(attachments[i]->AttachmentName());

    *       }

    *       attachments.ResetAndDestroy();

    *   }

	*

    *   // clean iterator and tables

    *   messages.ResetAndDestroy();

    *   delete iterator;

    *   sorting.Reset();

    *   delete folder;

    *

	*   // User should call close when terminating mail framework usage

	*   // when shutting down application close mail client singleton

	*   CleanupStack::PopAndDestroy(mail);

	*

	* @section sec3 Observing Email Events.

	*

	*   // To be able to observe events an user has to

	*   // implement MFSMailEventObserver interface.

	*   // Here the COwnMailObserver class implements the interface.

	*   COwnMailObserver* ownObserver = COwnMailObserver::NewL();

	*

	*   // Register to observe mail store events

	*   mail->AddObserverL(*ownObserver);

	*

	*   // Now callbacks are done via the EventL function defined

	*   // in the MFSMailEventObserver and implemented in this case

	*   // by the COwnMailObserver

	*

	*   // When user does not wish to observe events anymore

	*   // he has to unregister

	*   mail->RemoveObserver( *ownObserver );

	*

	*   // Remember that it must be done for each observer

	*   // in the end of the observation because the AddObserverL

	*   // does not replace the observer

	*

	* @section sec_groups Classes

	*

	* The following classes form the public API of the frame work.

	*

	* @section sec_info More Information

	*

	* Copyright © 2006 Nokia.  All rights reserved.

	*

	* This material, including documentation and any related computer programs, 

	* is protected by copyright controlled by Nokia.  All rights are reserved.  

	* Copying, including reproducing, storing, adapting or translating, any or 

	* all of this material requires the prior written consent of Nokia.  This 

	* material also contains confidential information which may not be disclosed 

	* to others without the prior written consent of Nokia.

	*/

NONSHARABLE_CLASS(CFSMailClient) : public CExtendableEmail

{

 public:

    /**

     * Creates a new CFSMailClient singleton instance or increments

     * reference count if singleton already exists

     *

     * @return CFSMailClient pointer

     */

     IMPORT_C static CFSMailClient* NewL();

    /**

     * Creates a new CFSMailClient singleton instance or increments

     * reference count if singleton already exists

     *

     * @return CFSMailClient pointer

     */

     IMPORT_C static CFSMailClient* NewL( TInt aConfiguration );

    /**

     * Creates a new CFSMailClient singleton instance or increments

     * reference count if singleton already exists

     *

     * @return CFSMailClient pointer

     */

     IMPORT_C static CFSMailClient* NewLC( TInt aConfiguration );

    /**

     * CFSMailClient destructor, removes CFSMailClient singleton instance

     * or decrements reference count if singleton is used by other applications

     */

     IMPORT_C void Close();

    /**

     * plugin manager accessor

     */

     IMPORT_C CFSMailPlugin* GetPluginManager();

    /**

     * if plugin id is null id, function goes through all plugins and lists existing

     * mailboxes, otherwise lists existing mailboxes contained by given plugin

     *

     * @param aPluginId plugin id

     * @param aMailBoxes table containing ids of existing mailboxes owned by user

     */

     IMPORT_C TInt ListMailBoxes(const TFSMailMsgId aPluginId, RPointerArray<CFSMailBox>& aMailboxes);

    /**

     * returns email mailbox object related to given mailbox id

     *

     * @param aMailBoxId mailbox id

     * @return mailbox object ( CFSMailBox ), ownership is transferred to user

     */

     IMPORT_C CFSMailBox* GetMailBoxByUidL( const TFSMailMsgId aMailBoxId);

    /**

     * returns email folder object related to given folder id

     *

     * @param aMailBoxId id of mailbox containing folder

     * @param aFolderId folder id

     *

     * @return folder object (CFSMailFolder), ownership is transferred to user

     */

     IMPORT_C CFSMailFolder* GetFolderByUidL( const TFSMailMsgId aMailBoxId, const TFSMailMsgId aFolderId );

    /**

     * returns email object related to given message id

     *

     * @param aMailBoxId id of mailbox containing email

     * @param aFolderId id of folder containing email

     * @param aMessageId message id

     * @param aDetails defines which details are included in email object

     *

     * @return email object (CFSMailMessage), ownership is transferred to user

     */

	 IMPORT_C CFSMailMessage* GetMessageByUidL(const TFSMailMsgId aMailBoxId, const TFSMailMsgId aFolderId,

	 										  const TFSMailMsgId aMessageId, const TFSMailDetails aDetails );	 										  

    /**

     * deletes emails defined in message id list

     *

     * @param aMailBoxId id of mailbox containing emails

     * @param aFolderId id of folder containing email

     * @param aMessageIds defines ids of email to be deleted

     */

     IMPORT_C void DeleteMessagesByUidL( const TFSMailMsgId aMailBoxId, const TFSMailMsgId aFolderId, 

	 									 const RArray<TFSMailMsgId>& aMessageIds );

    /**

     * Deletes mail account. This asynchronous operation returns id that can

     * be later used for cancelling the operation.

     *

     * @param aMailBoxId id of the mailbox to be deleted

     * @param aOperationObserver observer to forward request events to user

     */

     IMPORT_C TInt DeleteMailBoxByUidL( const TFSMailMsgId aMailBoxId,

                                        MFSMailRequestObserver& aOperationObserver );

    /**

     * List emails. Returns iterator, which user can use to scroll email list

     * forwards and backwards.

     *

     * @param aMailBoxId id of mailbox containing emails

     * @param aFolderId id of folder containing emails

     * @param aDetails defines which details are included in each email object

     * (CFSMailMessage) returned by the iterator

     * @param aSorting sort criteria requested by user.

     * First item in array is primary sort criteria.

     *

     * @return email list iterator, ownership is transferred to user

     */

     IMPORT_C MFSMailIterator* ListMessages(

        						const TFSMailMsgId aMailBoxId,

        						const TFSMailMsgId  aFolderId,

        						const TFSMailDetails  aDetails,

        						const RArray<TFSMailSortCriteria>& aSorting);

    /**

     * returns branding manager to handle branding elements

     *

     * @return branding manager (ownership in framework)

     */

     IMPORT_C MFSMailBrandManager& GetBrandManagerL( void );

    /**

     * Adds a new event observer. There can be several observers active at

     * the same time. Caller MUST call RemoveObserver before destroying given

     * observer object.

     *

     * @param aObserver observer implementation

     */

     IMPORT_C void AddObserverL(MFSMailEventObserver& aObserver);

    /**

     * Removes event observer

     *

     * @param aObserver observer to be removed

     */

     IMPORT_C void RemoveObserver(MFSMailEventObserver& aObserver);

    /**

     * unregisters plugin request observer to cancel pending events  

     *

     * @param aRequestId request id of the pending asynchronous request

     */

     IMPORT_C void UnregisterRequestObserver(TInt aRequestId);

    /**

     * Subscribes events from given mailbox

     *

     * @param aMailboxId id of target mailbox

     * @param aObserver observer given by user

     */

     IMPORT_C void SubscribeMailboxEventsL(TFSMailMsgId aMailboxId, MFSMailEventObserver& aObserver);

    /**

     * Unsubscribes events from given mailbox

     * UnsubscribeMailboxEvents MUST be called before destroying given observer object.

     *

     * @param aMailboxId id of target mailbox

     * @param aObserver observer implementation

     */

     IMPORT_C void UnsubscribeMailboxEvents(TFSMailMsgId aMailboxId, MFSMailEventObserver& aObserver);

    /**

     * Sends notification to all protocol plugins that there is

     * Email Wizard data available for some of them.

     *

     * Can return any of the standard Symbian error codes if

     * one of the plugins reports failed mailbox configuration.

     */

     IMPORT_C TInt WizardDataAvailableL();

    /**

     * Client can call this function to immediately initialize authentications that are mandatory

     * to get services from protocol plugins. This means e.g. store authentications. FW will

     * internally ask authentication from all existing plugins before this operations completes.

     *

     * @param aOperationObserver is client provided observer that will receive progress

     * notifications during the operation.

     */

     IMPORT_C TInt AuthenticateL(MFSMailRequestObserver& aOperationObserver);

    /**

     * get framework temp directory

	 */

     IMPORT_C TDesC& GetTempDirL( );

    /**

     * clean framework temp directory

	 */

     IMPORT_C void CleanTempDirL( );

    /**

     * cancels single pending asynchronous request

     *

     * @param aRequestId identifies request

	 */

     IMPORT_C void CancelL( const TInt aRequestId );

    /**

     * cancels all pending asynchronous requests

	 */

     IMPORT_C void CancelAllL( );

     /**

      * Calls plugin to change the name of the mailbox

      *

      * @param aMailboxId mailbox id

      * @param aMailboxName new name for the mailbox

      */

     IMPORT_C void SetMailboxName( const TFSMailMsgId aMailboxId, const TDesC& aMailboxName );

public: // from  CExtendableEmail

    /**

	 * @see CExtendableEmail::ReleaseExtension

	 */

    IMPORT_C virtual void ReleaseExtension( CEmailExtension* aExtension );

    /**

    * Requests extension. Default implementation performs lookup only and

    * derived class should implement actual instantiation because it knows

    * extensions it supports

    * array but does not delete it.

    * @param aExtension extension to release

    */

    IMPORT_C virtual CEmailExtension* ExtensionL( const TUid& aInterfaceUid );

 protected:

 private:

    /**

     * C++ default constructor.

     */

     CFSMailClient();

    /**

     * Destructor.

     */

     ~CFSMailClient();

    /**

     * ConstructL

     */

	 void ConstructL( TInt aConfiguration );

    /**

     * returns framework singleton instance if exists

     */

	 static CFSMailClient* Instance();

    /**

     * increments reference count to framework singleton

     */

     TInt IncReferenceCount();

    /**

     * decrements reference count to framework singleton

     */

     TInt DecReferenceCount();

 private: // data

	/** framework singleton reference count */

    TInt                     iReferenceCount;

	/** */

    CFSFWImplementation*     iFWImplementation;

	/** branding manager pointer  */

    MFSMailBrandManager*     iBrandManager;

};

#endif // __FSMAILCLIENT_H