1 /*

     2 * Copyright (c) 2005 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:  Used as proxy for phone application to get and observe 

    15 *                the change of the variable.state of the phone.

    16 *

    17 */

    18 

    19 

    20 #ifndef __CPHONEPUBSUBPROXY_H

    21 #define __CPHONEPUBSUBPROXY_H

    22 

    23 //  INCLUDES

    24 #include <coemain.h>

    25 #include <e32property.h>

    26 #include "mphonepubsubobserver.h"

    27 

    28 // FORWARD DECLARATIONS

    29 class CPhonePublishSubscriberAO;

    30 class CIdle;

    31 

    32 /**

    33 *  CPhonePubSubProxy is an API used as proxy for phone application to get/set

    34 *  and observe variable states.

    35 *

    36 *  How to get some setting?

    37 *  ---------------------------

    38 *  example code:

    39 *

    40 *  TUid category = KUidSystemCategory

    41 *  TUInt key = KPSUidAutolockStatusValue

    42 *  Tint value = CPhonePubSubProxy::Instance()->GetValue( category, key ); 

    43 *  

    44 *  uid and states can be found in PSVariables.h

    45 *  

    46 *  How to set any settings

    47 *  --------------------------------------

    48 *  example code:

    49 *

    50 *  TUid category = KUidSystemCategory

    51 *  TUInt key = KPSUidAutolockStatusValue

    52 *  TInt value = EPSAutolockOn;

    53 *

    54 *  CPhonePubSubProxy::Instance()->ChangePropertyValue( category, key, value );

    55 *

    56 *  How to observe any settings

    57 *  --------------------------------------

    58 *  example code:

    59 * 

    60 *  class CPhoneSomeManager : private MPhonePubSubObserver

    61 *  {

    62 *  

    63 *  virtual void HandlePropertyChangedL( const TUid& aCategory, 

    64 *            const TUint aKey, const TInt aValue );

    65 *  }

    66 *

    67 *  CPhoneSomeManager::SomeFunctionL

    68 *      {

    69 *      CPhonePubSubProxy::Instance()->NotifyChangeL( cat1, key1, this );

    70 *      CPhonePubSubProxy::Instance()->NotifyChangeL( cat2, key2, this );

    71 *      }

    72 *  

    73 *  CPhoneSomeManager::HandlePropertyChangedL( 

    74 *      const TUid& aCategory, 

    75 *      const TUint aKey, 

    76 *      const TInt aValue )

    77 *      {

    78 *      switch( aCategory )

    79 *          {

    80 *          case KUidSomeCategory1:

    81 *               .... //do something for the category i.e. look at value

    82 *          case KUidSomeCategory2:

    83 *               .... //do something for the category i.e. look at value

    84 *          default:

    85 *               .... //panic in debug

    86 *          }

    87 *      }

    88 *

    89 *  The CancelAllNotifies() should be always called before destroy the object

    90 *  CPhoneSomeManager::~CPhoneSomeManager()

    91 *      {

    92 *      CPhonePubSubProxy::Instance()->CancelAllNotifies( this );

    93 *      }

    94 */

    95 

    96 // CLASS DECLARATION

    97 

    98 /**

    99 *  Used as proxy for phone application to get and observe the change of the

   100 *  state of the phone.

   101 */

   102 class CPhonePubSubProxy : public CCoeStatic, public MPhonePubSubObserver

   103     {

   104     public:  // Constructors and destructor

   105         

   106         /**

   107         * First call initializes the singleton object. Subsequent calls 

   108         * return instance.

   109         * @return the created instance.

   110         */

   111         IMPORT_C static CPhonePubSubProxy* Instance();

   112 

   113         /**

   114         * Destructor.

   115         */

   116         IMPORT_C virtual ~CPhonePubSubProxy();

   117 

   118     public: // New Functions 

   119 

   120         /**

   121         * Cancel all requests by the observer. This function should always be 

   122         * call before an object is destroyed. During shutdown, this singleton

   123         * may be deleted before the classes that observe it. If this happens, the

   124         * routine will just return since of requests have already been cancelled.

   125         * @param aObserver

   126         */

   127         IMPORT_C static void CancelAllNotifications( 

   128             MPhonePubSubObserver* aObserver );

   129         

   130         /**

   131         * Get the property value of particular category key.

   132         *

   133         * @param aCategory the category for the key.

   134         * @param aKey the property key.

   135         * @return current property value.

   136         */

   137         IMPORT_C TInt Value( const TUid& aCategory, const TUint aKey );

   138 

   139         /**

   140         * Notify the change of state to particular varible.

   141         *

   142         * @param aUid Specify the uid of the particular varible.

   143         * @param aObserver The observer to receive the notification.

   144         */

   145         IMPORT_C void NotifyChangeL( 

   146             const TUid& aCategory, 

   147             const TUint aKey,

   148             MPhonePubSubObserver* aObserver );

   149 

   150         /**

   151         * Change a specific property value.

   152         *

   153         * @param aCategory Category of property.

   154         * @param aKey Property key to be changed

   155         * @param aValue New property value.

   156         */

   157         IMPORT_C void ChangePropertyValue( 

   158             const TUid& aCategory,

   159             const TUint aKey,

   160             const TInt aValue );

   161 

   162     private:

   163         /**

   164         * Two-phased constructor.

   165         * @return new instance.

   166         */

   167         static CPhonePubSubProxy* NewL();

   168 

   169         /**

   170         * C++ constructor.

   171         */

   172         CPhonePubSubProxy();

   173 

   174         /**

   175         * Symbian OS constructor.

   176         */

   177         void ConstructL();

   178 

   179     private:

   180         

   181         /**

   182         * Cancel all request by the observer. 

   183         * @param aObserver

   184         */

   185         void CancelAllObserverNotifies( 

   186             MPhonePubSubObserver* aObserver );

   187         

   188         /**

   189         * function used to forward change events to observers.

   190         * @param aCategory Category of property

   191         * @param aKey Property key that is changed

   192         * @param aValue New property value

   193         */

   194         void HandlePropertyChangedL( 

   195             const TUid& aCategory, 

   196             const TUint aKey, 

   197             const TInt aValue );

   198         

   199     private:    // Data

   200 

   201         // Observer elements.

   202         class TPubSubObserverTag

   203             {

   204            public: 

   205                 // Unique property category.

   206                 TUid iCategory; 

   207                 // Property key

   208                 TUint iKey;

   209                 // Observer.

   210                 MPhonePubSubObserver* iObserver;

   211             };

   212 

   213         // Owned array of observers.

   214         CArrayFixFlat<TPubSubObserverTag>* iObserverArray;

   215 

   216         // Owned array of publish subscribers.

   217         CArrayPtrFlat<CPhonePublishSubscriberAO>* iPublishSubscriberArray;

   218 

   219     };

   220 

   221 #endif      // __CPHONEPUBSUBPROXY_H

   222             

   223 // End of File