1 /*

     2 * Copyright (c)  Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Header for notification handling base class

    15 *

    16 */

    17 

    18 

    19 #ifndef __FSNOTIFICATIONHANDLERBASE_H__

    20 #define __FSNOTIFICATIONHANDLERBASE_H__

    21 

    22 #include <e32base.h>

    23 //<cmail>

    24 #include "mfsmaileventobserver.h"

    25 //</cmail>

    26 

    27 class CFSMailClient;

    28 class CFSMailFolder;

    29 class CFSMailMessage;

    30 class MFSNotificationHandlerMgr;

    31 class CFSNotificationHandlerHSConnection;

    32 class TFSMailMsgId;

    33 

    34 

    35 class TNewMailInfo

    36     {

    37 public:

    38     inline TNewMailInfo( TFSMailMsgId aMsgId, 

    39                          TFSMailMsgId aMailBoxId,

    40                          TFSMailMsgId aParentFolderId) 

    41     : iMsgId( aMsgId ), iMailBox( aMailBoxId ), iParentFolderId( aParentFolderId)

    42     { }

    43     

    44     TFSMailMsgId iMsgId;

    45     TFSMailMsgId iMailBox;

    46     TFSMailMsgId iParentFolderId;

    47     };

    48 

    49 class MFSTimerObserver

    50     {

    51     public:

    52 

    53     /**

    54      * TODO document me

    55      */

    56      virtual void TimerExpiredL() = 0;

    57 

    58      };

    59 

    60 class CNewMailNotificationTimer : public CTimer

    61     {

    62 public:

    63 

    64     static CNewMailNotificationTimer* NewL(

    65             MFSTimerObserver& aObserver );

    66     static CNewMailNotificationTimer* NewLC(

    67             MFSTimerObserver& aObserver );

    68 

    69     /**

    70      * Destructor.

    71      */

    72     virtual ~CNewMailNotificationTimer();

    73 

    74 

    75 protected:

    76   

    77     /**

    78      * Constructor.

    79      *

    80      * @since S60 ?S60_version

    81      * @param aObserver Observer of this timer.

    82      */ 

    83     CNewMailNotificationTimer(

    84             MFSTimerObserver& aObserver );

    85     void ConstructL();

    86 

    87 // from base class CActive

    88     virtual void DoCancel();

    89     virtual void RunL();

    90 

    91 private:

    92 

    93 

    94             

    95 private: // data

    96 

    97     /**

    98      * Observer and user of this timer.

    99      */    

   100     MFSTimerObserver& iObserver;

   101 

   102     };

   103 

   104 /**

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

   106  *

   107  *  @code

   108  *   ?good_class_usage_example(s)

   109  *  @endcode

   110  *

   111  *  @lib ?library

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

   113  */

   114 class CFSNotificationHandlerBase : public CBase, public MFSMailEventObserver, public MFSTimerObserver

   115     {

   116 public:

   117     

   118     /**

   119      * Two-phased constructor.

   120      * @param aOwner Owner and manager of this handler.

   121      */ 

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

   123     

   124 public:

   125     

   126     /**

   127     * Function that returns a reference to the mail client which

   128     * is used to access email framework.

   129     *

   130     * @since S60 ?S60_version

   131     * @return Reference to framework object.

   132     */

   133     CFSMailClient& MailClient() const;

   134 

   135 // from base class MFSMailEventObserver

   136 

   137     /**

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

   139     * Default implementation checks whether the startup is complete

   140     * and therefore the object of this class is observing

   141     * events.

   142     * Also checks whether for example the mailbox has capabilities

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

   144     * is checked by calling CapabilitiesToContinueL function which

   145     * should return ETrue whether the capabilities indicate that

   146     * the notification handling should be continued.

   147     * If notification handling is continued then call for HandleEventL

   148     * is made.

   149     *

   150     * This function is not necessarily called by the framework and

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

   152     * direct observer for the framework but for example for a

   153     * manager class.

   154     *

   155     * @see MFSMailEventObserver::EventL

   156     */

   157     virtual void EventL( TFSMailEvent aEvent, TFSMailMsgId aMailbox,

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

   159 

   160     /**

   161     * Destructor.

   162     */

   163     virtual ~CFSNotificationHandlerBase();

   164 

   165 

   166 protected:  

   167   

   168     /**

   169     * Constructor.

   170     *

   171     * @since S60 ?S60_version

   172     * @param aOwner Owner and manager of this handler.

   173     */ 

   174     CFSNotificationHandlerBase( MFSNotificationHandlerMgr& aOwner );

   175     

   176     void ConstructL();

   177     

   178     /**

   179     * Getter for information whether the handler is observing events

   180     *

   181     * @since S60 ?S60_version

   182     * @return Whether handler is observing or not

   183     */         

   184     TBool Observing() const;

   185     

   186     /**

   187     * Function that goes through messages identified by the

   188     * message ids given in the parameter array and checks

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

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

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

   192     * in the folder.

   193     *

   194     * @since S60 ?S60_version

   195     * @param aMailboxId Mailbox which contains the messages

   196     *                   checked here.

   197     * @param aParentFolderId Folder that contains the messages

   198     *                        checked here.

   199     * @param aMsgIdList List of message identifiers identifying

   200     *                   the messages that should be checked

   201     *                   for newest unread message.

   202     * @return Boolean value to indicate whether newest unread

   203     *         messages was found among the identified messages.

   204     */

   205     virtual TBool MessagesCauseNotificationL( TFSMailMsgId aMailboxId,

   206                                               TFSMailMsgId aParentFolderId,

   207                                               const RArray<TFSMailMsgId>& aMsgIdList );

   208     

   209 

   210     /**

   211     * Function that checks whether the given message is unread

   212     * or not.

   213     *

   214     * @since S60 ?S60_version

   215     * @param aMessage Message which is checked.

   216     * @return Boolean indicating whether the message was unread

   217     *         or not. ETrue means unread.

   218     */ 

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

   220 

   221 protected:

   222     

   223     /**

   224     * Function that returns a reference to the Home Screen connection

   225     * which is used to access Home Screen status.

   226     *

   227     * @since S60 ?S60_version

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

   229     *         transferred. NULL is returned if the connection

   230     *         cannot be provided.

   231     */    

   232     CFSNotificationHandlerHSConnection* HSConnection() const;

   233      

   234     /**

   235     * Setter for information whether the handler is observing events.

   236     *

   237     * @since S60 ?S60_version

   238     * @param aNewValue New value for observing info

   239     */     

   240     void SetObserving( TBool aNewValue );

   241      

   242     /**

   243      * Function that is used to check desired capabilities.

   244      * Default implementation of this function checks that the mailbox

   245      * does not have EFSMBoxCapaNewEmailNotifications capability. If it

   246      * has then EFalse is returned. 

   247      *

   248      * @see EventL for parameters.

   249      *

   250      * @since S60 ?S60_version

   251      */   

   252     virtual TBool CapabilitiesToContinueL(

   253         TFSMailEvent aEvent,

   254         TFSMailMsgId aMailbox,

   255         TAny* aParam1,

   256         TAny* aParam2,

   257         TAny* aParam3 ) const;

   258 

   259     /**

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

   261      * a default implementation for the function. Sets notification on

   262      * if the messages cause MessagesCauseNotification() to return

   263      * ETrue.

   264      *

   265      * @see EventL for parameters.

   266      *

   267      * @since S60 ?S60_version

   268      */     

   269     virtual void HandleEventL(

   270         TFSMailEvent aEvent,

   271         TFSMailMsgId aMailbox,

   272         TAny* aParam1,

   273         TAny* aParam2,

   274         TAny* aParam3 );

   275 

   276 

   277     /**

   278      * Function that gets the newest message from the given

   279      * folder.

   280      *

   281      * @since S60 ?S60_version

   282      * @param aFolder Folder where from the newest message

   283      *                is searched.

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

   285      *         no messages are found, leaves with KErrNotFound.

   286      */      

   287     CFSMailMessage* NewestMsgInFolderL(

   288         /*const*/ CFSMailFolder& aFolder ) const;

   289 

   290     

   291 private:

   292 

   293     /**

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

   295      *

   296      * @since S60 ?S60_version

   297      */  

   298     virtual void TurnNotificationOn() = 0;

   299 

   300     /**

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

   302      *

   303      * @since S60 ?S60_version

   304      */  

   305     virtual void TurnNotificationOff() = 0;

   306     

   307 // from TODO

   308     virtual void TimerExpiredL();

   309     

   310 protected: // data

   311 

   312     /**

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

   314      */    

   315     MFSNotificationHandlerMgr& iOwner;

   316 

   317 private: // data

   318 

   319     /**

   320      * Boolean to inform whether we are currently observing

   321      * the mail framework

   322      * Used for example in the startup to prevent callbacks before

   323      * the object is fully initialized.

   324      */    

   325     TBool iObserving;

   326     

   327     // Destructor key for the ECOM plugin

   328     TUid                               iDestructorKey;

   329     

   330     RArray<TNewMailInfo> iNewInboxEntries;

   331     

   332     CNewMailNotificationTimer* iTimer;

   333     };

   334 

   335 #include "fsnotificationhandlerbase.inl"

   336 

   337 #endif  //__FSNOTIFICATIONHANDLERBASE_H__