--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/emailservices/emailserver/inc/fsnotificationhandlerbase.h Wed Sep 01 12:28:57 2010 +0100
@@ -0,0 +1,337 @@
+/*
+* 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;
+class TFSMailMsgId;
+
+
+class TNewMailInfo
+ {
+public:
+ inline TNewMailInfo( TFSMailMsgId aMsgId,
+ TFSMailMsgId aMailBoxId,
+ TFSMailMsgId aParentFolderId)
+ : iMsgId( aMsgId ), iMailBox( aMailBoxId ), iParentFolderId( aParentFolderId)
+ { }
+
+ TFSMailMsgId iMsgId;
+ TFSMailMsgId iMailBox;
+ TFSMailMsgId iParentFolderId;
+ };
+
+class MFSTimerObserver
+ {
+ public:
+
+ /**
+ * TODO document me
+ */
+ virtual void TimerExpiredL() = 0;
+
+ };
+
+class CNewMailNotificationTimer : public CTimer
+ {
+public:
+
+ static CNewMailNotificationTimer* NewL(
+ MFSTimerObserver& aObserver );
+ static CNewMailNotificationTimer* NewLC(
+ MFSTimerObserver& aObserver );
+
+ /**
+ * Destructor.
+ */
+ virtual ~CNewMailNotificationTimer();
+
+
+protected:
+
+ /**
+ * Constructor.
+ *
+ * @since S60 ?S60_version
+ * @param aObserver Observer of this timer.
+ */
+ CNewMailNotificationTimer(
+ MFSTimerObserver& aObserver );
+ void ConstructL();
+
+// from base class CActive
+ virtual void DoCancel();
+ virtual void RunL();
+
+private:
+
+
+
+private: // data
+
+ /**
+ * Observer and user of this timer.
+ */
+ MFSTimerObserver& iObserver;
+
+ };
+
+/**
+ * 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 MFSTimerObserver
+ {
+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,
+ TFSMailMsgId aParentFolderId,
+ 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;
+
+// from TODO
+ virtual void TimerExpiredL();
+
+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;
+
+ RArray<TNewMailInfo> iNewInboxEntries;
+
+ CNewMailNotificationTimer* iTimer;
+ };
+
+#include "fsnotificationhandlerbase.inl"
+
+#endif //__FSNOTIFICATIONHANDLERBASE_H__