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 

    33 

    34 /**

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

    36  *

    37  *  @code

    38  *   ?good_class_usage_example(s)

    39  *  @endcode

    40  *

    41  *  @lib ?library

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

    43  */

    44 class CFSNotificationHandlerBase : public CBase, public MFSMailEventObserver

    45     {

    46 public:

    47     

    48     /**

    49      * Two-phased constructor.

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

    51      */ 

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

    53     

    54 public:

    55     

    56     /**

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

    58     * is used to access email framework.

    59     *

    60     * @since S60 ?S60_version

    61     * @return Reference to framework object.

    62     */

    63     CFSMailClient& MailClient() const;

    64 

    65 // from base class MFSMailEventObserver

    66 

    67     /**

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

    69     * Default implementation checks whether the startup is complete

    70     * and therefore the object of this class is observing

    71     * events.

    72     * Also checks whether for example the mailbox has capabilities

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

    74     * is checked by calling CapabilitiesToContinueL function which

    75     * should return ETrue whether the capabilities indicate that

    76     * the notification handling should be continued.

    77     * If notification handling is continued then call for HandleEventL

    78     * is made.

    79     *

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

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

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

    83     * manager class.

    84     *

    85     * @see MFSMailEventObserver::EventL

    86     */

    87     virtual void EventL( TFSMailEvent aEvent, TFSMailMsgId aMailbox,

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

    89 

    90     /**

    91     * Destructor.

    92     */

    93     virtual ~CFSNotificationHandlerBase();

    94 

    95 

    96 protected:  

    97   

    98     /**

    99     * Constructor.

   100     *

   101     * @since S60 ?S60_version

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

   103     */ 

   104     CFSNotificationHandlerBase( MFSNotificationHandlerMgr& aOwner );

   105     

   106     void ConstructL();

   107     

   108     /**

   109     * Getter for information whether the handler is observing events

   110     *

   111     * @since S60 ?S60_version

   112     * @return Whether handler is observing or not

   113     */         

   114     TBool Observing() const;

   115     

   116     /**

   117     * Function that goes through messages identified by the

   118     * message ids given in the parameter array and checks

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

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

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

   122     * in the folder.

   123     *

   124     * @since S60 ?S60_version

   125     * @param aMailboxId Mailbox which contains the messages

   126     *                   checked here.

   127     * @param aParentFolderId Folder that contains the messages

   128     *                        checked here.

   129     * @param aMsgIdList List of message identifiers identifying

   130     *                   the messages that should be checked

   131     *                   for newest unread message.

   132     * @return Boolean value to indicate whether newest unread

   133     *         messages was found among the identified messages.

   134     */

   135     virtual TBool MessagesCauseNotificationL( TFSMailMsgId aMailboxId,

   136                                               CFSMailFolder& aParentFolder,

   137                                               const RArray<TFSMailMsgId>& aMsgIdList );

   138     

   139 

   140     /**

   141     * Function that checks whether the given message is unread

   142     * or not.

   143     *

   144     * @since S60 ?S60_version

   145     * @param aMessage Message which is checked.

   146     * @return Boolean indicating whether the message was unread

   147     *         or not. ETrue means unread.

   148     */ 

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

   150 

   151 protected:

   152     

   153     /**

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

   155     * which is used to access Home Screen status.

   156     *

   157     * @since S60 ?S60_version

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

   159     *         transferred. NULL is returned if the connection

   160     *         cannot be provided.

   161     */    

   162     CFSNotificationHandlerHSConnection* HSConnection() const;

   163      

   164     /**

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

   166     *

   167     * @since S60 ?S60_version

   168     * @param aNewValue New value for observing info

   169     */     

   170     void SetObserving( TBool aNewValue );

   171      

   172     /**

   173      * Function that is used to check desired capabilities.

   174      * Default implementation of this function checks that the mailbox

   175      * does not have EFSMBoxCapaNewEmailNotifications capability. If it

   176      * has then EFalse is returned. 

   177      *

   178      * @see EventL for parameters.

   179      *

   180      * @since S60 ?S60_version

   181      */   

   182     virtual TBool CapabilitiesToContinueL(

   183         TFSMailEvent aEvent,

   184         TFSMailMsgId aMailbox,

   185         TAny* aParam1,

   186         TAny* aParam2,

   187         TAny* aParam3 ) const;

   188 

   189     /**

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

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

   192      * if the messages cause MessagesCauseNotification() to return

   193      * ETrue.

   194      *

   195      * @see EventL for parameters.

   196      *

   197      * @since S60 ?S60_version

   198      */     

   199     virtual void HandleEventL(

   200         TFSMailEvent aEvent,

   201         TFSMailMsgId aMailbox,

   202         TAny* aParam1,

   203         TAny* aParam2,

   204         TAny* aParam3 );

   205 

   206 

   207     /**

   208      * Function that gets the newest message from the given

   209      * folder.

   210      *

   211      * @since S60 ?S60_version

   212      * @param aFolder Folder where from the newest message

   213      *                is searched.

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

   215      *         no messages are found, leaves with KErrNotFound.

   216      */      

   217     CFSMailMessage* NewestMsgInFolderL(

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

   219 

   220 private:

   221 

   222     /**

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

   224      *

   225      * @since S60 ?S60_version

   226      */  

   227     virtual void TurnNotificationOn() = 0;

   228 

   229     /**

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

   231      *

   232      * @since S60 ?S60_version

   233      */  

   234     virtual void TurnNotificationOff() = 0;

   235     

   236 protected: // data

   237 

   238     /**

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

   240      */    

   241     MFSNotificationHandlerMgr& iOwner;

   242 

   243 private: // data

   244 

   245     /**

   246      * Boolean to inform whether we are currently observing

   247      * the mail framework

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

   249      * the object is fully initialized.

   250      */    

   251     TBool iObserving;

   252     

   253     // Destructor key for the ECOM plugin

   254     TUid                               iDestructorKey;

   255     };

   256 

   257 #include "fsnotificationhandlerbase.inl"

   258 

   259 #endif  //__FSNOTIFICATIONHANDLERBASE_H__