1 /*

     2 * Copyright (c) 2008 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:  Client API for Dynamic Avkon soft notifications.

    15 *

    16 */

    17 

    18 #ifndef AKNDYNAMICSOFTNOTIFIER_H

    19 #define AKNDYNAMICSOFTNOTIFIER_H

    20 

    21 // INCLUDES

    22 #include <e32base.h>

    23 #include <AknCapServerClient.h>

    24 

    25 // FORWARD DECLARATION

    26 class TAknDynamicSoftNotificationParams;

    27 class CAknDynamicSoftNoteObserver;

    28 class CAknDynamicNotifier;

    29 class CAknSDData;

    30 

    31 /**

    32  * Observer interface for dynamic soft notifications.

    33  * 

    34  * @see CAknDynamicSoftNotifier

    35  * @since S60 3.2

    36  * @lib AknNotify.DLL

    37  */

    38 class MAknDynamicSoftNoteObserver

    39     {

    40 public: // New methods    

    41     

    42     /**

    43      * Dynamic soft notification was accepted by user.

    44      *

    45      * @param aNoteId Identification of notification.

    46      */

    47     virtual void NotificationAccepted( TInt aNoteId ) = 0;

    48     

    49     /**

    50      * Dynamic soft notification was canceled by user.

    51      *

    52      * @param aNoteId Identification of notification.

    53      */

    54     virtual void NotificationCanceled( TInt aNoteId ) = 0;

    55         

    56     

    57 protected: // protected destructor

    58     

    59     /// Virtual destructor.

    60     virtual ~MAknDynamicSoftNoteObserver() {};

    61     };

    62 

    63 /**

    64  * Client API for dynamic Avkon soft notifications.

    65  *

    66  * @since S60 3.2

    67  * @lib AknNotify.DLL

    68  */

    69 NONSHARABLE_CLASS( CAknDynamicSoftNotifier ) : public CBase

    70     {

    71 public:

    72     /// Static constructor.

    73     IMPORT_C static CAknDynamicSoftNotifier* NewL();

    74 

    75     /// Static constructor.

    76     IMPORT_C static CAknDynamicSoftNotifier* NewLC();

    77 

    78     /// Destructor.

    79     IMPORT_C ~CAknDynamicSoftNotifier();

    80 

    81     /**

    82      * Adds a dynamic soft notification. If a dynamic soft notification with

    83      * exactly the same id already exists, its count is increased by aCount.

    84      *

    85      * @param aParams Dynamic soft notification parameters.

    86      * @param aNoteId Dynamic soft notification identification.

    87      *        - If note is found: Old notification is updated.

    88      *        - If note is not found: method will return the id of

    89      *          newly created notification.

    90      *        - If not provided: New note is always created.

    91      * @param aCount Addition count.

    92      * @return ID ID of created or updated notification. Can be the same

    93      *         as aNoteId.

    94      */

    95     IMPORT_C TInt AddDynamicNotificationL(

    96         TAknDynamicSoftNotificationParams& aParams,

    97         TInt aNoteId = KErrUnknown,

    98         TInt aCount = 1 );

    99 

   100     /**

   101      * Sets the absolute count of a dynamic soft notification with

   102      * given id. If such notification did not exist already,

   103      * it is created.

   104      *

   105      * @param aParams Dynamic soft notification parameters.

   106      * @param aNoteId Dynamic soft notification identification.

   107      *        - If such note is found, then that is updated

   108      *        - If note is not found, then method will return the id of

   109      *          newly created notification.

   110      *        - Use KErrUnknown if you want to create a new dynamic soft 

   111      *          notification.

   112      * @param aCount Absolute count.

   113      * @return ID ID of created or updated notification. Can be the same

   114      *         as aNoteId.

   115      */

   116     IMPORT_C TInt SetDynamicNotificationCountL(

   117         TAknDynamicSoftNotificationParams& aParams,

   118         TInt aNoteId,

   119         TInt aCount );

   120 

   121     /**

   122      * Cancels dynamic soft notification of the given identification.

   123      *

   124      * @param aNoteId Dynamic soft notification identification.

   125      */

   126     IMPORT_C void CancelDynamicNotificationL( TInt aNoteId );

   127  

   128     /**

   129      * Add dynamic soft notification observer. 

   130      * Leaves with KErrAlreadyExists if same NoteId is added twice.

   131      * Does not take ownership of the observer.

   132      * 

   133      * @param aNoteId Soft notification id. 

   134      * @param aObserver Observer for notification. 

   135      */

   136     IMPORT_C void StartObservingL( 

   137         TInt aNoteId, 

   138         MAknDynamicSoftNoteObserver* aObserver );

   139     

   140     /**

   141      * Stop observing the specific soft notification.

   142      * 

   143      * @param aNoteId Soft notification id. 

   144      */

   145     IMPORT_C void StopObserving( TInt aNoteId );

   146 

   147     /**

   148      * Sets additional information to be sent to secondary display.

   149      * Takes ownership of object.

   150      * Must be called before sending data to notifier to have effect.

   151      * 

   152      * @param aData Data to be sent to cover UI.

   153      * @internal to S60

   154      */

   155     IMPORT_C void SetSecondaryDisplayData( CAknSDData* aData );

   156     

   157 public: // Non-exported    

   158      

   159     /**

   160      * Deletes given observer and removes it from the internal array.

   161      * 

   162      * @param aObserver Observer to be deleted.

   163      */    

   164     void DeleteObserver( CAknDynamicSoftNoteObserver* aObserver );

   165     

   166     

   167     /**

   168      * Getter for secondary display data.

   169      * 

   170      * @return Instance of secondary display data if set.

   171      */

   172     CAknSDData* SecondaryDisplayData();

   173     

   174 private:

   175     

   176     /// Constructor.

   177     CAknDynamicSoftNotifier();

   178 

   179     /// 2nd phase constructor.

   180     void ConstructL();

   181 

   182     /**

   183      * Internalizes parameters into buffer and sends it to server.

   184      *

   185      * @param aNoteId Notification Identifier which is to be updated. 

   186      * @param aCount Count of soft notifications.

   187      * @param aCancel ETrue : Cancel soft notification.

   188      * @param aAddCount  ETrue  : Count is added to previous count.

   189      *                   EFalse : Count is absolute value.

   190      * @param aParams Parameters for dynamic soft notification.

   191      * @return Identification of created or updated dynamic notification. 

   192      */

   193     TInt SendMessageL(

   194         TInt aNoteId,

   195         TInt aCount,

   196         TBool aCancel,

   197         TBool aAddCount,

   198         TAknDynamicSoftNotificationParams& aParams );

   199 

   200     /**

   201      * Find Observer of the given notification id.

   202      * 

   203      * @param aNoteId Soft notification id.

   204      * @return KErrNotFound or index of the observer. 

   205      */

   206     TInt FindByNoteId( TInt aNoteId ) const;        

   207     

   208 private: // Data

   209     /// Own. Array of observed soft notifications.

   210     RPointerArray<CAknDynamicSoftNoteObserver> iObservers;

   211     /// Own. Secondary display custom data.

   212     CAknSDData* iSecondaryDisplayData;

   213     /// Own. Notifier handle.

   214     CAknDynamicNotifier* iNotifier;

   215     };

   216 

   217 #endif // AKNDYNAMICSOFTNOTIFIER_H