// Copyright (c) 2004-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:

//

#ifndef __CSIMREDUCETIMERS_H__

#define __CSIMREDUCETIMERS_H__

/**

 * @file

 *

 * Definition of the observer pattern, which is used in the simulator,

 * to give the functionality of reducing the timers that are used

 * throughout.

 */

#include <simtsy.h>

#include "CSimPubSub.h"

const TInt KTimerDelayOnReduceTimeSignal = 3;		//< Constant value of seconds delay to give timers before stopping.

/**

Definition of the observer required for a CSimTimer object.

*/

class MSimTimerUpdateObserver

	{

public:

	/**

	Method to be used for updating the timer associated with this

	observer.

	@param aSecsOffTimer The number of seconds to reduce off the

	                     remaining time duration in this objects

	                     corresponding timer.

	*/

	virtual void Update(TInt aSecsOffTimer) =0;

	/**

	Method for obtaining information regarding this observer, which in

	this case is the time duration remaining on the corresponding

	timer.

	@return The number of seconds remaining on this object's

	        corresponding timer.

	*/

	virtual TInt GetRemainingSeconds() const =0;

	/**

	Method for obtaining information regarding this observer, which in

	this case is the event assocated with the timer

	@return The timer event ID as defined in TTimerEventId in simtsy.h

	*/

	virtual TInt GetTimerEventInfo() const =0;

	};

/**

Defines the requirements of a subject for observing and updating

CSimTimer objects.  This is particularly useful for reducing the time

durations originally given to the simulator.

*/

class MSimTimersSubject

	{

public:

	/**

	Method used to remove an observer, aObserver, from this

	object's list of attached/registered observers.

	@param aObserver The observer to add to this subject's list of

	                 observers.

	*/

	virtual void AttachL(MSimTimerUpdateObserver* aObserver) =0;

	/**

	Method used to remove an observer, aObserver, from this

	object's list of attached/registered observers.

	@param aObserver The observer to remove from this subject's list of

	                 observers.

	*/

	virtual void DetachL(MSimTimerUpdateObserver* aObserver) =0;

private:

	/**

	Method for notifying all attached/registered observers that a

	change has occurred.

	*/

	virtual void Notify() =0;

	/**

	Method for notifying an attached/registered observer with specific

	timer event ID and lowest remaining time, that a change has occurred

	*/

	virtual void Notify(TInt aTimerEventId) =0;

	};

/**

Implementation of MSimTimersSubject, used to listen to events

indicating a request to reduce the timers running in the simulator.

This implementation currently uses the Publish & Subscribe API to get a

notification of when a particular property is changed.  On

notification, all registered timer observers will be required to reduce

their timer's duration by the minimum time duration of all these

timers.

The notification must be made by changing a specific property, category

KUidPSSimTsyCategory and sub-key KPSSimTsyTimersReduceTime, to the

value KReduceSimTsyTimers.  (These constants are defined in "SimTsy.h")

Example:

@code

// Optional, but safe to attempt defining property.

TInt ret = RProperty::Define(KUidPSSimTsyCategory, KPSSimTsyTimersReduceTime,

								KPSSimTsyTimersReduceTimeSignalKeyType);

if (ret != KErrNone && ret != KErrAlreadyExists)

	{

	User::Leave(ret);

	}

RProperty stopTimerProperty;

// User's code must create a property handle attached to a property with the

// category KUidPSSimTsyCategory and sub-key KPSSimTsyTimersReduceTime.

User::LeaveIfError(stopTimerProperty.Attach(KUidPSSimTsyCategory, KPSSimTsyTimersReduceTime));

CleanupClosePushL(stopTimerProperty);

//... Use the simulator.

// The property must then be set to KReduceSimTsyTimers in order to indicate that

// the simulator is no longer required to continue running and thus timers can be reduced.

User::LeaveIfError(stopTimerProperty.Set(KUidPSSimTsyCategory, KPSSimTsyTimersReduceTime,

											KReduceSimTsyTimers));

CleanupStack::PopAndDestroy(&stopTimerProperty);

@endcode

*/

class CSimReduceTimers : public CBase, MPSSimObserver, MSimTimersSubject

	{

public:

	static CSimReduceTimers* NewL();

	~CSimReduceTimers();

	void SimPSEvent(const CSimPubSub::TPubSubProperty aProperty, TInt aStatus);

	void AttachL(MSimTimerUpdateObserver* aObserver);

	void DetachL(MSimTimerUpdateObserver* aObserver);

private:

	CSimReduceTimers();

	void ConstructL();

	void Notify();

	void Notify(TInt aTimerEventId);

private:

	/** The Publish & Subscribe notification object.  This will call

	    the SimPSEvent() method when the specified property

	    (iPSProperty) is changed.*/

	CSimPubSub* iSimPubSub;

	/**	The property this object subscribes to, in order to listen to

	    value changes indicating a request for timers to be reduced.*/

	CSimPubSub::TPubSubProperty iPSProperty;

	/**	Maintains a list of timers currently active, which can

	    therefore have their duration reduced.*/

	RPointerArray<MSimTimerUpdateObserver> iObservers;

	};

#endif