/*

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

     * @param aSilentConnection defines if connection is needed to be

     *        silent connection or non-silent one (default).

     */

     virtual void RefreshNowL( const TFSMailMsgId& aMailBoxId,

                               MFSMailRequestObserver& aOperationObserver,

                               TInt aRequestId,

                               const TBool aSilentConnection=EFalse ) = 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;

    /**

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

    /**

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

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

     *                      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 evaluated and returned by plugin

     *

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

     */

     virtual CFSMailMessage* GetMessageByUidL(  const TFSMailMsgId& aMailBoxId,

                                                const TFSMailMsgId& aParentFolderId,

                                                const TFSMailMsgId& aMessageId,

                                                const TFSMailDetails aDetails) = 0;

    /**

     * deletes email defined by message id

     *

     * @param aMailBoxId id of the mailbox containing email

     * @param aFolderId email parent folder id

     * @param aMessages ids of messages to be deleted

     */

     virtual void DeleteMessagesByUidL( const TFSMailMsgId& aMailBoxId,

                                        const TFSMailMsgId& aFolderId,

                                        const RArray<TFSMailMsgId>& aMessages ) = 0;

// <qmail>

     /**

      * deletes email defined by message id

      *

      * @param aMailBoxId id of the mailbox containing email

      * @param aFolderId email parent folder id

      * @param aMessages ids of messages to be deleted

      * @param aOperationObserver Observer for the operation

      * @param aRequestId id of the operation

      * @return KErrNone if this method is supported, KErrNotSupported if not

      */

      virtual void DeleteMessagesByUidL( const TFSMailMsgId& aMailBoxId,

                                         const TFSMailMsgId& aFolderId,

                                         const RArray<TFSMailMsgId>& aMessages,

                                         MFSMailRequestObserver& aOperationObserver,

                                         const TInt aRequestId );

// </qmail>

    /**

     * creates new email template into drafts folder

     *

     * @param aMailBoxId id of the mailbox where new email is created

     * @return email object to be modified by user, ownership is transferred to user

     */

     virtual CFSMailMessage* CreateMessageToSendL( const TFSMailMsgId& aMailBoxId ) = 0;

// <qmail>

    /**

     * Asynchronous creation of new email template into drafts folder. When the operation

     * finishes, RequestResponseL is called on the observer and the created message is

     * passed along with the TFSProgress data. It is not necessary for a plugin to

     * implement this method if using the synchronous version does not cause performance

     * problems for the UI or general problems for the application. UI uses these methods

     * via an operation class NmMessageCreationOperation (see NmailUiEngine). If a plugin

     * doesn't implement this method the operation class automatically selects the

     * synchronous version.

     *

     * @param aMailBoxId id of the mailbox where new email is created

     * @param aOperationObserver Observer for the operation

     * @param aRequestId id of the operation

     * @return KErrNone if this method is supported, KErrNotSupported if not

     */

     virtual void CreateMessageToSendL( const TFSMailMsgId& aMailBoxId,

                                        MFSMailRequestObserver& aOperationObserver,

                                        const TInt aRequestId ) = 0;

// </qmail>

    /**

     * creates new email template to drafts folder to be forwarded

     *

     * @param aMailBoxId id of the mailbox where new email is created

     * @param aOriginalMessageId if of the (original) message,which is forwarded

     * @return email object to be modified by user, ownership is transferred to user

     */

     virtual CFSMailMessage* CreateForwardMessageL( const TFSMailMsgId& aMailBoxId,

                                                    const TFSMailMsgId& aOriginalMessageId,

                                                    const TDesC& aHeaderDescriptor = KNullDesC ) = 0;

// <qmail>

     /**

      * Asynchronous creation of new forwarded email into drafts folder. When the operation

      * finishes, RequestResponseL is called on the observer and the created message is

      * passed along with the TFSProgress data.

      *

      * @param aMailBoxId id of the mailbox where new email is created

      * @param aOriginalMessageId if of the (original) message,which is forwarded

      * @param aOperationObserver Observer for the operation

      * @param aRequestId id of the operation

      * @param aHeaderDescriptor user can give quote headers data to plugin as

      *  parameter if needed

      * @return email object to be modified by user, ownership is transferred to user

      */