// Copyright (c) 1999-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 __ASSRVSOUNDCONTROLLER_H__
#define __ASSRVSOUNDCONTROLLER_H__

// System includes
#include <e32base.h>
#include <babitflags.h>

// User includes
#include <asshddefs.h>
#include "ASSrvAlarmObserver.h"
#include "ASSrvAlarmQueueObserver.h"
#include "ASSrvSoundSettingsObserver.h"
#include "ASSrvSoundControllerObserver.h"
#include "ASSrvEnvironmentChangeObserver.h"

// Classes referenced
class TASSrvAlarm;
class CASSrvServerWideData;
class MASSrvSoundControllerObserver;


//
// ----> CASSrvSoundController (header)
//
/**
 * The sound controller performs all the timing related functionality associated
 * with the sound play intervals (these essentially are "auto-snoozed" alarm sounds,
 * whereby after a given length of time, the alarm sound is silenced for a small
 * amount of time). For example, the sound plays for 30 seconds, then is silent
 * for 30, then it plays again for 30 seconds, and then is slient for 1 minute, etc.
 *
 * The sound controller notifies an observer which actually implements the sound
 * playing functionality (in fact, the observer is just a proxy for the Alarm
 * Alert Server, where the sound is really played).
 */
class CASSrvSoundController : public CTimer, 
	public MASSrvAlarmObserver, 
	public MASSrvSoundSettingsObserver, 
	public MASSrvAlarmQueueObserver, 
	public MASSrvEnvironmentChangeObserver
	{
//
public:										// STATIC CONSTRUCT / DESTRUCT
//
	static CASSrvSoundController*			NewL(CASSrvServerWideData& aServerWideData, MASSrvSoundControllerObserver& aObserver);
	~CASSrvSoundController();

//
private:									// INTERNAL CONSTRUCT
//
	CASSrvSoundController(CASSrvServerWideData& aServerWideData, MASSrvSoundControllerObserver& aObserver);
	void									ConstructL();

//
private:									// FROM MASSrvAlarmObserver
//

	/**
	 * @see MASSrvAlarmObserver
	 *
	 * When an alarm expires, we should start timing the alarm sound intervals. Note that
	 * no sound is played directly by the alarm server - it's all handled by proxy in the
	 * EikSrv thread (Alarm Alert Server).
	 * 
	 * We only ever receive one notification that an alarm has expired (unless its snoozed
	 * and then the snooze expires). Therefore, the sound controller has to perform cycle
	 * management for the alerting (notifying) head alarm in the queue).
	 */
	void									MASSrvAlarmObsHandleEvent(TObserverEvent aEvent, const TASSrvAlarm& aAlarm, TInt aEventSpecificData);

//
private:									// FROM MASSrvSoundSettingsObserver
//

	/**
	 * @see MASSrvSoundSettingsObserver
	 */
	void									MASSoundSettingsHandleChangeEvent(TSoundSettingsEvent aEvent);

//
private:									// FROM MASSrvAlarmQueueObserver
//

	/**
	 * @see MASSrvAlarmQueueObserver
	 */
	void									MAlarmQueueObserverHandleEvent(TASSrvAlarmQueueEvent aEvent, TAlarmId aAlarmId);

//
private:									// FROM MASSrvEnvironmentChangeObserver
//

	/**
	* @see MASSrvEnvironmentChangeObserver
	*
	* Since PREQ234 all alarm silent periods are stored in UTC time but specified in 
	* local time hence the need to track changes to system time.
	*/

	void MEnvChangeHandleEvent(TInt aChanges, TUint aWorkdays, TBool aWorkdaysChanged);

//
public:										// ACCESS
//

	/**
	 * Stops any sound from playing and resets the sound timer to an idle state.
	 */
	void									CancelAllSounds();

	/**
	 * Stop playing any sounds until the specified time updating with UTC offset changes.
	 */
	void									MakeAllSoundsQuietUntil(const TTime& aTime);
	
	/**
	 * Returns the
	 */
	inline const TTime&						SoundsQuietUntil() const { return iTimeToReturnToNormalSoundTimingBehaviour; }

	/**
	 * Stop playing the sound (for just this alarm) until the specified time.
	 */
	void									CurrentAlarmSoundPausedUntil(const TTime& aTime);

	/**
	 * Returns a boolean indicating whether or not the alarm server is currently
	 * in a quiet period.
	 */
	TBool									InQuietPeriod() const;

	/**
	 * Return a boolean indicating whether sound is currently
	 * paused within the alarm server.
	 */
	TBool									SoundIsPausedForAlarm() const;

	/**
	 * Cancel a previously enabled silent period
	 */
	void									CancelSilence();
	
	/**
	 * Do not update silent period with UTC offset changes.
	 */
	inline void								SetFixed() { Flags().Set(ESoundControllerFlagsIsFixed); }

	/**
	 * Update silent period with UTC offset changes.
	 */	
	inline void								SetFloating() { Flags().Clear(ESoundControllerFlagsIsFixed); }

	void									CancelSound(TAlarmId aAlarmId);
	
//
private:									// FROM CActive
//

	/**
	 * @see CActive
	 */
	void									RunL();

	/**
	 * Replacement of CActive::Cancel function
	 */
	void									Cancel();

//
private:									// INTERNAL
//

	/**
	 * Access the server wide data
	 */
	inline CASSrvServerWideData&			ServerData() const { return iServerWideData; }

	/**
	 * Writable access to this class' interal flags
	 */
	inline TBitFlags&						Flags() { return iSoundControllerFlags; }

	/**
	 * Access to this class' interal flags
	 */
	inline const TBitFlags&					Flags() const { return iSoundControllerFlags; }

	/**
	 * Writable access to the id of the currently notifying alarm
	 */
	inline TAlarmId&						IdOfNotifyingAlarm() { return iIdOfNotifyingAlarm; }

	/**
	 * The id of the currently notifying alarm
	 */
	inline TAlarmId							IdOfNotifyingAlarm() const { return iIdOfNotifyingAlarm; }

	/**
	 * Handle a timer event - called when the sound timer expires
	 */
	void									ReactToSoundTimerExpiry();

	/**
	 * Notify observers about the specified event
	 */
	void									NotifySoundEvent(MASSrvSoundControllerObserver::TSoundControllerEvent aEvent, TAlarmId aAlarmId);

	/**
	 * Manage sound timing
	 */
	void									StartSoundTimingForAnyWaitingAlarmAfterPausingOrQuietPeriod();

	/**
	 * Calculate when the next start/stop timer period should be for
	 * alarm sounds
	 */
	void									WorkOutAndScheduleForNextSoundCycle();
	
	/**
	 * Indicates that the Sound Controller is disabled (ie. no sounds
	 * intervals configured in the rsc file)
	 */
	TBool									IsSoundControllerDisabled() const;
	

	void									PlayPreviousNotifyingAlarm();

//
private:									// INTERNAL ENUMERATIONS
//
	/**
	 * Internal sound flags
	 */
	enum TSoundControllerFlags
		{
		/**
		 * Pausing
		 */
		ESoundControllerFlagsPausing		= 0,

		/**
		 * Quiet period
		 */
		ESoundControllerFlagsInQuietPeriod	= 1,
		
		/**
		 * Until (floating) or For (fixed) silent period
		 */
		 
		ESoundControllerFlagsIsFixed = 2,
		};

//
private:									// MEMBER DATA
//

	/**
	 * The alarm id of the alarm which is currently being timed. KNullAlarmID if 
	 * no current alarm to notify.
	 */
	TAlarmId								iIdOfNotifyingAlarm;

	/**
	 * Record the previous sound event we sent to the SoundControlllerObserver
	 * (and AlertServer) so that we can suppress duplicate events.
	 */
	MASSrvSoundControllerObserver::TSoundControllerEvent	iPreviousSoundEvent;

	/**
	 * The time when normal sound behaviour should be resumed.
	 */
	TTime									iTimeToReturnToNormalSoundTimingBehaviour;

	/**
	 * Internal flags
	 */
	TBitFlags								iSoundControllerFlags;

	/**
	 * The server wide data handle
	 */
	CASSrvServerWideData&					iServerWideData;

	/**
	 * The observer of this class, in this case, the notification
	 * co-ordinator
	 */
	MASSrvSoundControllerObserver&			iObserver;
	
	/**
	 * UTC offset when the last request involving time was made
	 */
	 
	 TTimeIntervalSeconds iPreviousUTCOffset;
	};

#endif