williamr@2: // Copyright (c) 1999-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: // All rights reserved.
williamr@2: // This component and the accompanying materials are made available
williamr@4: // under the terms of "Eclipse Public License v1.0"
williamr@2: // which accompanies this distribution, and is available
williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: //
williamr@2: // Initial Contributors:
williamr@2: // Nokia Corporation - initial contribution.
williamr@2: //
williamr@2: // Contributors:
williamr@2: //
williamr@2: // Description:
williamr@2: //
williamr@2: 
williamr@2: #ifndef __ASSHDDEFS_H__
williamr@2: #define __ASSHDDEFS_H__
williamr@2: 
williamr@2: /** @file
williamr@2: @publishedAll
williamr@2: @released */
williamr@2: 
williamr@2: // System includes
williamr@2: #include <e32std.h>
williamr@2: #include <babitflags.h>
williamr@2: 
williamr@2: // Constants
williamr@2: 
williamr@2: /** Maximum length of an alarm message. The message is usually displayed by the 
williamr@2: alarm UI. */
williamr@2: const TInt KMaxAlarmMessageLength = 0x80;
williamr@2: /** Maximum length of the filename of the sound played when an alarm expires. */
williamr@2: const TInt KMaxAlarmSoundNameLength = KMaxFileName;
williamr@2: 
williamr@2: // Type definitions
williamr@2: /** A unique identifier allocated to each new alarm by the alarm server, so that 
williamr@2: the client can identify them. By default, KNullAlarmId. */
williamr@2: typedef TInt TAlarmId;
williamr@2: /** A unique identifier that can optionally be used by clients to group 
williamr@2: alarms into categories, for instance alarms associated with a particular application 
williamr@2: or application engine. The alarm server ignores the category. It is relevant 
williamr@2: to the client alone. */
williamr@2: typedef TUid TAlarmCategory;
williamr@2: //
williamr@2: /** Flags that define an alarm's characteristics.
williamr@2: 
williamr@2: @see TAlarmCharacteristics */
williamr@2: typedef TBitFlags8 TAlarmCharacteristicsFlags;
williamr@2: //
williamr@2: 
williamr@2: /** A type to identify what kind of alarms should be deleted when using the API
williamr@2: RASCliSession::AlarmDeleteByCategory()
williamr@2: @see TTDeleteTypeEnum */
williamr@2: typedef TInt TDeleteType;
williamr@2:  
williamr@2: /** Stores the text message associated with an alarm. */
williamr@2: typedef TBuf<KMaxAlarmMessageLength> TAlarmMessage;
williamr@2: /** Stores the name of a sound file which is played when an alarm activates. */
williamr@2: typedef TBuf<KMaxAlarmSoundNameLength> TAlarmSoundName;
williamr@2: //
williamr@2: /** Defines a null alarm identifier. */
williamr@2: const TAlarmId KNullAlarmId	= 0;
williamr@2: //
williamr@2: /** Defines the length in seconds of an alarm sound offset. */
williamr@2: const TInt KDefaultSoundPlayOffsetInSeconds	= 0;
williamr@2: /** Defines the length in seconds of an alarm sound duration. */
williamr@2: const TInt KDefaultSoundPlayDurationInSeconds = 30;
williamr@2: 
williamr@2: // Constants
williamr@2: /** A category that can be assigned to identify clock alarms to the client. The 
williamr@2: server does not distinguish between alarm types. */
williamr@2: const TAlarmCategory KASCliCategoryClock		= { 0x101F5030 };
williamr@2: 
williamr@2: /** Defines whether an alarm is enabled or disabled: 
williamr@2: 
williamr@2: An enabled alarm activates at a specified time. 
williamr@2: 
williamr@2: A disabled alarm remains in the alarm server queue but is not active. 
williamr@2: 
williamr@2: You can get or set an alarm's status using the RASCliSession class. */
williamr@2: enum TAlarmStatus
williamr@2: 	{
williamr@2: 	/** The alarm is currently enabled. */
williamr@2: 	EAlarmStatusEnabled = 0,
williamr@2: 
williamr@2: 	/** The alarm is currently disabled, and will not expire. */
williamr@2: 	EAlarmStatusDisabled,
williamr@2: 	};
williamr@2: 
williamr@2: /** Represents an alarm's state. Alarms can have only one state. */
williamr@2: enum TAlarmState
williamr@2: 	{
williamr@2: 	/** The alarm state is not currently known by the alarm server. */
williamr@2: 	EAlarmStateInPreparation = -1,
williamr@2: 
williamr@2: 	/** The alarm is waiting for its expiry time to be reached. */
williamr@2: 	EAlarmStateQueued = 0,
williamr@2: 
williamr@2: 	/** The alarm is snoozed. When the snooze period is over, the alarm expires again. */
williamr@2: 	EAlarmStateSnoozed,
williamr@2: 
williamr@2: 	/** The alarm is waiting to be notified. 
williamr@2: 	
williamr@2: 	This state occurs when an alarm expires while another is being notified. When 
williamr@2: 	this happens, the alarm being notified changes state to EAlarmStateWaitingToNotify. 
williamr@2: 	This means that if it is set to be the next alarm to be notified, notification 
williamr@2: 	will happen after the newly expired alarm has been notified and dismissed. */
williamr@2: 	EAlarmStateWaitingToNotify,
williamr@2: 
williamr@2: 	/** The alarm is currently notifying. */
williamr@2: 	EAlarmStateNotifying,
williamr@2: 
williamr@2: 	/** The alarm has already notified and has been dismissed. Any alarm which remains 
williamr@2: 	in this state is dead. */
williamr@2: 	EAlarmStateNotified
williamr@2: 	};
williamr@2: 
williamr@2: /** Defines an alarm session type as timed or untimed. This property is ignored by 
williamr@2: the alarm server, and is for use by the client only. */
williamr@2: enum TAlarmDayOrTimed
williamr@2: 	{
williamr@2: 	/** Timed alarm type (default). This alarm belongs to a timed event. This is an event 
williamr@2: 	with a defined start and finish time. The alarm notification 
williamr@2: 	time is specified as an offset from the event's start time, so that when the 
williamr@2: 	event time changes, so does the alarm time. */
williamr@2: 	EASShdAlarmTypeTimed = 0,
williamr@2: 
williamr@2: 	/** Day alarm type. This alarm belongs to untimed events; these do not have 
williamr@2: 	a defined start and finish time, but have an activation time. */
williamr@2: 	EASShdAlarmTypeDay
williamr@2: 	};
williamr@2: 
williamr@2: /** Defines the sound state of the global alarm server . */
williamr@2: enum TAlarmGlobalSoundState
williamr@2: 	{
williamr@2: 	/** When an alarm expires, the alarm sound is played. */
williamr@2: 	EAlarmGlobalSoundStateOn = 0,
williamr@2: 
williamr@2: 	/** When an alarm expires, no sound plays. */
williamr@2: 	EAlarmGlobalSoundStateOff
williamr@2: 	};
williamr@2: 
williamr@2: /** Defines how an alarm is to be repeated. */
williamr@2: enum TAlarmRepeatDefinition
williamr@2: 	{
williamr@2: 	/** The alarm expires only once, and is then deleted from the alarm server. By 
williamr@2: 	default, all alarms behave this way. 
williamr@2: 	
williamr@2: 	Standard repeat-once alarms are date relative, that is, they occur on a fixed 
williamr@2: 	date and point in time. 
williamr@2: 	
williamr@2: 	If the user changes the system date or time so that the new time is in the 
williamr@2: 	future, and the new time is after the previously calculated expiry time:
williamr@2: 	
williamr@2: 	By less than 12 hours, the alarm expires immediately. 
williamr@2: 	
williamr@2: 	By more than 12 horus, the alarm is silently discarded. 
williamr@2: 	
williamr@2: 	If the user changes the system date or time so that the new time is before 
williamr@2: 	the next calculated expiry time, the alarm type continues to be a
williamr@2: 	"Repeat once" alarm*/
williamr@2: 	EAlarmRepeatDefintionRepeatOnce	= 0,
williamr@2: 
williamr@2: 	/** When initially scheduling the alarm, the date is always within the 
williamr@2: 	next 24 hours. For example:
williamr@2: 	
williamr@2: 	The current time is 15:00, and the alarm time specified is 14:00. The 
williamr@2: 	alarm expires tomorrow at 14:00. 
williamr@2: 	
williamr@2: 	The current time is 15:00, and the alarm time specified is 16:00. The 
williamr@2: 	alarm expires today at 16:00. 
williamr@2: 	
williamr@2: 	If the alarm is missed, i.e. because the alarm server is inactive, then 
williamr@2: 	the alarm changes its type from "Repeat in the next 24 Hours" to "Repeat once".
williamr@2: 	
williamr@2: 	If the user changes the system date or time so that the new time is in the 
williamr@2: 	future, and the new time is after the previously calculated expiry time:
williamr@2: 	
williamr@2: 	By less than 12 hours, the alarm expires immediately. 
williamr@2: 	
williamr@2: 	By more than 12 horus, the alarm is silently discarded. 
williamr@2: 	
williamr@2: 	If the user changes the system date or time so that the new time is 
williamr@2: 	before the next calculated expiry time:
williamr@2: 
williamr@2: 	By less than 12 hours, no change in alarm type, and the alarm 
williamr@2: 	remains queued.
williamr@2: 
williamr@2: 	By greater than 12 hours, the alarm changes its type from 
williamr@2: 	"Repeat in the next 24 Hours" to "Repeat once".	Subsequent changes in system 
williamr@2: 	time result in the behaviour described by the EAlarmRepeatDefintionRepeatOnce 
williamr@2: 	characteristic. */
williamr@2: 	EAlarmRepeatDefintionRepeatNext24Hours,
williamr@2: 
williamr@2: 	/** The alarm repeats every day at the same time. If the user changes the system 
williamr@2: 	date or time, this alarm behaves in the same way as a "Repeat once" alarm, 
williamr@2: 	except that the alarm is not deleted, but rescheduled for the next available 
williamr@2: 	time. 
williamr@2: 	
williamr@2: 	If the user changes the system date or time to a point in the past, there 
williamr@2: 	are no phantom alarm expiries. */
williamr@2: 	EAlarmRepeatDefintionRepeatDaily,
williamr@2: 
williamr@2: 	/** The alarm repeats every work day at the same time. If the user changes the 
williamr@2: 	system date or time, this alarm behaves in the same way as a "Repeat once" 
williamr@2: 	alarm, except that the alarm is not deleted, but rescheduled for the next 
williamr@2: 	available time. 
williamr@2: 	
williamr@2: 	If the user changes the system date or time to a point in the past, there 
williamr@2: 	are no phantom alarm expiries. */
williamr@2: 	EAlarmRepeatDefintionRepeatWorkday,
williamr@2: 
williamr@2: 	/** The alarm repeats every week, on the same day at the same time. If the user 
williamr@2: 	changes the system date or time, this alarm behaves in the same way as a "Repeat 
williamr@2: 	once" alarm, except that the alarm is not deleted, but rescheduled for the 
williamr@2: 	next available time.
williamr@2: 	
williamr@2: 	If the user changes the system date or time to a point in the past, there 
williamr@2: 	are no phantom alarm expiries. */
williamr@2: 	EAlarmRepeatDefintionRepeatWeekly,
williamr@2: 
williamr@4: #ifdef SYMBIAN_ALARM_REPEAT_EXTENSIONS
williamr@2: 	/** The alarm repeats every specified day at the same time. If the user
williamr@2: 	changes the system date or time, this alarm behaves in the same way as a
williamr@2: 	"repeat once" alarm, except that the alarm is not deleted, but rescheduled
williamr@2: 	for the next available time.
williamr@2: 	 
williamr@2:     If the user changes the system date or time to a point in the past, there
williamr@2:     are no phantom alarm expiries.*/ 
williamr@2: 	EAlarmRepeatDefinitionRepeatDailyOnGivenDays
williamr@4: #endif
williamr@2: 	};
williamr@2: 
williamr@2: /** Defines various alarm characteristics. */
williamr@2: enum TAlarmCharacteristics
williamr@2: 	{
williamr@2: 	/** Sets an alarm to be session-only. This alarm only exists as long as a session 
williamr@2: 	is maintained with the alarm server. Session alarms are removed from the alarm 
williamr@2: 	queue when the originating session disconnects from the server. By default, 
williamr@2: 	all alarms are persistent and remain so, even after the initiating session 
williamr@2: 	has disconnected. */
williamr@2: 	EAlarmCharacteristicsSessionSpecific = 0,
williamr@2: 
williamr@2: 	/** Do not display a screen. By default, all alarms result in a suitable screen 
williamr@2: 	being displayed, depending on the device. Use this flag to disable this default 
williamr@2: 	behaviour. */
williamr@2: 	EAlarmCharacteristicsDoNotNotifyAlarmAlertServer = 1,
williamr@2: 
williamr@2: 	/** Sets an alarm to be floating - floating alarms expire at the current local time,
williamr@2: 	regardless of the current locale or DST rules.*/
williamr@2: 	EAlarmCharacteristicsIsFixed = 2,
williamr@2: 	
williamr@2: 	/** Do not notify if its due time is in the past.*/
williamr@2: 	EAlarmCharacteristicsDeQueueIfDueTimeInPast = 3,
williamr@2: 	//
williamr@2: 	EAlarmCharacteristicsLast
williamr@2: 	};
williamr@2: 
williamr@2: /** This enumeration defines the events that can be reported by the alarm server. 
williamr@2: 
williamr@2: These events are channelled to the client using the RASCliSession::NotifyChange() 
williamr@2: method. 
williamr@2: 
williamr@2: @see TAlarmState */
williamr@2: enum TAlarmChangeEvent
williamr@2: 	{
williamr@2: 	/** An alarm has changed state. 
williamr@2: 	
williamr@2: 	@see TAlarmState */
williamr@2: 	EAlarmChangeEventState = 1,
williamr@2: 
williamr@2: 	/** An alarm has changed status. 
williamr@2: 	
williamr@2: 	@see TAlarmStatus */
williamr@2: 	EAlarmChangeEventStatus = 2,
williamr@2: 
williamr@2: 	/** An alarm has changed characteristics. 
williamr@2: 	
williamr@2: 	@see TAlarmCharacteristics */
williamr@2: 	EAlarmChangeEventCharacteristics = 3,
williamr@2: 
williamr@2: 	/** An alarm has been deleted from the queue of alarms. */
williamr@2: 	EAlarmChangeEventAlarmDeletion = 4,
williamr@2: 
williamr@2: 	/** An alarm has been added to the queue of alarms. */
williamr@2: 	EAlarmChangeEventAlarmAddition = 5,
williamr@2: 
williamr@2: 	/** An alarm has expired. */
williamr@2: 	EAlarmChangeEventTimerExpired = 6,
williamr@2: 
williamr@2: 	/** The sound for an alarm has just started playing. */
williamr@2: 	EAlarmChangeEventSoundPlaying = 7,
williamr@2: 
williamr@2: 	/** The sound for an alarm has just stopped playing. */
williamr@2: 	EAlarmChangeEventSoundStopped = 8,
williamr@2: 
williamr@2: 	/** The sound intervals associated with sound timing have changed. */
williamr@2: 	EAlarmChangeEventPlayIntervalsChanged = 9,
williamr@2: 
williamr@2: 	/** The global sound state (on/off) has changed. */
williamr@2: 	EAlarmChangeEventGlobalSoundStateChanged = 10,
williamr@2: 
williamr@2: 	/** The next alarm at the head of the alarm queue has changed. */
williamr@2: 	EAlarmChangeEventHeadQueueItemChanged = 11,
williamr@2: 
williamr@2: 	/** The system date or time has changed, or the days defined as workdays have changed. */
williamr@2: 	EAlarmChangeEventSystemDateTimeChanged = 12,
williamr@2: 
williamr@2: 	/** The alarm alert server has been instructed to show the 'alarm expired' display. */
williamr@2: 	EAlarmChangeEventAlarmUIVisible = 13,
williamr@2: 
williamr@2: 	/** The alarm alert server has been instructed to hide the 'alarm expired' display. */
williamr@2: 	EAlarmChangeEventAlarmUIInvisible = 14,
williamr@2: 
williamr@2: 	/** Alarm sounds have been temporarily silenced, the current alarm has been paused 
williamr@2: 	or re-enabled. */
williamr@2: 	EAlarmChangeEventSoundSilence = 15,
williamr@2: 
williamr@2: 	/** The data associated with an alarm has changed. */
williamr@2: 	EAlarmChangeEventAlarmData = 16,
williamr@2: 
williamr@2: 	/** A restore from backup of the alarm server has started. Alarms cannot be added/deleted 
williamr@2: 	until this has finished.  */
williamr@2: 	EAlarmChangeEventRestoreStarted = 17,
williamr@2: 
williamr@2: 	/** A restore from backup of the alarm server has failed. Alarms can be added/deleted again. */
williamr@2: 	EAlarmChangeEventRestoreFailed = 18,
williamr@2: 
williamr@2: 	/** A restore from backup of the alarm server has completed. The alarm queue has changed. */
williamr@2: 	EAlarmChangeEventRestoreCompleted = 19,
williamr@2: 
williamr@2: 	/** Last change event (anchor). This is always at the end of the list. */
williamr@2: 	EAlarmChangeEventLast,
williamr@2: 	
williamr@2: 	/** An undefined alarm event has occurred. */
williamr@2: 	EAlarmChangeEventUndefined = 0
williamr@2: 	};
williamr@2: 
williamr@2: /** Identifies server-initiated panics relating to the client session. */
williamr@2: enum TAlarmServerInitiatedClientPanic
williamr@2: 	{
williamr@2: 	/** This panic occurs when the client requests a copy of any data attached to an 
williamr@2: 	alarm, but does not supply enough buffer space to contain the data. */
williamr@2: 	EAlarmServerInitiatedClientPanicInsufficientRoomForAlarmData = 0,
williamr@2: 
williamr@2: 	/** This panic usually occurs when a client method tries to write to a descriptor 
williamr@2: 	(sometimes asynchronously), and the client-supplied descriptor is not valid. */
williamr@2: 	EAlarmServerInitiatedClientPanicBadDescriptor = 1,
williamr@2: 
williamr@2: 	/** This panic occurs when a client already has an outstanding notification request, 
williamr@2: 	but attempts to request another. */
williamr@2: 	EAlarmServerInitiatedClientPanicChangeNotificationAlreadyOutstanding = 2,
williamr@2: 
williamr@2: 	/** This panic occurs when a client tries to perform an invalid operation. */
williamr@2: 	EAlarmServerInitiatedClientPanicInvalidOperation = 3,
williamr@2: 
williamr@2: 	/** This panic occurs when a request to add an alarm contains a null alarm identiifer. 
williamr@2: 	In the case of alarms with notifications, the client should pre-allocate the 
williamr@2: 	alarm identifier before requesting the notification. */
williamr@2: 	EAlarmServerInitiatedClientPanicBadPreAllocatedAlarmId = 4
williamr@2: 
williamr@2: 	};
williamr@2: 
williamr@2: /** Identifies what kind of alarms the client wants to delete. */
williamr@2: enum TDeleteTypeEnum
williamr@2: 	{
williamr@2: 	/** All type of alarms. */
williamr@2: 	EAllAlarms = 0,
williamr@2: 	/** Alarms future of the current time */
williamr@2: 	EFuture = 1,
williamr@2: 	/** Alarms in the past of the current time but notifying, or waiting to notify, or snoozed by, the user  */
williamr@2: 	EActive = 2,
williamr@2: 	/** alarms that has been dismissed by the user  */
williamr@2: 	EExpired = 4
williamr@2: 	};
williamr@2: 
williamr@4: #ifdef SYMBIAN_ALARM_REPEAT_EXTENSIONS
williamr@2: /**
williamr@2: This enumeration indicates which days of the week an alarm with a repeat
williamr@2: definition of EAlarmRepeatDefinitionRepeatDailyOnGivenDays activates on.  Days
williamr@2: are combined using the bitwise OR operator.
williamr@2: 
williamr@2: @prototype
williamr@2: */
williamr@2: enum TAlarmDays
williamr@2:     {
williamr@2:     /** Alarm is active on Monday. */
williamr@2:     EAlarmDayMonday    = 0x01,
williamr@2:     /** Alarm is active on Tuesday. */
williamr@2:     EAlarmDayTuesday   = 0x02,
williamr@2:     /** Alarm is active on Wednesday. */
williamr@2:     EAlarmDayWednesday = 0x04,
williamr@2:     /** Alarm is active on Thursday. */
williamr@2:     EAlarmDayThursday  = 0x08,
williamr@2:     /** Alarm is active on Friday. */
williamr@2:     EAlarmDayFriday    = 0x10,
williamr@2:     /** Alarm is active on Saturday. */
williamr@2:     EAlarmDaySaturday  = 0x20,
williamr@2:     /** Alarm is active on Sunday. */
williamr@2:     EAlarmDaySunday    = 0x40
williamr@2:     };
williamr@4: #endif
williamr@2: 
williamr@4: #ifdef SYMBIAN_SKIPPED_CALENDAR_ALARMS
williamr@2: /** Identifies the type of alarm which was missed.  A UTC offset change will only
williamr@2: affect floating alarms whereas a system time change may affect either floating
williamr@2: or fixed alarms.
williamr@2: @see TASShdAlarmedInstanceParams
williamr@2: @see CASSrvAlarmQueue::MEnvChangeHandleEvent
williamr@2: */
williamr@2: enum TASShdAlarmTimeType
williamr@2: 	{
williamr@2: 	/** Floating time alarm. */
williamr@2: 	EFloating,
williamr@2: 	/** Floating or fixed time alarm. */
williamr@2: 	EFloatingOrFixed
williamr@2: 	};
williamr@4: #endif
williamr@2: 
williamr@2: #endif