/*
* Copyright (c) 2002, 2003 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: Property Observer class for handling property change events.
 *
*/



#ifndef CPROPERTYOBSERVER_H
#define CPROPERTYOBSERVER_H

// INCLUDES
#include <e32base.h>
#include <e32property.h>

// CLASS DECLARATION

/**
 * MPropertyChangeHandler.
 * Abstract interface for handling property change events.
 **/
NONSHARABLE_CLASS( MPropertyChangeHandler )
{
 public:
    /**
     * This is a callback function which is called when a property is changed.
     *
     * @param aCategory  UID of the category.
     * @param aKey       changed key
     * @param aValue     the new value
     *
     * Note! references aKey and aValue are only valid while executing
     * HandlePropertyChange(). After that the data in which they refer can change.
     **/
    virtual void HandlePropertyChange(const TUid& aCategory, const TUint& aKey, const TInt& aValue) = 0;

};


// CLASS DECLARATION

/**
 * ?one_line_short_description.
 * ?other_description_lines
 *
 * @since Series 60 3.0
 **/
NONSHARABLE_CLASS(CPropertyObserver) : public CActive
{
 public:  // Constructors and destructor
    /**
     * Two-phased constructor.
     * @since Series 60 3.0
     * @param ?arg1 ?description
     * @param ?arg2 ?description
     **/
    static CPropertyObserver* NewL(MPropertyChangeHandler& aHandler, const TUid& aCategory, const TUint& aKey, const TBool aSkipValue=EFalse)
    {
        CPropertyObserver* self = new( ELeave )CPropertyObserver( aHandler, aCategory, aKey, aSkipValue );
        CleanupStack::PushL( self );
        self->ConstructL();
        CleanupStack::Pop( self );
        return self;
    };

    /**
     * Destructor.
     **/
    ~CPropertyObserver()
    {
        Deque();
        iProperty.Cancel();
        iProperty.Close();
    };

 private:
    /**
     * C++ default constructor overload.
     **/
    CPropertyObserver(MPropertyChangeHandler& aHandler, const TUid& aCategory, const TUint& aKey, const TBool aSkipValue)
    : CActive( CActive::EPriorityStandard ),
      iCategory( aCategory ),
      iKey( aKey ),
      iHandler( aHandler ),
      iSkipValue( aSkipValue )
    {
    };

    /**
     * By default Symbian 2nd phase constructor is private.
     **/
    void ConstructL(void)
    {
        CActiveScheduler::Add( this );

        User::LeaveIfError( iProperty.Attach( iCategory, iKey ) );

        //NotifyCurrentValue(); // notify initial value

        // Start observing...
        Subscribe();
    };

 protected:  // Functions from base classes
    /**
     * From CActive ?member_description
     **/
    inline void RunL(void);

    /**
     * From CActive ?member_description
     **/
    inline void DoCancel(void);

 private:  // New functions
    /**
     * ?member_description.
     * @since Series 60 3.0
     **/
    inline void Subscribe(void);

    /**
     * ?member_description.
     * @since Series 60 3.0
     **/
    inline void NotifyCurrentValue(void);

 private:  // Data
    // ?one_line_short_description_of_data
    RProperty iProperty;

    // ?one_line_short_description_of_data
    const TUid iCategory;

    // ?one_line_short_description_of_data
    const TUint iKey;

    // ?one_line_short_description_of_data
    MPropertyChangeHandler& iHandler;

    // ?one_line_short_description_of_data
    const TBool iSkipValue;

};

#include "PropertyObserver.inl"

#endif  // CPROPERTYOBSERVER_H


// End of File