/*
* Copyright (c) 2005 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:  Used as proxy for phone application to get and observe 
*                the change of the variable.state of the phone.
*
*/


#ifndef __CPHONEPUBSUBPROXY_H
#define __CPHONEPUBSUBPROXY_H

//  INCLUDES
#include <coemain.h>
#include <e32property.h>
#include "mphonepubsubobserver.h"

// FORWARD DECLARATIONS
class CPhonePublishSubscriberAO;
class CIdle;

/**
*  CPhonePubSubProxy is an API used as proxy for phone application to get/set
*  and observe variable states.
*
*  How to get some setting?
*  ---------------------------
*  example code:
*
*  TUid category = KUidSystemCategory
*  TUInt key = KPSUidAutolockStatusValue
*  Tint value = CPhonePubSubProxy::Instance()->GetValue( category, key ); 
*  
*  uid and states can be found in PSVariables.h
*  
*  How to set any settings
*  --------------------------------------
*  example code:
*
*  TUid category = KUidSystemCategory
*  TUInt key = KPSUidAutolockStatusValue
*  TInt value = EPSAutolockOn;
*
*  CPhonePubSubProxy::Instance()->ChangePropertyValue( category, key, value );
*
*  How to observe any settings
*  --------------------------------------
*  example code:
* 
*  class CPhoneSomeManager : private MPhonePubSubObserver
*  {
*  
*  virtual void HandlePropertyChangedL( const TUid& aCategory, 
*            const TUint aKey, const TInt aValue );
*  }
*
*  CPhoneSomeManager::SomeFunctionL
*      {
*      CPhonePubSubProxy::Instance()->NotifyChangeL( cat1, key1, this );
*      CPhonePubSubProxy::Instance()->NotifyChangeL( cat2, key2, this );
*      }
*  
*  CPhoneSomeManager::HandlePropertyChangedL( 
*      const TUid& aCategory, 
*      const TUint aKey, 
*      const TInt aValue )
*      {
*      switch( aCategory )
*          {
*          case KUidSomeCategory1:
*               .... //do something for the category i.e. look at value
*          case KUidSomeCategory2:
*               .... //do something for the category i.e. look at value
*          default:
*               .... //panic in debug
*          }
*      }
*
*  The CancelAllNotifies() should be always called before destroy the object
*  CPhoneSomeManager::~CPhoneSomeManager()
*      {
*      CPhonePubSubProxy::Instance()->CancelAllNotifies( this );
*      }
*/

// CLASS DECLARATION

/**
*  Used as proxy for phone application to get and observe the change of the
*  state of the phone.
*/
class CPhonePubSubProxy : public CCoeStatic, public MPhonePubSubObserver
    {
    public:  // Constructors and destructor
        
        /**
        * First call initializes the singleton object. Subsequent calls 
        * return instance.
        * @return the created instance.
        */
        IMPORT_C static CPhonePubSubProxy* Instance();

        /**
        * Destructor.
        */
        IMPORT_C virtual ~CPhonePubSubProxy();

    public: // New Functions 

        /**
        * Cancel all requests by the observer. This function should always be 
        * call before an object is destroyed. During shutdown, this singleton
        * may be deleted before the classes that observe it. If this happens, the
        * routine will just return since of requests have already been cancelled.
        * @param aObserver
        */
        IMPORT_C static void CancelAllNotifications( 
            MPhonePubSubObserver* aObserver );
        
        /**
        * Get the property value of particular category key.
        *
        * @param aCategory the category for the key.
        * @param aKey the property key.
        * @return current property value.
        */
        IMPORT_C TInt Value( const TUid& aCategory, const TUint aKey );

        /**
        * Notify the change of state to particular varible.
        *
        * @param aUid Specify the uid of the particular varible.
        * @param aObserver The observer to receive the notification.
        */
        IMPORT_C void NotifyChangeL( 
            const TUid& aCategory, 
            const TUint aKey,
            MPhonePubSubObserver* aObserver );

        /**
        * Change a specific property value.
        *
        * @param aCategory Category of property.
        * @param aKey Property key to be changed
        * @param aValue New property value.
        */
        IMPORT_C void ChangePropertyValue( 
            const TUid& aCategory,
            const TUint aKey,
            const TInt aValue );

    private:
        /**
        * Two-phased constructor.
        * @return new instance.
        */
        static CPhonePubSubProxy* NewL();

        /**
        * C++ constructor.
        */
        CPhonePubSubProxy();

        /**
        * Symbian OS constructor.
        */
        void ConstructL();

    private:
        
        /**
        * Cancel all request by the observer. 
        * @param aObserver
        */
        void CancelAllObserverNotifies( 
            MPhonePubSubObserver* aObserver );
        
        /**
        * function used to forward change events to observers.
        * @param aCategory Category of property
        * @param aKey Property key that is changed
        * @param aValue New property value
        */
        void HandlePropertyChangedL( 
            const TUid& aCategory, 
            const TUint aKey, 
            const TInt aValue );
        
    private:    // Data

        // Observer elements.
        class TPubSubObserverTag
            {
           public: 
                // Unique property category.
                TUid iCategory; 
                // Property key
                TUint iKey;
                // Observer.
                MPhonePubSubObserver* iObserver;
            };

        // Owned array of observers.
        CArrayFixFlat<TPubSubObserverTag>* iObserverArray;

        // Owned array of publish subscribers.
        CArrayPtrFlat<CPhonePublishSubscriberAO>* iPublishSubscriberArray;

    };

#endif      // __CPHONEPUBSUBPROXY_H
            
// End of File