1 // Copyright (c) 1999-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // under the terms of "Eclipse Public License v1.0"
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
16 #ifndef __ASSHDDEFS_H__
17 #define __ASSHDDEFS_H__
25 #include <babitflags.h>
29 /** Maximum length of an alarm message. The message is usually displayed by the
31 const TInt KMaxAlarmMessageLength = 0x80;
32 /** Maximum length of the filename of the sound played when an alarm expires. */
33 const TInt KMaxAlarmSoundNameLength = KMaxFileName;
36 /** A unique identifier allocated to each new alarm by the alarm server, so that
37 the client can identify them. By default, KNullAlarmId. */
38 typedef TInt TAlarmId;
39 /** A unique identifier that can optionally be used by clients to group
40 alarms into categories, for instance alarms associated with a particular application
41 or application engine. The alarm server ignores the category. It is relevant
42 to the client alone. */
43 typedef TUid TAlarmCategory;
45 /** Flags that define an alarm's characteristics.
47 @see TAlarmCharacteristics */
48 typedef TBitFlags8 TAlarmCharacteristicsFlags;
51 /** A type to identify what kind of alarms should be deleted when using the API
52 RASCliSession::AlarmDeleteByCategory()
53 @see TTDeleteTypeEnum */
54 typedef TInt TDeleteType;
56 /** Stores the text message associated with an alarm. */
57 typedef TBuf<KMaxAlarmMessageLength> TAlarmMessage;
58 /** Stores the name of a sound file which is played when an alarm activates. */
59 typedef TBuf<KMaxAlarmSoundNameLength> TAlarmSoundName;
61 /** Defines a null alarm identifier. */
62 const TAlarmId KNullAlarmId = 0;
64 /** Defines the length in seconds of an alarm sound offset. */
65 const TInt KDefaultSoundPlayOffsetInSeconds = 0;
66 /** Defines the length in seconds of an alarm sound duration. */
67 const TInt KDefaultSoundPlayDurationInSeconds = 30;
70 /** A category that can be assigned to identify clock alarms to the client. The
71 server does not distinguish between alarm types. */
72 const TAlarmCategory KASCliCategoryClock = { 0x101F5030 };
74 /** Defines whether an alarm is enabled or disabled:
76 An enabled alarm activates at a specified time.
78 A disabled alarm remains in the alarm server queue but is not active.
80 You can get or set an alarm's status using the RASCliSession class. */
83 /** The alarm is currently enabled. */
84 EAlarmStatusEnabled = 0,
86 /** The alarm is currently disabled, and will not expire. */
90 /** Represents an alarm's state. Alarms can have only one state. */
93 /** The alarm state is not currently known by the alarm server. */
94 EAlarmStateInPreparation = -1,
96 /** The alarm is waiting for its expiry time to be reached. */
97 EAlarmStateQueued = 0,
99 /** The alarm is snoozed. When the snooze period is over, the alarm expires again. */
102 /** The alarm is waiting to be notified.
104 This state occurs when an alarm expires while another is being notified. When
105 this happens, the alarm being notified changes state to EAlarmStateWaitingToNotify.
106 This means that if it is set to be the next alarm to be notified, notification
107 will happen after the newly expired alarm has been notified and dismissed. */
108 EAlarmStateWaitingToNotify,
110 /** The alarm is currently notifying. */
111 EAlarmStateNotifying,
113 /** The alarm has already notified and has been dismissed. Any alarm which remains
114 in this state is dead. */
118 /** Defines an alarm session type as timed or untimed. This property is ignored by
119 the alarm server, and is for use by the client only. */
120 enum TAlarmDayOrTimed
122 /** Timed alarm type (default). This alarm belongs to a timed event. This is an event
123 with a defined start and finish time. The alarm notification
124 time is specified as an offset from the event's start time, so that when the
125 event time changes, so does the alarm time. */
126 EASShdAlarmTypeTimed = 0,
128 /** Day alarm type. This alarm belongs to untimed events; these do not have
129 a defined start and finish time, but have an activation time. */
133 /** Defines the sound state of the global alarm server . */
134 enum TAlarmGlobalSoundState
136 /** When an alarm expires, the alarm sound is played. */
137 EAlarmGlobalSoundStateOn = 0,
139 /** When an alarm expires, no sound plays. */
140 EAlarmGlobalSoundStateOff
143 /** Defines how an alarm is to be repeated. */
144 enum TAlarmRepeatDefinition
146 /** The alarm expires only once, and is then deleted from the alarm server. By
147 default, all alarms behave this way.
149 Standard repeat-once alarms are date relative, that is, they occur on a fixed
150 date and point in time.
152 If the user changes the system date or time so that the new time is in the
153 future, and the new time is after the previously calculated expiry time:
155 By less than 12 hours, the alarm expires immediately.
157 By more than 12 horus, the alarm is silently discarded.
159 If the user changes the system date or time so that the new time is before
160 the next calculated expiry time, the alarm type continues to be a
161 "Repeat once" alarm*/
162 EAlarmRepeatDefintionRepeatOnce = 0,
164 /** When initially scheduling the alarm, the date is always within the
165 next 24 hours. For example:
167 The current time is 15:00, and the alarm time specified is 14:00. The
168 alarm expires tomorrow at 14:00.
170 The current time is 15:00, and the alarm time specified is 16:00. The
171 alarm expires today at 16:00.
173 If the alarm is missed, i.e. because the alarm server is inactive, then
174 the alarm changes its type from "Repeat in the next 24 Hours" to "Repeat once".
176 If the user changes the system date or time so that the new time is in the
177 future, and the new time is after the previously calculated expiry time:
179 By less than 12 hours, the alarm expires immediately.
181 By more than 12 horus, the alarm is silently discarded.
183 If the user changes the system date or time so that the new time is
184 before the next calculated expiry time:
186 By less than 12 hours, no change in alarm type, and the alarm
189 By greater than 12 hours, the alarm changes its type from
190 "Repeat in the next 24 Hours" to "Repeat once". Subsequent changes in system
191 time result in the behaviour described by the EAlarmRepeatDefintionRepeatOnce
193 EAlarmRepeatDefintionRepeatNext24Hours,
195 /** The alarm repeats every day at the same time. If the user changes the system
196 date or time, this alarm behaves in the same way as a "Repeat once" alarm,
197 except that the alarm is not deleted, but rescheduled for the next available
200 If the user changes the system date or time to a point in the past, there
201 are no phantom alarm expiries. */
202 EAlarmRepeatDefintionRepeatDaily,
204 /** The alarm repeats every work day at the same time. If the user changes the
205 system date or time, this alarm behaves in the same way as a "Repeat once"
206 alarm, except that the alarm is not deleted, but rescheduled for the next
209 If the user changes the system date or time to a point in the past, there
210 are no phantom alarm expiries. */
211 EAlarmRepeatDefintionRepeatWorkday,
213 /** The alarm repeats every week, on the same day at the same time. If the user
214 changes the system date or time, this alarm behaves in the same way as a "Repeat
215 once" alarm, except that the alarm is not deleted, but rescheduled for the
218 If the user changes the system date or time to a point in the past, there
219 are no phantom alarm expiries. */
220 EAlarmRepeatDefintionRepeatWeekly,
222 #ifdef SYMBIAN_ALARM_REPEAT_EXTENSIONS
223 /** The alarm repeats every specified day at the same time. If the user
224 changes the system date or time, this alarm behaves in the same way as a
225 "repeat once" alarm, except that the alarm is not deleted, but rescheduled
226 for the next available time.
228 If the user changes the system date or time to a point in the past, there
229 are no phantom alarm expiries.*/
230 EAlarmRepeatDefinitionRepeatDailyOnGivenDays
234 /** Defines various alarm characteristics. */
235 enum TAlarmCharacteristics
237 /** Sets an alarm to be session-only. This alarm only exists as long as a session
238 is maintained with the alarm server. Session alarms are removed from the alarm
239 queue when the originating session disconnects from the server. By default,
240 all alarms are persistent and remain so, even after the initiating session
242 EAlarmCharacteristicsSessionSpecific = 0,
244 /** Do not display a screen. By default, all alarms result in a suitable screen
245 being displayed, depending on the device. Use this flag to disable this default
247 EAlarmCharacteristicsDoNotNotifyAlarmAlertServer = 1,
249 /** Sets an alarm to be floating - floating alarms expire at the current local time,
250 regardless of the current locale or DST rules.*/
251 EAlarmCharacteristicsIsFixed = 2,
253 /** Do not notify if its due time is in the past.*/
254 EAlarmCharacteristicsDeQueueIfDueTimeInPast = 3,
256 EAlarmCharacteristicsLast
259 /** This enumeration defines the events that can be reported by the alarm server.
261 These events are channelled to the client using the RASCliSession::NotifyChange()
265 enum TAlarmChangeEvent
267 /** An alarm has changed state.
270 EAlarmChangeEventState = 1,
272 /** An alarm has changed status.
275 EAlarmChangeEventStatus = 2,
277 /** An alarm has changed characteristics.
279 @see TAlarmCharacteristics */
280 EAlarmChangeEventCharacteristics = 3,
282 /** An alarm has been deleted from the queue of alarms. */
283 EAlarmChangeEventAlarmDeletion = 4,
285 /** An alarm has been added to the queue of alarms. */
286 EAlarmChangeEventAlarmAddition = 5,
288 /** An alarm has expired. */
289 EAlarmChangeEventTimerExpired = 6,
291 /** The sound for an alarm has just started playing. */
292 EAlarmChangeEventSoundPlaying = 7,
294 /** The sound for an alarm has just stopped playing. */
295 EAlarmChangeEventSoundStopped = 8,
297 /** The sound intervals associated with sound timing have changed. */
298 EAlarmChangeEventPlayIntervalsChanged = 9,
300 /** The global sound state (on/off) has changed. */
301 EAlarmChangeEventGlobalSoundStateChanged = 10,
303 /** The next alarm at the head of the alarm queue has changed. */
304 EAlarmChangeEventHeadQueueItemChanged = 11,
306 /** The system date or time has changed, or the days defined as workdays have changed. */
307 EAlarmChangeEventSystemDateTimeChanged = 12,
309 /** The alarm alert server has been instructed to show the 'alarm expired' display. */
310 EAlarmChangeEventAlarmUIVisible = 13,
312 /** The alarm alert server has been instructed to hide the 'alarm expired' display. */
313 EAlarmChangeEventAlarmUIInvisible = 14,
315 /** Alarm sounds have been temporarily silenced, the current alarm has been paused
317 EAlarmChangeEventSoundSilence = 15,
319 /** The data associated with an alarm has changed. */
320 EAlarmChangeEventAlarmData = 16,
322 /** A restore from backup of the alarm server has started. Alarms cannot be added/deleted
323 until this has finished. */
324 EAlarmChangeEventRestoreStarted = 17,
326 /** A restore from backup of the alarm server has failed. Alarms can be added/deleted again. */
327 EAlarmChangeEventRestoreFailed = 18,
329 /** A restore from backup of the alarm server has completed. The alarm queue has changed. */
330 EAlarmChangeEventRestoreCompleted = 19,
332 /** Last change event (anchor). This is always at the end of the list. */
333 EAlarmChangeEventLast,
335 /** An undefined alarm event has occurred. */
336 EAlarmChangeEventUndefined = 0
339 /** Identifies server-initiated panics relating to the client session. */
340 enum TAlarmServerInitiatedClientPanic
342 /** This panic occurs when the client requests a copy of any data attached to an
343 alarm, but does not supply enough buffer space to contain the data. */
344 EAlarmServerInitiatedClientPanicInsufficientRoomForAlarmData = 0,
346 /** This panic usually occurs when a client method tries to write to a descriptor
347 (sometimes asynchronously), and the client-supplied descriptor is not valid. */
348 EAlarmServerInitiatedClientPanicBadDescriptor = 1,
350 /** This panic occurs when a client already has an outstanding notification request,
351 but attempts to request another. */
352 EAlarmServerInitiatedClientPanicChangeNotificationAlreadyOutstanding = 2,
354 /** This panic occurs when a client tries to perform an invalid operation. */
355 EAlarmServerInitiatedClientPanicInvalidOperation = 3,
357 /** This panic occurs when a request to add an alarm contains a null alarm identiifer.
358 In the case of alarms with notifications, the client should pre-allocate the
359 alarm identifier before requesting the notification. */
360 EAlarmServerInitiatedClientPanicBadPreAllocatedAlarmId = 4
364 /** Identifies what kind of alarms the client wants to delete. */
367 /** All type of alarms. */
369 /** Alarms future of the current time */
371 /** Alarms in the past of the current time but notifying, or waiting to notify, or snoozed by, the user */
373 /** alarms that has been dismissed by the user */
377 #ifdef SYMBIAN_ALARM_REPEAT_EXTENSIONS
379 This enumeration indicates which days of the week an alarm with a repeat
380 definition of EAlarmRepeatDefinitionRepeatDailyOnGivenDays activates on. Days
381 are combined using the bitwise OR operator.
387 /** Alarm is active on Monday. */
388 EAlarmDayMonday = 0x01,
389 /** Alarm is active on Tuesday. */
390 EAlarmDayTuesday = 0x02,
391 /** Alarm is active on Wednesday. */
392 EAlarmDayWednesday = 0x04,
393 /** Alarm is active on Thursday. */
394 EAlarmDayThursday = 0x08,
395 /** Alarm is active on Friday. */
396 EAlarmDayFriday = 0x10,
397 /** Alarm is active on Saturday. */
398 EAlarmDaySaturday = 0x20,
399 /** Alarm is active on Sunday. */
400 EAlarmDaySunday = 0x40
404 #ifdef SYMBIAN_SKIPPED_CALENDAR_ALARMS
405 /** Identifies the type of alarm which was missed. A UTC offset change will only
406 affect floating alarms whereas a system time change may affect either floating
408 @see TASShdAlarmedInstanceParams
409 @see CASSrvAlarmQueue::MEnvChangeHandleEvent
411 enum TASShdAlarmTimeType
413 /** Floating time alarm. */
415 /** Floating or fixed time alarm. */