/*

* Copyright (c)  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:  Header for notification handling base class

*

*/

#ifndef __FSNOTIFICATIONHANDLERBASE_H__

#define __FSNOTIFICATIONHANDLERBASE_H__

#include <e32base.h>

//<cmail>

#include "MFSMailEventObserver.h"

//</cmail>

class CFSMailClient;

class CFSMailFolder;

class CFSMailMessage;

class MFSNotificationHandlerMgr;

class CFSNotificationHandlerHSConnection;

/**

 *  A base class for notification handlers that need timer services.

 *

 *  @code

 *   ?good_class_usage_example(s)

 *  @endcode

 *

 *  @lib ?library

 *  @since S60 ?S60_version *** for example, S60 v3.0

 */

class CFSNotificationHandlerBase : public CBase, public MFSMailEventObserver

    {

public:

    /**

     * Two-phased constructor.

     * @param aOwner Owner and manager of this handler.

     */ 

    static CFSNotificationHandlerBase* NewL( TInt aHandlerUid, MFSNotificationHandlerMgr& aOwner );

public:

    /**

    * Function that returns a reference to the mail client which

    * is used to access email framework.

    *

    * @since S60 ?S60_version

    * @return Reference to framework object.

    */

    CFSMailClient& MailClient() const;

// from base class MFSMailEventObserver

    /**

    * Function that is used to inform the handler of a new event.

    * Default implementation checks whether the startup is complete

    * and therefore the object of this class is observing

    * events.

    * Also checks whether for example the mailbox has capabilities

    * so that the event handling is in this handler is possible. This

    * is checked by calling CapabilitiesToContinueL function which

    * should return ETrue whether the capabilities indicate that

    * the notification handling should be continued.

    * If notification handling is continued then call for HandleEventL

    * is made.

    *

    * This function is not necessarily called by the framework and

    * thus an instance of this class does not necessarily act as a

    * direct observer for the framework but for example for a

    * manager class.

    *

    * @see MFSMailEventObserver::EventL

    */

    virtual void EventL( TFSMailEvent aEvent, TFSMailMsgId aMailbox,

                                  TAny* aParam1, TAny* aParam2, TAny* aParam3 );

    /**

    * Destructor.

    */

    virtual ~CFSNotificationHandlerBase();

protected:  

    /**

    * Constructor.

    *

    * @since S60 ?S60_version

    * @param aOwner Owner and manager of this handler.

    */ 

    CFSNotificationHandlerBase( MFSNotificationHandlerMgr& aOwner );

    void ConstructL();

    /**

    * Getter for information whether the handler is observing events

    *

    * @since S60 ?S60_version

    * @return Whether handler is observing or not

    */         

    TBool Observing() const;

    /**

    * Function that goes through messages identified by the

    * message ids given in the parameter array and checks

    * if any of them is such that it causes a notification.

    * In this default implementation it is checked if any of the

    * messages is unread and that it is the newest of unread messages

    * in the folder.

    *

    * @since S60 ?S60_version

    * @param aMailboxId Mailbox which contains the messages

    *                   checked here.

    * @param aParentFolderId Folder that contains the messages

    *                        checked here.

    * @param aMsgIdList List of message identifiers identifying

    *                   the messages that should be checked

    *                   for newest unread message.

    * @return Boolean value to indicate whether newest unread

    *         messages was found among the identified messages.

    */

    virtual TBool MessagesCauseNotificationL( TFSMailMsgId aMailboxId,

                                              CFSMailFolder& aParentFolder,

                                              const RArray<TFSMailMsgId>& aMsgIdList );

    /**

    * Function that checks whether the given message is unread

    * or not.

    *

    * @since S60 ?S60_version

    * @param aMessage Message which is checked.

    * @return Boolean indicating whether the message was unread

    *         or not. ETrue means unread.

    */ 

    TBool MsgIsUnread( /*const*/ CFSMailMessage& aMessage ) const;

protected:

    /**

    * Function that returns a reference to the Home Screen connection

    * which is used to access Home Screen status.

    *

    * @since S60 ?S60_version

    * @return Pointer to Home Screen connection. Ownership is not

    *         transferred. NULL is returned if the connection

    *         cannot be provided.

    */    

    CFSNotificationHandlerHSConnection* HSConnection() const;

    /**

    * Setter for information whether the handler is observing events.

    *

    * @since S60 ?S60_version

    * @param aNewValue New value for observing info

    */     

    void SetObserving( TBool aNewValue );

    /**

     * Function that is used to check desired capabilities.

     * Default implementation of this function checks that the mailbox

     * does not have EFSMBoxCapaNewEmailNotifications capability. If it

     * has then EFalse is returned. 

     *

     * @see EventL for parameters.

     *

     * @since S60 ?S60_version

     */   

    virtual TBool CapabilitiesToContinueL(

        TFSMailEvent aEvent,

        TFSMailMsgId aMailbox,

        TAny* aParam1,

        TAny* aParam2,

        TAny* aParam3 ) const;

    /**

     * Function that does the actual event handling. This class provides

     * a default implementation for the function. Sets notification on

     * if the messages cause MessagesCauseNotification() to return

     * ETrue.

     *

     * @see EventL for parameters.

     *

     * @since S60 ?S60_version

     */     

    virtual void HandleEventL(

        TFSMailEvent aEvent,

        TFSMailMsgId aMailbox,

        TAny* aParam1,

        TAny* aParam2,

        TAny* aParam3 );

    /**

     * Function that gets the newest message from the given

     * folder.

     *

     * @since S60 ?S60_version

     * @param aFolder Folder where from the newest message

     *                is searched.

     * @return Pointer to newest message in the folder. If

     *         no messages are found, leaves with KErrNotFound.

     */      

    CFSMailMessage* NewestMsgInFolderL(

        /*const*/ CFSMailFolder& aFolder ) const;

private:

    /**

     * Function that sets the notification of the derived class on.

     *

     * @since S60 ?S60_version

     */  

    virtual void TurnNotificationOn() = 0;

    /**

     * Function that sets the notification of the derived class off.

     *

     * @since S60 ?S60_version

     */  

    virtual void TurnNotificationOff() = 0;

protected: // data

    /**

     * Owner and manager of the instance of this handler class.

     */    

    MFSNotificationHandlerMgr& iOwner;

private: // data

    /**

     * Boolean to inform whether we are currently observing

     * the mail framework

     * Used for example in the startup to prevent callbacks before

     * the object is fully initialized.

     */    

    TBool iObserving;

    // Destructor key for the ECOM plugin

    TUid                               iDestructorKey;

    };

#include "fsnotificationhandlerbase.inl"

#endif  //__FSNOTIFICATIONHANDLERBASE_H__