/*

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

*

*/

#ifndef AKNDYNAMICSOFTNOTIFIER_H

#define AKNDYNAMICSOFTNOTIFIER_H

// INCLUDES

#include <e32base.h>

#include <AknCapServerClient.h>

// FORWARD DECLARATION

class TAknDynamicSoftNotificationParams;

class CAknDynamicSoftNoteObserver;

class CAknDynamicNotifier;

class CAknSDData;

/**

 * Observer interface for dynamic soft notifications.

 * 

 * @see CAknDynamicSoftNotifier

 * @since S60 3.2

 * @lib AknNotify.DLL

 */

class MAknDynamicSoftNoteObserver

    {

public: // New methods    

    /**

     * Dynamic soft notification was accepted by user.

     *

     * @param aNoteId Identification of notification.

     */

    virtual void NotificationAccepted( TInt aNoteId ) = 0;

    /**

     * Dynamic soft notification was canceled by user.

     *

     * @param aNoteId Identification of notification.

     */

    virtual void NotificationCanceled( TInt aNoteId ) = 0;

protected: // protected destructor

    /// Virtual destructor.

    virtual ~MAknDynamicSoftNoteObserver() {};

    };

/**

 * Client API for dynamic Avkon soft notifications.

 *

 * @since S60 3.2

 * @lib AknNotify.DLL

 */

NONSHARABLE_CLASS( CAknDynamicSoftNotifier ) : public CBase

    {

public:

    /// Static constructor.

    IMPORT_C static CAknDynamicSoftNotifier* NewL();

    /// Static constructor.

    IMPORT_C static CAknDynamicSoftNotifier* NewLC();

    /// Destructor.

    IMPORT_C ~CAknDynamicSoftNotifier();

    /**

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

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

     *

     * @param aParams Dynamic soft notification parameters.

     * @param aNoteId Dynamic soft notification identification.

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

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

     *          newly created notification.

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

     * @param aCount Addition count.

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

     *         as aNoteId.

     */

    IMPORT_C TInt AddDynamicNotificationL(

        TAknDynamicSoftNotificationParams& aParams,

        TInt aNoteId = KErrUnknown,

        TInt aCount = 1 );

    /**

     * Sets the absolute count of a dynamic soft notification with

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

     * it is created.

     *

     * @param aParams Dynamic soft notification parameters.

     * @param aNoteId Dynamic soft notification identification.

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

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

     *          newly created notification.

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

     *          notification.

     * @param aCount Absolute count.

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

     *         as aNoteId.

     */

    IMPORT_C TInt SetDynamicNotificationCountL(

        TAknDynamicSoftNotificationParams& aParams,

        TInt aNoteId,

        TInt aCount );

    /**

     * Cancels dynamic soft notification of the given identification.

     *

     * @param aNoteId Dynamic soft notification identification.

     */

    IMPORT_C void CancelDynamicNotificationL( TInt aNoteId );

    /**

     * Add dynamic soft notification observer. 

     * Leaves with KErrAlreadyExists if same NoteId is added twice.

     * Does not take ownership of the observer.

     * 

     * @param aNoteId Soft notification id. 

     * @param aObserver Observer for notification. 

     */

    IMPORT_C void StartObservingL( 

        TInt aNoteId, 

        MAknDynamicSoftNoteObserver* aObserver );

    /**

     * Stop observing the specific soft notification.

     * 

     * @param aNoteId Soft notification id. 

     */

    IMPORT_C void StopObserving( TInt aNoteId );

    /**

     * Sets additional information to be sent to secondary display.

     * Takes ownership of object.

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

     * 

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

     * @internal to S60

     */

    IMPORT_C void SetSecondaryDisplayData( CAknSDData* aData );

public: // Non-exported    

    /**

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

     * 

     * @param aObserver Observer to be deleted.

     */    

    void DeleteObserver( CAknDynamicSoftNoteObserver* aObserver );

    /**

     * Getter for secondary display data.

     * 

     * @return Instance of secondary display data if set.

     */

    CAknSDData* SecondaryDisplayData();

private:

    /// Constructor.

    CAknDynamicSoftNotifier();

    /// 2nd phase constructor.

    void ConstructL();

    /**

     * Internalizes parameters into buffer and sends it to server.

     *

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

     * @param aCount Count of soft notifications.

     * @param aCancel ETrue : Cancel soft notification.

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

     *                   EFalse : Count is absolute value.

     * @param aParams Parameters for dynamic soft notification.

     * @return Identification of created or updated dynamic notification. 

     */

    TInt SendMessageL(

        TInt aNoteId,

        TInt aCount,

        TBool aCancel,

        TBool aAddCount,

        TAknDynamicSoftNotificationParams& aParams );

    /**

     * Find Observer of the given notification id.

     * 

     * @param aNoteId Soft notification id.

     * @return KErrNotFound or index of the observer. 

     */

    TInt FindByNoteId( TInt aNoteId ) const;        

private: // Data

    /// Own. Array of observed soft notifications.

    RPointerArray<CAknDynamicSoftNoteObserver> iObservers;

    /// Own. Secondary display custom data.

    CAknSDData* iSecondaryDisplayData;

    /// Own. Notifier handle.

    CAknDynamicNotifier* iNotifier;

    };

#endif // AKNDYNAMICSOFTNOTIFIER_H