/*

* 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:  email framework plugin interface

*

*/

#ifndef CFSFWMAILPLUGIN_H

#define CFSFWMAILPLUGIN_H

#include <ecom.h>

//<cmail>

#include "MFSMailRequestObserver.h"

#include "MFSMailEventObserver.h"

#include "CFSMailBox.h"

#include "CFSMailPlugin.hrh"

#include "cemailextensionbase.h"

//</cmail>

// constants

const TUid KFSMailPluginInterface = { FSMAILPLUGININTERFACE };

_LIT8( KFSPluginInterfaceImplementationType, "Plug-In Interface / Freestyle Email Framework");

class MFSMailIterator;

/**

 *  Freestyle Email Framework Plugin Interface

 *

 *  class MFSMailPlugin defines functions used by email framework

 *  and implemented by plugin implementor.

 *

 *  Plugin implementor inherits from class CFSMailPlugin,

 *  but plugin load medhods are provided by framework in file CFSMailPlugin.inl

 *  CFSMailPlugin,CFSMailPlugin.inl are exported by framework

 *

 *  @lib FSFWCommonLib

 *

 */

NONSHARABLE_CLASS ( CFSMailPlugin ) : public CExtendableEmail

    {

public: // Methods

    /**

     * destructor

     */

     inline virtual ~CFSMailPlugin();

    /**

     * two-phased constructor

     */

     static CFSMailPlugin* NewL(TUid aUid);

    /**

     * close ecom session

     */

     static void Close( );

    /**

     * list plugin implementations

     *

     * @param aInfo plugin implementation info

     */

     static void ListImplementationsL( RPointerArray<CImplementationInformation>& aInfo );

    /** MAILBOX HANDLING API */

    /**

     * Enables synchronization of identified mailbox. This means

     * that the plugin 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 plugin

     * implementation.

     *

     * All collections (mail etc.) supported by the plugin and

     * enabled by user settings are synchronized.

     *

     * This function sets identified mailbox online but it may

     * have a side effect that also other mailboxes of the same

     * plugin are set online.

     *

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

     *

     * @param aMailBoxId mailbox id request is accessed to

     */

     virtual void GoOnlineL( const TFSMailMsgId& aMailBoxId ) = 0;

    /**

     * Disables mailbox synchronization. Connection by the plugin

     * to synchronize identified mailbox is not allowed after this.

     *

     * If GoOnlineL has effect on other mailboxes of the

     * same plugin then this function has effect on those

     * mailboxes also.

     *

     * @param aMailBoxId mailbox id request is accessed to

     */

     virtual void GoOfflineL( const TFSMailMsgId& aMailBoxId ) = 0;

    /**

     * Forces synchronization of mailbox. This can be called

     * whether the mailbox is currently offline or online. In

     * 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 plugin and

     * enabled by user settings are synchronized.

     *

     * This is an asynchronous operation and the request id

     * is returned for cancelling purpose.

     *

     * Observer is given as a parameter to enable callbacks

     * related to this operation. Alternatively user can use

     * empty implementation of the observer function and rely

     * only on events. Notice that the event system is not as

     * comprehensive as the observing way do this.

     *

     * @param aMailBoxId defines mailbox

     * @param aOperationObserver is client provided observer that

     *        will receive progress notifications during the operation.

     * @param aRequestId identifies asynchronous request if parallel

     * requests exist

     */

     virtual void RefreshNowL( const TFSMailMsgId& aMailBoxId,

                               MFSMailRequestObserver& aOperationObserver,

    /**

     * Returns last synchronization operation status.

     *

     * @param aMailBoxId mailbox id

     *

     * @return last sync operation status

     *

     */

     virtual const TFSProgress GetLastSyncStatusL( const TFSMailMsgId& aMailBoxId ) = 0;

    /**

     * cancels all ongoing synchronizations in given mailbox regardless if initiated

     * by email framework or plugin itself

     *

     * @return error code

     */

     virtual TInt CancelSyncL( const TFSMailMsgId& aMailBoxId ) = 0;

    /**

     * Returns the current synchronization state of mailbox.

     *

     * @param aMailboxId id of the target mailbox

     *

     * @return mailbox synchronizing state data structure

     */

     virtual TSSMailSyncState CurrentSyncState( const TFSMailMsgId& aMailboxId ) = 0;

    /**

     * returns mailbox online status

     *

     * @param aMailboxId id of target mailbox

     *

     * @return online / offline

     */

     virtual TFSMailBoxStatus GetMailBoxStatus( const TFSMailMsgId& aMailBoxId ) = 0;

    /**

     * checks if mailbox supports given capability

     *

     * @param aCapability capability to be checked

     * @param aMailBoxId id of the target mailbox

     *

     * @return true/false

     */

     virtual TBool MailboxHasCapabilityL(   TFSMailBoxCapabilities aCapability,

                                            TFSMailMsgId aMailBoxId ) = 0;

    /**

     * lists existing mailboxes contained by plugin

     *

     * @param aMailBoxes plugin writes list of existing mailboxes into this

     *        table owned by user

     * to this table owned by framework

     */

     virtual void ListMailBoxesL( RArray<TFSMailMsgId>& aMailboxes) = 0;

    /**

     * returns email mailbox object related to given mailbox id

     * mailbox data set by plugin :

     *               - mailbox id

     *               - mailbox name

     *               - branding id

     *               - mailbox capabilities

     *

     * @param aMailBoxId mailbox id

     *

     * @return mailBox object ( CFSMailBox ) to be owned by user

     */

     virtual CFSMailBox* GetMailBoxByUidL( const TFSMailMsgId& aMailBoxId) = 0;

    /**

     * removes mailbox

     *

     * @param aMailBoxId id of the mailbox to be removed

     * @param aOperationObserver is FW provided observer that should be

     * used to report progress notifications during the operation.

     * @param aRequestId asynchronous request id

     */

     virtual void DeleteMailBoxByUidL(  const TFSMailMsgId& aMailBoxId,

                                        MFSMailRequestObserver& aOperationObserver,

                                        const TInt aRequestId ) = 0;

    /**

     * Returns branding id of this mailbox.

     * This function is used by Branding Manager to associate mailbox to a branding

     * definition. Plugin should return incoming mail server associated with this mailbox.

     *

     * @param aMailBoxId defines the target mailbox

     * @return branding id

     */

     virtual TDesC& GetBrandingIdL(const TFSMailMsgId& aMailboxId) = 0;

    /**

     * Subscribes events coming from given mailbox. UnsubscribeMailboxEvents

     * MUST be called before destroying given observer object.

     *

     * @param aMailboxId id of target mailbox

     * @param aObserver event observer implementation

     */

     virtual void SubscribeMailboxEventsL(const TFSMailMsgId& aMailboxId,

                                          MFSMailEventObserver& aObserver) = 0;

    /**

     * Unsubscribes events from given mailbox

     *

     * @param aMailboxId id of target mailbox

     * @param aObserver event observer

     */

     virtual void UnsubscribeMailboxEvents(const TFSMailMsgId& aMailboxId,

                                           MFSMailEventObserver& aObserver) = 0;

    /**

     * Gives notification that new account data may be available from Email Wizard.

     * Plugin must check if there is Wizard Data available for it and create

     * new account if necessary. If plugin does not support Email Wizard this

     * function can just return immediately.

     *

     * Should return KErrNone if no data found or configuration was successful.

     * otherwise any of the standard Symbian error codes.

     */

     virtual TInt WizardDataAvailableL() = 0;

    /**

     * reads connection id from plugin

     *

     * @param  aConnectionId reference to connection id

     * @return KErrNone or error code

     */

     virtual TInt GetConnectionId( TFSMailMsgId aMailBoxId, TUint32& aConnectionId );

    /**

     * checks from plugin if connection is allowed when roaming

     *

     * @param  aConnectionAllowed

     * @return KErrNone or error code

     */

     virtual TInt IsConnectionAllowedWhenRoaming( TFSMailMsgId aMailBoxId, TBool& aConnectionAllowed );

    /**

      * Reads email from file stream and converts it to class CFSMailMessage

      *

      * @param  aMailBoxId mailbox where email exists

      * @param  aFile input file given by user

      * @return CFSMailMessage

      */

     virtual CFSMailMessage* CreateMessageFromFileL( const TFSMailMsgId /*aMailboxId*/,

                                                     const RFile& /*aFile*/ )

                                                     { return NULL; };

    /**

     * Moves a messages between the given folders.

     *

     * @param aMailBoxId id of the target mailbox

     * @param aMessageIds ids of the messages to be transferred owned by user

     * @param aSourceFolderId source folder id

     * @param aDestinationFolderId destination folder id

     *

     */

     virtual void MoveMessagesL( const TFSMailMsgId& aMailBoxId,

                                 const RArray<TFSMailMsgId>& aMessageIds,

                                 const TFSMailMsgId& aSourceFolderId,

                                 const TFSMailMsgId& aDestinationFolderId ) = 0;

    /**

     * Moves a messages between the given folders. Async version.

     * @param aMailBoxId id of the target mailbox

     * @param aMessageIds ids of the messages to be transferred owned by user

     * @param aSourceFolderId source folder id

     * @param aDestinationFolderId destination folder id

     */

     virtual TInt MoveMessagesL( const TFSMailMsgId& /*aMailBoxId*/,

                                 const RArray<TFSMailMsgId>& /*aMessageIds*/,

                                 const TFSMailMsgId& /*aSourceFolderId*/,

                                 const TFSMailMsgId& /*aDestinationFolderId*/,

                                 MFSMailRequestObserver& /*aOperationObserver*/,

                                 TInt /*aRequestId*/ ){return KErrNotSupported;}

    /**

     * Copies a messages from folder to another.

     * This function copies a messages to the given 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 aMailBoxId target mailbox id

     * @param aMessageIds ids of the messages to be copied

     * @param aNewMessages ids of the copied new messages owned by user

     * @param aSourceFolderId source folder id

     * @param aDestinationFolderId destination folder id

     */

     virtual void CopyMessagesL( const TFSMailMsgId& aMailBoxId,

                                 const RArray<TFSMailMsgId>& aMessageIds,

                                 RArray<TFSMailMsgId>& aNewMessages,

                                 const TFSMailMsgId& aSourceFolderId,

                                 const TFSMailMsgId& aDestinationFolderId ) = 0;

    /** Get a list of most recently used addresses of desired 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.

     *

     *  The function will leave with KErrNotFound if a mailbox with

     *  given id is not found.

     *

     * @param aMailBoxId target mailbox id

     *

     * @return Array of descriptors containing MRUs. Ownership

     * is transferred. Empty if no entries are found.

     */

     virtual MDesCArray* GetMrusL( const TFSMailMsgId& aMailBoxId ) = 0;

    /** Set a list of most recently used addresses for given 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.

     *

     *  The function will leave with KErrNotFound if a mailbox with

     *  given id is not found.

     *

     * @param aMailBoxId target mailbox id

     * @param aNewMruList Array of descriptors containing MRUs.

     * Empty if no entries are found.

     */

     virtual void SetMrusL( const TFSMailMsgId& aMailBoxId,

                            MDesCArray* aNewMruList ) = 0;

    /** FOLDER HANDLING API */

    /**

     * returns email folder object related to given folder id

     * folder data set by plugin :

     *               - folder id

     *               - folder name

     *               - folder type ; Inbox, Outbox, Sent, Drafts, Deleted, Other

     *               - message count

     *               - unread message count

     *               - mailbox id

     *               - parent folder

     *

     * @param aMailBoxId id of mailbox containing folder

     * @param aFolderId folder id

     *

     * @return folder object (CFSMailFolder) to be owned by user

     */

     virtual CFSMailFolder* GetFolderByUidL( const TFSMailMsgId& aMailBoxId,

                                             const TFSMailMsgId& aFolderId ) = 0;

    /**

     * create new folder

     *

     * @param aMailBoxId id of the mailbox where folder is created

     * @param aFolderId id of the parent folder where folder is created

     * @param aFolderName name of the new folder

     * @param aSync defines if new folder is local only (false)

     * or if it also should sync to server (true)

     *

     * @return new folder object CFSMailFolder to be owned by user

     */

     virtual CFSMailFolder* CreateFolderL(  const TFSMailMsgId& aMailBoxId,

                                            const TFSMailMsgId& aParentFolderId,

                                            const TDesC& aFolderName,

                                            const TBool aSync ) = 0;

    /**

     * deletes folder related to given folder id

     *

     * @param aMailBoxId mailbox where deleted folder is located

     * @param aFolderId defines id of the folder to be deleted

     */

     virtual void DeleteFolderByUidL( const TFSMailMsgId& aMailBoxId,

                                      const TFSMailMsgId& aFolderId) = 0;

    /**

     * Lists 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 aMailBoxId id of the mailbox where parent folder is located

     * @param aFolderId parent folder id. TFSMailId::NullId() for root level list.

     * @param aFolderList plugin writes results in this array owned by user

     */

     virtual void ListFoldersL( const TFSMailMsgId& aMailBoxId,

                                const TFSMailMsgId& aParentFolderId,

                                RPointerArray<CFSMailFolder>& aFolderList) = 0;

   /**

     * List all subfolders of given mailbox.

     * 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 aMailBoxId mailbox id

     * @param aFolderList plugin writes results in this array owned by user.

     * Caller must determine tree structure by examining parent id of each

     * returned folder.

     */

     virtual void ListFoldersL( const TFSMailMsgId& aMailBoxId,

                                RPointerArray<CFSMailFolder>& aFolderList) = 0;

    /**

     * returns folder id of given standard folder

     *

     * @param aMailBoxId id of the mailbox where folder is located

     * @param aFolderType folder type

     *

     * return folder id

     */

     virtual TFSMailMsgId GetStandardFolderIdL( const TFSMailMsgId& aMailBoxId,

                                                const TFSFolderType aFolderType ) = 0;

    /** MESSAGE FETCH AND STORE */

    /**

     * List messages contained by given folder.

     * Returns email list iterator to user.

     *

     * @param aMailBoxId id of the mailbox where parent folder is located

     * @param aFolderId folder id of given folder

     * @param aDetails defines which message details are included in messages

     * EFSMsgDataIdOnly  -> Doesn't get any data. The object just contains the ID.

     * EFSMsgDataDate    -> Get received date only. To be used when showing messages sorted by date.

     *                      The rest would be retreived when needed but date is needed to build the list.

     * EFSMsgDataSubject -> Like above but when sorting by subject

     * EFSMsgDataSender  -> Likewise for sender address.

     * EFSMsgDataEnvelope, EFSMsgDataStructure -> email content type is returned by plugin

     * @param aSorting describes requested sort criteria (owned by user).

     *        First item in array is primary sort criteria.

     *

     * @return Email list iterator, ownership is transferred to user.

     */

     virtual MFSMailIterator* ListMessagesL( const TFSMailMsgId& aMailBoxId,

                                             const TFSMailMsgId& aFolderId,

                                             const TFSMailDetails aDetails,

                                             const RArray<TFSMailSortCriteria>& aSorting ) = 0;

    /**

     * returns email object related to given message id

     *

     * message info set by plugin :

     *                - message id

     *                - mailbox

     *                - parent folder

     *                - message size

     *                - the rest is defined by message attributes ;

     * @param aMailBoxId id of the mailbox containing email

     * @param aFolderId parent folder id containing email

     * @param aMessageId email message id

     *

     * @param aDetails defines which message parts are included in message

     * EFSMsgDataIdOnly  -> Doesn't get any data. The object just contains the ID.

     * EFSMsgDataDate    -> Get received date only. To be used when showing messages sorted by date.