// 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__