// 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 __ASSHDALARM_H__
#define __ASSHDALARM_H__


// System Includes
#include <e32base.h>
#include <s32strm.h>

// User Includes
#include <asshddefs.h>

#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS

/**
 * The Alarm publish and subscribe category
 * 
 * @publishedPartner
 * @released
 */
const TUid KAlarmServerPubSubCategory = { 0x101f5027 };

/**
 * Used for subcribing missed alarms or time zone changes
 * @publishedPartner
 * @released
 */
const TUint KMissingAlarmPubSubKey = 100;

/**
 * The publish and subscribe data for KMissingAlarmPubSubKey
 * @publishedPartner
 * @released
 */
struct TMissedAlarmPubSubData
	{
	/**
	 * The value indicating the changes.
	 * 1 - Time zone has been changes but there are no missed alarms
	 * 2 - Some alarms have been missed after system time or time zone has changed.
	 */
	TUint8 iValue;
	
	/**
	 * The time that system time change took place, in universal (UTC) time 
	 */
	TTime iTimeOfChangeUtc;
	};

#ifdef SYMBIAN_SKIPPED_CALENDAR_ALARMS
/**
 * Used for subscribing to data used when searching for instances in Calendar
 * @publishedPartner
 * @released
 */
const TUint KSkippedAlarmInstancesPubSubKey = 101;

/**
 * The publish and subscribe data for KMissingAlarmInstancesPubSubKey
 * @publishedPartner
 * @released
 */
struct TASShdAlarmedInstanceParams
	{
	/**
	 * The start of the time range in local time.
	 */ 
	TTime iLocalStartTime;

	/**
	 * The end of the time range in local time.
	 */
	TTime iLocalEndTime;
	
	/**
	 * The alarm time types to include.
	 */
	TASShdAlarmTimeType iTimeType;
	};

#endif //SYMBIAN_SKIPPED_CALENDAR_ALARMS
#endif //SYMBIAN_ENABLE_SPLIT_HEADERS


#ifdef SYMBIAN_SYSTEM_STATE_MANAGEMENT

/**
 * Used for subcribing wake-up alarm set and unset notifications
 * Belonging to the KAlarmServerPubSubCategory alarm publish and subscribe category
 * 
 * @publishedPartner
 * @released
 */
const TUint KWakeupAlarmPubSubKey = 102;

/**
 * Alarm server sets KWakeupAlarmPubSubKey value to EActiveWakeupAlarmSet when there is an active
 * wakeup alarm in the alarm queue otherwise sets it to EActiveNoWakeupAlarmsSet. 
 * A wakeup alarm starts the device if it is powered off when the alarm expires. If 
 * the device is in normal mode then it works as a clock alarm.      
 * An active wakeup alarm is a wakeup alarm which has been set and has not started to alert yet.
 *  
 * EActiveWakeupAlarmUninitialized is used to notify the listeners of 'KWakeupAlarmPubSubKey' 
 * key that the Alarm Server has just started at the device boot time and it needs to internalize 
 * Alarm Queue from backup before checking for the presence of active wake-up alarm. 
 *  
 * @publishedPartner
 * @released
 */
enum TActiveWakeupAlarmStatus
    {
    EActiveWakeupAlarmUninitialized = 100,
    EActiveWakeupAlarmSet,
    EActiveNoWakeupAlarmsSet,
    };

#endif

/**
 * A client-side alarm object.
 * 
 * It contains all of the information needed to create an alarm in the Alarm Server.
 * 
 * @publishedAll
 * @released
 */
class TASShdAlarm
	{
public:										

	IMPORT_C TASShdAlarm();

public:										

	IMPORT_C void InternalizeL(RReadStream& aStream);
	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

public:								
    // Read-Only Access
    
    /**
     * Returns the alarm status.
     * 
     * @return Alarm status.
     */
	inline TAlarmStatus	Status() const { return iStatus; }

	/**
	 * Returns the alarm state.
	 * 
	 * @return Alarm state.
	 */
	inline TAlarmState State() const { return iState; }

	IMPORT_C TBool HasAssociatedData() const;
	IMPORT_C TBool HasOwningSession() const;
	IMPORT_C TBool HasBecomeOrphaned() const;
	
public:								

	IMPORT_C void Reset();

    /**
     * Returns a writable version of the alarm's unique identifier.
     * 
     * @return Reference to the unique identifier.
     */
	inline TAlarmId& Id() { return iAlarmId; }

	/**
	 * Return the alarm's unique identifier.
	 * 
	 * @return The unique identifier.
	 */
	inline TAlarmId	Id() const { return iAlarmId; }
		
	/**
	 * The Secure ID is only used in the secured platform
	 */ 
	
	// adds a SID to the alarms private field
	inline void SetSid(const TSecureId& aSecureID) {iTASShdAlarmSID = aSecureID;}
	
	//	returns the SID of the alarm's creator
	inline TSecureId GetSid() const {return iTASShdAlarmSID;}

    /**
     * Returns a writable version of the next time the alarm is scheduled to expire.
     * 
     * @return Next expiry time.
     */
	inline TTime& NextDueTime() { return iNextDueTime; }

    /**
     * Returns the next time that the alarm is scheduled to expire.
     * 
     * @return Next expiry time.
     */
	inline const TTime&	NextDueTime() const { return iNextDueTime; }

    /**
     * Returns a writable version of the alarm's original expiry time.
     * 
     * @return Original expiry time.
     */
	inline TTime& OriginalExpiryTime() { return iOriginalExpiryTime; }

    /**
     * Returns the alarm's original expiry time.
     * 
     * The original expiry time is the same as the next due time, unless the alarm
     * has been snoozed. In that case, the original expiry time is the time when
     * the alarm first expired, and the next due time is when it is to re-awaken
     * after the snooze.
     * 
     * @return Original expiry time.
     */
	inline const TTime& OriginalExpiryTime() const { return iOriginalExpiryTime; }

    /**
     * Returns a writable version of the alarm's category.
     * 
     * Clients can use the category to tag each alarm with a specific code. This
     * allows clients to identify all related alarms, such as all alarms associated
     * with a particular application or application engine.
     * 
     * @return Alarm category.
     */
	inline TAlarmCategory& Category() { return iCategory; }

    /**
     * Return this alarm's category.
     * 
     * @return Alarm category.
     */
	inline TAlarmCategory Category() const { return iCategory; }

    /**
     * Returns a writable version of the alarm's characteristics.
     * 
     * @return Alarm characteristics bit flags.
     */
	inline TAlarmCharacteristicsFlags& Characteristics() { return iCharacteristics; }

    /**
     * Returns the alarm's characteristics
     * 
     * @return Alarm characteristics bit flags.
     */
	inline TAlarmCharacteristicsFlags Characteristics() const { return iCharacteristics; }

    /**
     * Returns a writable version of the alarm's repeat definition.
     * 
     * The repeat definition controls the alarm's behaviour after it has expired.
     * For example, you can set the repeat definition so that the server automatically
     * queues the alarm to expire again in exactly 24 hours time.
     * 
     * @return Alarm repeat definition.
     */
	inline TAlarmRepeatDefinition& RepeatDefinition() { return iRepeatDefinition; }

    /**
     * Returns the repeat definition for the alarm.
     * 
     * @return The alarm's repeat definition.
     */
	inline TAlarmRepeatDefinition RepeatDefinition() const { return iRepeatDefinition; }

    /**
     * Returns a writable version of the alarm's message.
     * 
     * The message is usually displayed in the application UI when the alarm expires.
     * 
     * @return Reference to the alarm's associated message.
     */
	inline TAlarmMessage& Message() { return iMessage; }

    /**
     * Returns the alarm's message.
     * 
     * The message is usually displayed in the application UI when the alarm expires.
     * 
     * @return Reference to the alarm's associated message.
     */
	inline const TAlarmMessage& Message() const { return iMessage; }

    /**
     * Return a writable version of the alarm sound's filename.
     * 
     * @return Reference to the alarm's sound filename.
     */
	inline TAlarmSoundName& SoundName() { return iSoundName; }

    /**
     * Returns the alarm's sound filename.
     * 
     * @return Sound filename.
     */
	inline const TAlarmSoundName& SoundName() const { return iSoundName; }

    /**
     * Returns the alarm session type.
     * 
     * @return Alarm session type.
     */
	inline TAlarmDayOrTimed DayOrTimed() const { return iDayOrTimed; }

    /**
     * Returns a writable version of the alarm type, i.e. day, timed
     * 
     * @return iDayOrTimed.
     */ 
	inline TAlarmDayOrTimed& DayOrTimed() { return iDayOrTimed; }
   
	IMPORT_C void SetUtcNextDueTime(TTime aUtcTime);
	IMPORT_C void SetDeQueueIfDueTimeInPast();
	
#ifdef SYMBIAN_SYSTEM_STATE_MANAGEMENT
	IMPORT_C void SetWakeup(TBool aEnabled);
	IMPORT_C TBool IsWakeup() const;
#endif

#ifdef SYMBIAN_ALARM_REPEAT_EXTENSIONS
	IMPORT_C TInt SetAlarmDays(TUint8 aAlarmDays);
	IMPORT_C TUint8 AlarmDays() const;
	IMPORT_C void SetContinuous(TBool aContinuous);
	IMPORT_C TBool Continuous();
#endif
	
public:										
    // CLient Data Access 

    /**
     * Returns a writable version of the alarm's client flags.
     * 
     * The client flags may be used for any client-specific data - the alarm server does not use them.
     * 
     * @return Reference to the alarm's bit flags.
     */
	inline TBitFlags16& ClientFlags() { return iClientFlags; }

    /**
     * Returns this alarm's client flags.
     * 
     * @return Reference to the alarm's bit flags.
     */
	inline TBitFlags16 ClientFlags() const { return iClientFlags; }

    /**
     * Returns the client data from slot 1 for this alarm.
     * 
     * @return The first client-specific integer.
     */
	inline TInt	ClientData1() const { return iClientData1; }

    /**
     * Returns a writable version of the client data from slot 1 for this alarm.
     * 
     * @return Reference to the first client-specific integer.
     */
	inline TInt& ClientData1() { return iClientData1; }

    /**
     * Returns the client data from slot 2 for this alarm.
     * 
     * @return The second client-specific integer.
     */
	inline TInt ClientData2() const { return iClientData2; }

    /**
     * Returns the client data from slot 2 for this alarm.
     * 
     * @return The second client-specific integer.
     */
	inline TInt& ClientData2() { return iClientData2; }
		
	
    /**
     * Tests whether the alarm is floating.
     * 
     * Floating alarms expire at a given wall-clock time regardless of the 
     * current locale and whether any daylight saving time rules are in force.
     * 
     * @return True if the alarm is floating.
     */
	inline TBool IsFloating() const { return iCharacteristics.IsClear(EAlarmCharacteristicsIsFixed); }
	
protected:									
    // Internal Flags
    
#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
	/*
	 * @internalAll
	 */
	enum TASShdAlarmFlags
		{
		/**
		 * @publishedAll
		 */
		EASShdAlarmFlagsHasAssociatedData	= 0,

		/**
		 * @publishedAll
		 */
		EASShdAlarmFlagsHasOwningSession	= 1,

		/**
		 * @publishedAll
		 */
		EASShdAlarmFlagsHasBecomeOrphaned	= 2,
		
		/**
		 * Set if alarm is disabled manually so that can not be enabled when locale changes.
		 * 
		 * @publishedAll 
		 */
		EASShdAlarmFlagsPermanentDisabled	= 4
		};
#endif

private:
#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
    
#ifdef SYMBIAN_SYSTEM_STATE_MANAGEMENT
	/*
	 * @internalComponent
	 */
	enum TASShdAlarmFlags2
		{
		EASShdAlarmFlag2Wakeup = 0,
		};
#endif
	
#ifdef SYMBIAN_ALARM_REPEAT_EXTENSIONS
    /*
	 * @internalComponent
	 */
	enum TASShdAlarmFlags2AlarmRepeatExtensions
		{
		EASShdAlarmFlag2AlarmDayMonday		= 1,
		EASShdAlarmFlag2AlarmDayTuesday		= 2,
		EASShdAlarmFlag2AlarmDayWednesday	= 3,
		EASShdAlarmFlag2AlarmDayThursday	= 4,
		EASShdAlarmFlag2AlarmDayFriday		= 5,
		EASShdAlarmFlag2AlarmDaySaturday	= 6,
		EASShdAlarmFlag2AlarmDaySunday		= 7,
		EASShdAlarmFlag2Continuous			= 8
		};
#endif
	
#endif //SYMBIAN_ENABLE_SPLIT_HEADERS

		
protected:									

    /**
	 * Various flags - used internally by the alarm object
	 */
	TBitFlags8 iFlags;

	/**
	 * This represents the desired behaviour for a given alarm.
	 * The Alarm Server uses this information to control the
	 * behaviour of the alarm.
	 *
	 * @see TAlarmCharacteristics
	 */
	TAlarmCharacteristicsFlags iCharacteristics;

	/**
	 * The unique identifier assoicated with each alarm maintained
	 * by the alarm world server.
	 */
	TAlarmId iAlarmId;
	
	/**
	 * The status of this alarm (e.g. enabled, disabled)
	 */
	TAlarmStatus iStatus;

	/**
	 * The state of this alarm (e.g. queued, notifying, notified, snoozed etc)
	 */
	TAlarmState	iState;

	/**
	 * The type of this alarm (e.g. day, timed)
	 */
	TAlarmDayOrTimed iDayOrTimed;

	/**
	 * Controls how the alarm repeats after it has expired. Note that
	 * session alarms are not allowed to repeat (they must be "once
	 * only").
	 */
	TAlarmRepeatDefinition iRepeatDefinition;

	/**
	 * This UID is supplied by the client and is used to indicate
	 * the category that this alarm is part of. The Alarm Server
	 * is category-agnostic, that is, this information is for
	 * the client's use only
	 */
	TAlarmCategory iCategory;

	/**
	 * The date and time at which this alarm is next due. For alarms
	 * that haven't been snoozed, then this is the original due time.
	 *
	 * For alarms that have been snoozed, this is the time at which
	 * the alarm will reawaken.
	 */
	TTime iNextDueTime;

	/**
	 * This attribute is only used in the instance whereby an alarm
	 * is snoozed. It represents the time at which the alarm first 
	 * expired.
	 */
	TTime iOriginalExpiryTime;

	/**
	 * The message associated with this alarm, typically used
	 * in an application UI to inform the user as to the reason
	 * for the alarm.
	 */
	TAlarmMessage iMessage;

	/**
	 * A descriptor which holds the name of the sound file which
	 * should be played when the alarm expires.
	 */
	TAlarmSoundName iSoundName;

protected:									
    
    // Client Specific Data
    
	/**
	 * Flags for use by any particular client. These will
	 * only be relevant to a client who can interpret them.
	 */
	TBitFlags16 iClientFlags;

	/**
	 * For arbitrary client data 1
	 */
	TInt iClientData1;

	/**
	 * For arbitrary client data 2
	 */
	TInt iClientData2;

private:									
    // Binary Compatibility Proofing 
	TSecureId iTASShdAlarmSID;

#ifdef SYMBIAN_SYSTEM_STATE_MANAGEMENT
	/**
	 * Various flags - used internally by the alarm object
	 */
	TBitFlags16 iFlags2;
	TUint16 iTASShdAlarm_2;
#else
	
#ifdef SYMBIAN_ALARM_REPEAT_EXTENSIONS
	/**
	 * Various flags - used internally by the alarm object
	 */
	TBitFlags16 iFlags2;
	TUint16 iTASShdAlarm_2;
#else
	TAny* iTASShdAlarm_2;
#endif
#endif
	TAny* iTASShdAlarm_3;
	};

#endif // #ifndef __ASSHDALARM_H__