/*
* Copyright (c) 2006-2009 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:  Definition of CPropertyWatcher class.*
*/


#ifndef PROPERTYWATCHER_H
#define PROPERTYWATCHER_H

// SYSTEM INCLUDE
#include <e32base.h>

// FORWARD DECLARATIONS
class CListener;
class MKeyObserver;
class MKeyAndStatusObserver;

// CLASS DECLARATION
/**
 *  An instance of the CPropertyWatcher object - singleton.
 *  Create listeners for RProperty key changes. This class
 *  uses TLS implementation. 
 *
 *  @code
 *	
 * // Get instance
 * iPropertyWatcher = CPropertyWatcher::GetInstanceL();
 *	
 * // Set wanted key, give gategory's uid, observed key and this pointer.
 * iPropertyWatcher->ListenKeyChangesL( KUidSystemCategory,
 *  	conn::KUidBackupRestoreKey, this );
 *	iPropertyWatcher->ListenKeyChangesL( KPSUidScreenSaver,
 *  	KScreenSaverOn, this );
 *
 * ...
 *  // Implement NotifyKeyL for key canges or NotifyKeyAndStatusL for
 *  // key and status changes. 
 *  void CRestoreWatcher::NotifyKeyL( 
 *		const TInt aKeyValue,
 *		const TUid aPropertyCategory,
 *		const TUint aKey)
 *	{
 *	
 *	// In interface check key's category. 
 *	if( aPropertyCategory == KUidSystemCategory &&
 *		aKey == conn::KUidBackupRestoreKey )
 *		{
 *		TInt backupStateValue = aKeyValue;
 *		backupStateValue &= conn::KBURPartTypeMask;
 *		
 *		if ( backupStateValue >= conn::EBURRestoreFull )
 *			{
 *			// Handle backup here
 *			}
 *		}
 *	
 *	if( aPropertyCategory == KPSUidScreenSaver && aKey == KScreenSaverOn )
 *		{
 *		//Handle screensaver activity here 
 *		}	
 *	}
 * 
 *  // Destruction
 * 
 * 	if( iPropertyWatcher )
 *		{
 *		iPropertyWatcher->StopListeningKeyChanges( 
			KUidSystemCategory,
			conn::KUidBackupRestoreKey, this );
 *		
 *		iPropertyWatcher->Delete(); // Release connection to TLS object.
 *		} 
 * 
 * @endcode
 */
NONSHARABLE_CLASS( CPropertyWatcher ) : public CBase
    {
 public: // Exported.
		
	/*!
	@function GetInstanceL
	@Create a CPropertyWatcher object, 
	@result a pointer to the created instance of CPropertyWatcher.
	*/
	IMPORT_C static CPropertyWatcher* GetInstanceL();
	
	/*!
	@function Delete
	@Release an instance of this singleton.
	*/
	IMPORT_C void Delete();
		
	/*!
	@function ListenKeyChanges
	@Registers to watcher and get events from watcher via MKeyObserver interface.
	@param aPropertyCategory observed key's category.       
	@param aKey observed key.
	@aValueObserver client's pointer. Notive that this is not taking ownership.
	*/
	IMPORT_C void ListenKeyChangesL( const TUid aPropertyCategory,
			 const TUint aKey,
			 const MKeyObserver* aValueObserver
			);
   /*
	@function ListenKeyAndStatusChangesL
	@Registers to watcher and get events from watcher via MKeyAndStatusObserver interface.
	@param aPropertyCategory observed key's category.       
	@param aKey observed key.
	@aStatusObserver client's pointer. Notive that this is not taking ownership.
	*/
   IMPORT_C void ListenKeyAndStatusChangesL( const TUid aPropertyCategory,
			const TUint aKey,
			const MKeyAndStatusObserver* aStatusObserver );

   /*
	@function StopListeningKeyChanges
	@Stops listening key changes. 
	@param aPropertyCategory observed key's category.       
	@param aKey observed key.
	@aValueObserver client's pointer.
	*/
   IMPORT_C void StopListeningKeyChanges( 
			const TUid aPropertyCategory,
			const TUint aKey,
			const MKeyObserver* aKeyObserver );
   
   /*
	@function StopListeningKeyAndStatusChanges
	@Stops listening key and status changes. MDS need this to stop Active sheduler during restore.
	@param aPropertyCategory observed key's category.       
	@param aKey observed key.
	@aValueObserver client's pointer.
	*/
    IMPORT_C void StopListeningKeyAndStatusChanges( 
			const TUid aPropertyCategory,
			const TUint aKey,
			MKeyAndStatusObserver* aStatusObserver );
 
private:  
   /*!
	@function ~CPropertyWatcher
	@Destroy the object and release all memory objects.
	*/
	~CPropertyWatcher();  

private:
	/*!
	@function FindListener
	@Find if there is allredy listener which matches
	@aPropertyCategory and aKey.
	@return listener index, KErrNotFound if not exists.
	*/    	
	TInt FindListener( const TUid aPropertyCategory, const TUint aKey ) const;
  
private:
  
	/*!@iListenersArray - all listeners for different key values.
	 * Owned by this class.
	 */
	RPointerArray<CListener> iListenersArray;    
    };

#endif // PROPERTYWATCHER