1 asshddefs.h |
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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #ifndef __ASSHDDEFS_H__ |
|
17 #define __ASSHDDEFS_H__ |
|
18 |
|
19 /** @file |
|
20 @publishedAll |
|
21 @released */ |
|
22 |
|
23 // System includes |
|
24 #include <e32std.h> |
|
25 #include <babitflags.h> |
|
26 |
|
27 // Constants |
|
28 |
|
29 /** Maximum length of an alarm message. The message is usually displayed by the |
|
30 alarm UI. */ |
|
31 const TInt KMaxAlarmMessageLength = 0x80; |
|
32 /** Maximum length of the filename of the sound played when an alarm expires. */ |
|
33 const TInt KMaxAlarmSoundNameLength = KMaxFileName; |
|
34 |
|
35 // Type definitions |
|
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; |
|
44 // |
|
45 /** Flags that define an alarm's characteristics. |
|
46 |
|
47 @see TAlarmCharacteristics */ |
|
48 typedef TBitFlags8 TAlarmCharacteristicsFlags; |
|
49 // |
|
50 |
|
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; |
|
55 |
|
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; |
|
60 // |
|
61 /** Defines a null alarm identifier. */ |
|
62 const TAlarmId KNullAlarmId = 0; |
|
63 // |
|
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; |
|
68 |
|
69 // Constants |
|
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 }; |
|
73 |
|
74 /** Defines whether an alarm is enabled or disabled: |
|
75 |
|
76 An enabled alarm activates at a specified time. |
|
77 |
|
78 A disabled alarm remains in the alarm server queue but is not active. |
|
79 |
|
80 You can get or set an alarm's status using the RASCliSession class. */ |
|
81 enum TAlarmStatus |
|
82 { |
|
83 /** The alarm is currently enabled. */ |
|
84 EAlarmStatusEnabled = 0, |
|
85 |
|
86 /** The alarm is currently disabled, and will not expire. */ |
|
87 EAlarmStatusDisabled, |
|
88 }; |
|
89 |
|
90 /** Represents an alarm's state. Alarms can have only one state. */ |
|
91 enum TAlarmState |
|
92 { |
|
93 /** The alarm state is not currently known by the alarm server. */ |
|
94 EAlarmStateInPreparation = -1, |
|
95 |
|
96 /** The alarm is waiting for its expiry time to be reached. */ |
|
97 EAlarmStateQueued = 0, |
|
98 |
|
99 /** The alarm is snoozed. When the snooze period is over, the alarm expires again. */ |
|
100 EAlarmStateSnoozed, |
|
101 |
|
102 /** The alarm is waiting to be notified. |
|
103 |
|
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, |
|
109 |
|
110 /** The alarm is currently notifying. */ |
|
111 EAlarmStateNotifying, |
|
112 |
|
113 /** The alarm has already notified and has been dismissed. Any alarm which remains |
|
114 in this state is dead. */ |
|
115 EAlarmStateNotified |
|
116 }; |
|
117 |
|
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 |
|
121 { |
|
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, |
|
127 |
|
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. */ |
|
130 EASShdAlarmTypeDay |
|
131 }; |
|
132 |
|
133 /** Defines the sound state of the global alarm server . */ |
|
134 enum TAlarmGlobalSoundState |
|
135 { |
|
136 /** When an alarm expires, the alarm sound is played. */ |
|
137 EAlarmGlobalSoundStateOn = 0, |
|
138 |
|
139 /** When an alarm expires, no sound plays. */ |
|
140 EAlarmGlobalSoundStateOff |
|
141 }; |
|
142 |
|
143 /** Defines how an alarm is to be repeated. */ |
|
144 enum TAlarmRepeatDefinition |
|
145 { |
|
146 /** The alarm expires only once, and is then deleted from the alarm server. By |
|
147 default, all alarms behave this way. |
|
148 |
|
149 Standard repeat-once alarms are date relative, that is, they occur on a fixed |
|
150 date and point in time. |
|
151 |
|
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: |
|
154 |
|
155 By less than 12 hours, the alarm expires immediately. |
|
156 |
|
157 By more than 12 horus, the alarm is silently discarded. |
|
158 |
|
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, |
|
163 |
|
164 /** When initially scheduling the alarm, the date is always within the |
|
165 next 24 hours. For example: |
|
166 |
|
167 The current time is 15:00, and the alarm time specified is 14:00. The |
|
168 alarm expires tomorrow at 14:00. |
|
169 |
|
170 The current time is 15:00, and the alarm time specified is 16:00. The |
|
171 alarm expires today at 16:00. |
|
172 |
|
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". |
|
175 |
|
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: |
|
178 |
|
179 By less than 12 hours, the alarm expires immediately. |
|
180 |
|
181 By more than 12 horus, the alarm is silently discarded. |
|
182 |
|
183 If the user changes the system date or time so that the new time is |
|
184 before the next calculated expiry time: |
|
185 |
|
186 By less than 12 hours, no change in alarm type, and the alarm |
|
187 remains queued. |
|
188 |
|
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 |
|
192 characteristic. */ |
|
193 EAlarmRepeatDefintionRepeatNext24Hours, |
|
194 |
|
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 |
|
198 time. |
|
199 |
|
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, |
|
203 |
|
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 |
|
207 available time. |
|
208 |
|
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, |
|
212 |
|
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 |
|
216 next available time. |
|
217 |
|
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, |
|
221 |
|
222 /** The alarm repeats every specified day at the same time. If the user |
|
223 changes the system date or time, this alarm behaves in the same way as a |
|
224 "repeat once" alarm, except that the alarm is not deleted, but rescheduled |
|
225 for the next available time. |
|
226 |
|
227 If the user changes the system date or time to a point in the past, there |
|
228 are no phantom alarm expiries.*/ |
|
229 EAlarmRepeatDefinitionRepeatDailyOnGivenDays |
|
230 }; |
|
231 |
|
232 /** Defines various alarm characteristics. */ |
|
233 enum TAlarmCharacteristics |
|
234 { |
|
235 /** Sets an alarm to be session-only. This alarm only exists as long as a session |
|
236 is maintained with the alarm server. Session alarms are removed from the alarm |
|
237 queue when the originating session disconnects from the server. By default, |
|
238 all alarms are persistent and remain so, even after the initiating session |
|
239 has disconnected. */ |
|
240 EAlarmCharacteristicsSessionSpecific = 0, |
|
241 |
|
242 /** Do not display a screen. By default, all alarms result in a suitable screen |
|
243 being displayed, depending on the device. Use this flag to disable this default |
|
244 behaviour. */ |
|
245 EAlarmCharacteristicsDoNotNotifyAlarmAlertServer = 1, |
|
246 |
|
247 /** Sets an alarm to be floating - floating alarms expire at the current local time, |
|
248 regardless of the current locale or DST rules.*/ |
|
249 EAlarmCharacteristicsIsFixed = 2, |
|
250 |
|
251 /** Do not notify if its due time is in the past.*/ |
|
252 EAlarmCharacteristicsDeQueueIfDueTimeInPast = 3, |
|
253 // |
|
254 EAlarmCharacteristicsLast |
|
255 }; |
|
256 |
|
257 /** This enumeration defines the events that can be reported by the alarm server. |
|
258 |
|
259 These events are channelled to the client using the RASCliSession::NotifyChange() |
|
260 method. |
|
261 |
|
262 @see TAlarmState */ |
|
263 enum TAlarmChangeEvent |
|
264 { |
|
265 /** An alarm has changed state. |
|
266 |
|
267 @see TAlarmState */ |
|
268 EAlarmChangeEventState = 1, |
|
269 |
|
270 /** An alarm has changed status. |
|
271 |
|
272 @see TAlarmStatus */ |
|
273 EAlarmChangeEventStatus = 2, |
|
274 |
|
275 /** An alarm has changed characteristics. |
|
276 |
|
277 @see TAlarmCharacteristics */ |
|
278 EAlarmChangeEventCharacteristics = 3, |
|
279 |
|
280 /** An alarm has been deleted from the queue of alarms. */ |
|
281 EAlarmChangeEventAlarmDeletion = 4, |
|
282 |
|
283 /** An alarm has been added to the queue of alarms. */ |
|
284 EAlarmChangeEventAlarmAddition = 5, |
|
285 |
|
286 /** An alarm has expired. */ |
|
287 EAlarmChangeEventTimerExpired = 6, |
|
288 |
|
289 /** The sound for an alarm has just started playing. */ |
|
290 EAlarmChangeEventSoundPlaying = 7, |
|
291 |
|
292 /** The sound for an alarm has just stopped playing. */ |
|
293 EAlarmChangeEventSoundStopped = 8, |
|
294 |
|
295 /** The sound intervals associated with sound timing have changed. */ |
|
296 EAlarmChangeEventPlayIntervalsChanged = 9, |
|
297 |
|
298 /** The global sound state (on/off) has changed. */ |
|
299 EAlarmChangeEventGlobalSoundStateChanged = 10, |
|
300 |
|
301 /** The next alarm at the head of the alarm queue has changed. */ |
|
302 EAlarmChangeEventHeadQueueItemChanged = 11, |
|
303 |
|
304 /** The system date or time has changed, or the days defined as workdays have changed. */ |
|
305 EAlarmChangeEventSystemDateTimeChanged = 12, |
|
306 |
|
307 /** The alarm alert server has been instructed to show the 'alarm expired' display. */ |
|
308 EAlarmChangeEventAlarmUIVisible = 13, |
|
309 |
|
310 /** The alarm alert server has been instructed to hide the 'alarm expired' display. */ |
|
311 EAlarmChangeEventAlarmUIInvisible = 14, |
|
312 |
|
313 /** Alarm sounds have been temporarily silenced, the current alarm has been paused |
|
314 or re-enabled. */ |
|
315 EAlarmChangeEventSoundSilence = 15, |
|
316 |
|
317 /** The data associated with an alarm has changed. */ |
|
318 EAlarmChangeEventAlarmData = 16, |
|
319 |
|
320 /** A restore from backup of the alarm server has started. Alarms cannot be added/deleted |
|
321 until this has finished. */ |
|
322 EAlarmChangeEventRestoreStarted = 17, |
|
323 |
|
324 /** A restore from backup of the alarm server has failed. Alarms can be added/deleted again. */ |
|
325 EAlarmChangeEventRestoreFailed = 18, |
|
326 |
|
327 /** A restore from backup of the alarm server has completed. The alarm queue has changed. */ |
|
328 EAlarmChangeEventRestoreCompleted = 19, |
|
329 |
|
330 /** Last change event (anchor). This is always at the end of the list. */ |
|
331 EAlarmChangeEventLast, |
|
332 |
|
333 /** An undefined alarm event has occurred. */ |
|
334 EAlarmChangeEventUndefined = 0 |
|
335 }; |
|
336 |
|
337 /** Identifies server-initiated panics relating to the client session. */ |
|
338 enum TAlarmServerInitiatedClientPanic |
|
339 { |
|
340 /** This panic occurs when the client requests a copy of any data attached to an |
|
341 alarm, but does not supply enough buffer space to contain the data. */ |
|
342 EAlarmServerInitiatedClientPanicInsufficientRoomForAlarmData = 0, |
|
343 |
|
344 /** This panic usually occurs when a client method tries to write to a descriptor |
|
345 (sometimes asynchronously), and the client-supplied descriptor is not valid. */ |
|
346 EAlarmServerInitiatedClientPanicBadDescriptor = 1, |
|
347 |
|
348 /** This panic occurs when a client already has an outstanding notification request, |
|
349 but attempts to request another. */ |
|
350 EAlarmServerInitiatedClientPanicChangeNotificationAlreadyOutstanding = 2, |
|
351 |
|
352 /** This panic occurs when a client tries to perform an invalid operation. */ |
|
353 EAlarmServerInitiatedClientPanicInvalidOperation = 3, |
|
354 |
|
355 /** This panic occurs when a request to add an alarm contains a null alarm identiifer. |
|
356 In the case of alarms with notifications, the client should pre-allocate the |
|
357 alarm identifier before requesting the notification. */ |
|
358 EAlarmServerInitiatedClientPanicBadPreAllocatedAlarmId = 4 |
|
359 |
|
360 }; |
|
361 |
|
362 /** Identifies what kind of alarms the client wants to delete. */ |
|
363 enum TDeleteTypeEnum |
|
364 { |
|
365 /** All type of alarms. */ |
|
366 EAllAlarms = 0, |
|
367 /** Alarms future of the current time */ |
|
368 EFuture = 1, |
|
369 /** Alarms in the past of the current time but notifying, or waiting to notify, or snoozed by, the user */ |
|
370 EActive = 2, |
|
371 /** alarms that has been dismissed by the user */ |
|
372 EExpired = 4 |
|
373 }; |
|
374 |
|
375 /** |
|
376 This enumeration indicates which days of the week an alarm with a repeat |
|
377 definition of EAlarmRepeatDefinitionRepeatDailyOnGivenDays activates on. Days |
|
378 are combined using the bitwise OR operator. |
|
379 |
|
380 @prototype |
|
381 */ |
|
382 enum TAlarmDays |
|
383 { |
|
384 /** Alarm is active on Monday. */ |
|
385 EAlarmDayMonday = 0x01, |
|
386 /** Alarm is active on Tuesday. */ |
|
387 EAlarmDayTuesday = 0x02, |
|
388 /** Alarm is active on Wednesday. */ |
|
389 EAlarmDayWednesday = 0x04, |
|
390 /** Alarm is active on Thursday. */ |
|
391 EAlarmDayThursday = 0x08, |
|
392 /** Alarm is active on Friday. */ |
|
393 EAlarmDayFriday = 0x10, |
|
394 /** Alarm is active on Saturday. */ |
|
395 EAlarmDaySaturday = 0x20, |
|
396 /** Alarm is active on Sunday. */ |
|
397 EAlarmDaySunday = 0x40 |
|
398 }; |
|
399 |
|
400 /** Identifies the type of alarm which was missed. A UTC offset change will only |
|
401 affect floating alarms whereas a system time change may affect either floating |
|
402 or fixed alarms. |
|
403 @see TASShdAlarmedInstanceParams |
|
404 @see CASSrvAlarmQueue::MEnvChangeHandleEvent |
|
405 */ |
|
406 enum TASShdAlarmTimeType |
|
407 { |
|
408 /** Floating time alarm. */ |
|
409 EFloating, |
|
410 /** Floating or fixed time alarm. */ |
|
411 EFloatingOrFixed |
|
412 }; |
|
413 |
|
414 #endif |