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@2: // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members williamr@2: // which accompanies this distribution, and is available williamr@2: // at the URL "http://www.symbianfoundation.org/legal/licencesv10.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 williamr@2: #include 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 TAlarmMessage; williamr@2: /** Stores the name of a sound file which is played when an alarm activates. */ williamr@2: typedef TBuf 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@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@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@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@2: 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@2: williamr@2: #endif