|
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". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #ifndef __ASSHDALARM_H__ |
|
17 #define __ASSHDALARM_H__ |
|
18 |
|
19 |
|
20 // System Includes |
|
21 #include <e32base.h> |
|
22 #include <s32strm.h> |
|
23 |
|
24 // User Includes |
|
25 #include <asshddefs.h> |
|
26 |
|
27 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS |
|
28 |
|
29 /** |
|
30 * The Alarm publish and subscribe category |
|
31 * |
|
32 * @publishedPartner |
|
33 * @released |
|
34 */ |
|
35 const TUid KAlarmServerPubSubCategory = { 0x101f5027 }; |
|
36 |
|
37 /** |
|
38 * Used for subcribing missed alarms or time zone changes |
|
39 * @publishedPartner |
|
40 * @released |
|
41 */ |
|
42 const TUint KMissingAlarmPubSubKey = 100; |
|
43 |
|
44 /** |
|
45 * The publish and subscribe data for KMissingAlarmPubSubKey |
|
46 * @publishedPartner |
|
47 * @released |
|
48 */ |
|
49 struct TMissedAlarmPubSubData |
|
50 { |
|
51 /** |
|
52 * The value indicating the changes. |
|
53 * 1 - Time zone has been changes but there are no missed alarms |
|
54 * 2 - Some alarms have been missed after system time or time zone has changed. |
|
55 */ |
|
56 TUint8 iValue; |
|
57 |
|
58 /** |
|
59 * The time that system time change took place, in universal (UTC) time |
|
60 */ |
|
61 TTime iTimeOfChangeUtc; |
|
62 }; |
|
63 |
|
64 #ifdef SYMBIAN_SKIPPED_CALENDAR_ALARMS |
|
65 /** |
|
66 * Used for subscribing to data used when searching for instances in Calendar |
|
67 * @publishedPartner |
|
68 * @released |
|
69 */ |
|
70 const TUint KSkippedAlarmInstancesPubSubKey = 101; |
|
71 |
|
72 /** |
|
73 * The publish and subscribe data for KMissingAlarmInstancesPubSubKey |
|
74 * @publishedPartner |
|
75 * @released |
|
76 */ |
|
77 struct TASShdAlarmedInstanceParams |
|
78 { |
|
79 /** |
|
80 * The start of the time range in local time. |
|
81 */ |
|
82 TTime iLocalStartTime; |
|
83 |
|
84 /** |
|
85 * The end of the time range in local time. |
|
86 */ |
|
87 TTime iLocalEndTime; |
|
88 |
|
89 /** |
|
90 * The alarm time types to include. |
|
91 */ |
|
92 TASShdAlarmTimeType iTimeType; |
|
93 }; |
|
94 |
|
95 #endif //SYMBIAN_SKIPPED_CALENDAR_ALARMS |
|
96 #endif //SYMBIAN_ENABLE_SPLIT_HEADERS |
|
97 |
|
98 |
|
99 #ifdef SYMBIAN_SYSTEM_STATE_MANAGEMENT |
|
100 |
|
101 /** |
|
102 * Used for subcribing wake-up alarm set and unset notifications |
|
103 * Belonging to the KAlarmServerPubSubCategory alarm publish and subscribe category |
|
104 * |
|
105 * @publishedPartner |
|
106 * @released |
|
107 */ |
|
108 const TUint KWakeupAlarmPubSubKey = 102; |
|
109 |
|
110 /** |
|
111 * Alarm server sets KWakeupAlarmPubSubKey value to EActiveWakeupAlarmSet when there is an active |
|
112 * wakeup alarm in the alarm queue otherwise sets it to EActiveNoWakeupAlarmsSet. |
|
113 * A wakeup alarm starts the device if it is powered off when the alarm expires. If |
|
114 * the device is in normal mode then it works as a clock alarm. |
|
115 * An active wakeup alarm is a wakeup alarm which has been set and has not started to alert yet. |
|
116 * |
|
117 * EActiveWakeupAlarmUninitialized is used to notify the listeners of 'KWakeupAlarmPubSubKey' |
|
118 * key that the Alarm Server has just started at the device boot time and it needs to internalize |
|
119 * Alarm Queue from backup before checking for the presence of active wake-up alarm. |
|
120 * |
|
121 * @publishedPartner |
|
122 * @released |
|
123 */ |
|
124 enum TActiveWakeupAlarmStatus |
|
125 { |
|
126 EActiveWakeupAlarmUninitialized = 100, |
|
127 EActiveWakeupAlarmSet, |
|
128 EActiveNoWakeupAlarmsSet, |
|
129 }; |
|
130 |
|
131 #endif |
|
132 |
|
133 /** |
|
134 * A client-side alarm object. |
|
135 * |
|
136 * It contains all of the information needed to create an alarm in the Alarm Server. |
|
137 * |
|
138 * @publishedAll |
|
139 * @released |
|
140 */ |
|
141 class TASShdAlarm |
|
142 { |
|
143 public: |
|
144 |
|
145 IMPORT_C TASShdAlarm(); |
|
146 |
|
147 public: |
|
148 |
|
149 IMPORT_C void InternalizeL(RReadStream& aStream); |
|
150 IMPORT_C void ExternalizeL(RWriteStream& aStream) const; |
|
151 |
|
152 public: |
|
153 // Read-Only Access |
|
154 |
|
155 /** |
|
156 * Returns the alarm status. |
|
157 * |
|
158 * @return Alarm status. |
|
159 */ |
|
160 inline TAlarmStatus Status() const { return iStatus; } |
|
161 |
|
162 /** |
|
163 * Returns the alarm state. |
|
164 * |
|
165 * @return Alarm state. |
|
166 */ |
|
167 inline TAlarmState State() const { return iState; } |
|
168 |
|
169 IMPORT_C TBool HasAssociatedData() const; |
|
170 IMPORT_C TBool HasOwningSession() const; |
|
171 IMPORT_C TBool HasBecomeOrphaned() const; |
|
172 |
|
173 public: |
|
174 |
|
175 IMPORT_C void Reset(); |
|
176 |
|
177 /** |
|
178 * Returns a writable version of the alarm's unique identifier. |
|
179 * |
|
180 * @return Reference to the unique identifier. |
|
181 */ |
|
182 inline TAlarmId& Id() { return iAlarmId; } |
|
183 |
|
184 /** |
|
185 * Return the alarm's unique identifier. |
|
186 * |
|
187 * @return The unique identifier. |
|
188 */ |
|
189 inline TAlarmId Id() const { return iAlarmId; } |
|
190 |
|
191 /** |
|
192 * The Secure ID is only used in the secured platform |
|
193 */ |
|
194 |
|
195 // adds a SID to the alarms private field |
|
196 inline void SetSid(const TSecureId& aSecureID) {iTASShdAlarmSID = aSecureID;} |
|
197 |
|
198 // returns the SID of the alarm's creator |
|
199 inline TSecureId GetSid() const {return iTASShdAlarmSID;} |
|
200 |
|
201 /** |
|
202 * Returns a writable version of the next time the alarm is scheduled to expire. |
|
203 * |
|
204 * @return Next expiry time. |
|
205 */ |
|
206 inline TTime& NextDueTime() { return iNextDueTime; } |
|
207 |
|
208 /** |
|
209 * Returns the next time that the alarm is scheduled to expire. |
|
210 * |
|
211 * @return Next expiry time. |
|
212 */ |
|
213 inline const TTime& NextDueTime() const { return iNextDueTime; } |
|
214 |
|
215 /** |
|
216 * Returns a writable version of the alarm's original expiry time. |
|
217 * |
|
218 * @return Original expiry time. |
|
219 */ |
|
220 inline TTime& OriginalExpiryTime() { return iOriginalExpiryTime; } |
|
221 |
|
222 /** |
|
223 * Returns the alarm's original expiry time. |
|
224 * |
|
225 * The original expiry time is the same as the next due time, unless the alarm |
|
226 * has been snoozed. In that case, the original expiry time is the time when |
|
227 * the alarm first expired, and the next due time is when it is to re-awaken |
|
228 * after the snooze. |
|
229 * |
|
230 * @return Original expiry time. |
|
231 */ |
|
232 inline const TTime& OriginalExpiryTime() const { return iOriginalExpiryTime; } |
|
233 |
|
234 /** |
|
235 * Returns a writable version of the alarm's category. |
|
236 * |
|
237 * Clients can use the category to tag each alarm with a specific code. This |
|
238 * allows clients to identify all related alarms, such as all alarms associated |
|
239 * with a particular application or application engine. |
|
240 * |
|
241 * @return Alarm category. |
|
242 */ |
|
243 inline TAlarmCategory& Category() { return iCategory; } |
|
244 |
|
245 /** |
|
246 * Return this alarm's category. |
|
247 * |
|
248 * @return Alarm category. |
|
249 */ |
|
250 inline TAlarmCategory Category() const { return iCategory; } |
|
251 |
|
252 /** |
|
253 * Returns a writable version of the alarm's characteristics. |
|
254 * |
|
255 * @return Alarm characteristics bit flags. |
|
256 */ |
|
257 inline TAlarmCharacteristicsFlags& Characteristics() { return iCharacteristics; } |
|
258 |
|
259 /** |
|
260 * Returns the alarm's characteristics |
|
261 * |
|
262 * @return Alarm characteristics bit flags. |
|
263 */ |
|
264 inline TAlarmCharacteristicsFlags Characteristics() const { return iCharacteristics; } |
|
265 |
|
266 /** |
|
267 * Returns a writable version of the alarm's repeat definition. |
|
268 * |
|
269 * The repeat definition controls the alarm's behaviour after it has expired. |
|
270 * For example, you can set the repeat definition so that the server automatically |
|
271 * queues the alarm to expire again in exactly 24 hours time. |
|
272 * |
|
273 * @return Alarm repeat definition. |
|
274 */ |
|
275 inline TAlarmRepeatDefinition& RepeatDefinition() { return iRepeatDefinition; } |
|
276 |
|
277 /** |
|
278 * Returns the repeat definition for the alarm. |
|
279 * |
|
280 * @return The alarm's repeat definition. |
|
281 */ |
|
282 inline TAlarmRepeatDefinition RepeatDefinition() const { return iRepeatDefinition; } |
|
283 |
|
284 /** |
|
285 * Returns a writable version of the alarm's message. |
|
286 * |
|
287 * The message is usually displayed in the application UI when the alarm expires. |
|
288 * |
|
289 * @return Reference to the alarm's associated message. |
|
290 */ |
|
291 inline TAlarmMessage& Message() { return iMessage; } |
|
292 |
|
293 /** |
|
294 * Returns the alarm's message. |
|
295 * |
|
296 * The message is usually displayed in the application UI when the alarm expires. |
|
297 * |
|
298 * @return Reference to the alarm's associated message. |
|
299 */ |
|
300 inline const TAlarmMessage& Message() const { return iMessage; } |
|
301 |
|
302 /** |
|
303 * Return a writable version of the alarm sound's filename. |
|
304 * |
|
305 * @return Reference to the alarm's sound filename. |
|
306 */ |
|
307 inline TAlarmSoundName& SoundName() { return iSoundName; } |
|
308 |
|
309 /** |
|
310 * Returns the alarm's sound filename. |
|
311 * |
|
312 * @return Sound filename. |
|
313 */ |
|
314 inline const TAlarmSoundName& SoundName() const { return iSoundName; } |
|
315 |
|
316 /** |
|
317 * Returns the alarm session type. |
|
318 * |
|
319 * @return Alarm session type. |
|
320 */ |
|
321 inline TAlarmDayOrTimed DayOrTimed() const { return iDayOrTimed; } |
|
322 |
|
323 /** |
|
324 * Returns a writable version of the alarm type, i.e. day, timed |
|
325 * |
|
326 * @return iDayOrTimed. |
|
327 */ |
|
328 inline TAlarmDayOrTimed& DayOrTimed() { return iDayOrTimed; } |
|
329 |
|
330 IMPORT_C void SetUtcNextDueTime(TTime aUtcTime); |
|
331 IMPORT_C void SetDeQueueIfDueTimeInPast(); |
|
332 |
|
333 #ifdef SYMBIAN_SYSTEM_STATE_MANAGEMENT |
|
334 IMPORT_C void SetWakeup(TBool aEnabled); |
|
335 IMPORT_C TBool IsWakeup() const; |
|
336 #endif |
|
337 |
|
338 #ifdef SYMBIAN_ALARM_REPEAT_EXTENSIONS |
|
339 IMPORT_C TInt SetAlarmDays(TUint8 aAlarmDays); |
|
340 IMPORT_C TUint8 AlarmDays() const; |
|
341 IMPORT_C void SetContinuous(TBool aContinuous); |
|
342 IMPORT_C TBool Continuous(); |
|
343 #endif |
|
344 |
|
345 public: |
|
346 // CLient Data Access |
|
347 |
|
348 /** |
|
349 * Returns a writable version of the alarm's client flags. |
|
350 * |
|
351 * The client flags may be used for any client-specific data - the alarm server does not use them. |
|
352 * |
|
353 * @return Reference to the alarm's bit flags. |
|
354 */ |
|
355 inline TBitFlags16& ClientFlags() { return iClientFlags; } |
|
356 |
|
357 /** |
|
358 * Returns this alarm's client flags. |
|
359 * |
|
360 * @return Reference to the alarm's bit flags. |
|
361 */ |
|
362 inline TBitFlags16 ClientFlags() const { return iClientFlags; } |
|
363 |
|
364 /** |
|
365 * Returns the client data from slot 1 for this alarm. |
|
366 * |
|
367 * @return The first client-specific integer. |
|
368 */ |
|
369 inline TInt ClientData1() const { return iClientData1; } |
|
370 |
|
371 /** |
|
372 * Returns a writable version of the client data from slot 1 for this alarm. |
|
373 * |
|
374 * @return Reference to the first client-specific integer. |
|
375 */ |
|
376 inline TInt& ClientData1() { return iClientData1; } |
|
377 |
|
378 /** |
|
379 * Returns the client data from slot 2 for this alarm. |
|
380 * |
|
381 * @return The second client-specific integer. |
|
382 */ |
|
383 inline TInt ClientData2() const { return iClientData2; } |
|
384 |
|
385 /** |
|
386 * Returns the client data from slot 2 for this alarm. |
|
387 * |
|
388 * @return The second client-specific integer. |
|
389 */ |
|
390 inline TInt& ClientData2() { return iClientData2; } |
|
391 |
|
392 |
|
393 /** |
|
394 * Tests whether the alarm is floating. |
|
395 * |
|
396 * Floating alarms expire at a given wall-clock time regardless of the |
|
397 * current locale and whether any daylight saving time rules are in force. |
|
398 * |
|
399 * @return True if the alarm is floating. |
|
400 */ |
|
401 inline TBool IsFloating() const { return iCharacteristics.IsClear(EAlarmCharacteristicsIsFixed); } |
|
402 |
|
403 protected: |
|
404 // Internal Flags |
|
405 |
|
406 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS |
|
407 /* |
|
408 * @internalAll |
|
409 */ |
|
410 enum TASShdAlarmFlags |
|
411 { |
|
412 /** |
|
413 * @publishedAll |
|
414 */ |
|
415 EASShdAlarmFlagsHasAssociatedData = 0, |
|
416 |
|
417 /** |
|
418 * @publishedAll |
|
419 */ |
|
420 EASShdAlarmFlagsHasOwningSession = 1, |
|
421 |
|
422 /** |
|
423 * @publishedAll |
|
424 */ |
|
425 EASShdAlarmFlagsHasBecomeOrphaned = 2, |
|
426 |
|
427 /** |
|
428 * Set if alarm is disabled manually so that can not be enabled when locale changes. |
|
429 * |
|
430 * @publishedAll |
|
431 */ |
|
432 EASShdAlarmFlagsPermanentDisabled = 4 |
|
433 }; |
|
434 #endif |
|
435 |
|
436 private: |
|
437 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS |
|
438 |
|
439 #ifdef SYMBIAN_SYSTEM_STATE_MANAGEMENT |
|
440 /* |
|
441 * @internalComponent |
|
442 */ |
|
443 enum TASShdAlarmFlags2 |
|
444 { |
|
445 EASShdAlarmFlag2Wakeup = 0, |
|
446 }; |
|
447 #endif |
|
448 |
|
449 #ifdef SYMBIAN_ALARM_REPEAT_EXTENSIONS |
|
450 /* |
|
451 * @internalComponent |
|
452 */ |
|
453 enum TASShdAlarmFlags2AlarmRepeatExtensions |
|
454 { |
|
455 EASShdAlarmFlag2AlarmDayMonday = 1, |
|
456 EASShdAlarmFlag2AlarmDayTuesday = 2, |
|
457 EASShdAlarmFlag2AlarmDayWednesday = 3, |
|
458 EASShdAlarmFlag2AlarmDayThursday = 4, |
|
459 EASShdAlarmFlag2AlarmDayFriday = 5, |
|
460 EASShdAlarmFlag2AlarmDaySaturday = 6, |
|
461 EASShdAlarmFlag2AlarmDaySunday = 7, |
|
462 EASShdAlarmFlag2Continuous = 8 |
|
463 }; |
|
464 #endif |
|
465 |
|
466 #endif //SYMBIAN_ENABLE_SPLIT_HEADERS |
|
467 |
|
468 |
|
469 protected: |
|
470 |
|
471 /** |
|
472 * Various flags - used internally by the alarm object |
|
473 */ |
|
474 TBitFlags8 iFlags; |
|
475 |
|
476 /** |
|
477 * This represents the desired behaviour for a given alarm. |
|
478 * The Alarm Server uses this information to control the |
|
479 * behaviour of the alarm. |
|
480 * |
|
481 * @see TAlarmCharacteristics |
|
482 */ |
|
483 TAlarmCharacteristicsFlags iCharacteristics; |
|
484 |
|
485 /** |
|
486 * The unique identifier assoicated with each alarm maintained |
|
487 * by the alarm world server. |
|
488 */ |
|
489 TAlarmId iAlarmId; |
|
490 |
|
491 /** |
|
492 * The status of this alarm (e.g. enabled, disabled) |
|
493 */ |
|
494 TAlarmStatus iStatus; |
|
495 |
|
496 /** |
|
497 * The state of this alarm (e.g. queued, notifying, notified, snoozed etc) |
|
498 */ |
|
499 TAlarmState iState; |
|
500 |
|
501 /** |
|
502 * The type of this alarm (e.g. day, timed) |
|
503 */ |
|
504 TAlarmDayOrTimed iDayOrTimed; |
|
505 |
|
506 /** |
|
507 * Controls how the alarm repeats after it has expired. Note that |
|
508 * session alarms are not allowed to repeat (they must be "once |
|
509 * only"). |
|
510 */ |
|
511 TAlarmRepeatDefinition iRepeatDefinition; |
|
512 |
|
513 /** |
|
514 * This UID is supplied by the client and is used to indicate |
|
515 * the category that this alarm is part of. The Alarm Server |
|
516 * is category-agnostic, that is, this information is for |
|
517 * the client's use only |
|
518 */ |
|
519 TAlarmCategory iCategory; |
|
520 |
|
521 /** |
|
522 * The date and time at which this alarm is next due. For alarms |
|
523 * that haven't been snoozed, then this is the original due time. |
|
524 * |
|
525 * For alarms that have been snoozed, this is the time at which |
|
526 * the alarm will reawaken. |
|
527 */ |
|
528 TTime iNextDueTime; |
|
529 |
|
530 /** |
|
531 * This attribute is only used in the instance whereby an alarm |
|
532 * is snoozed. It represents the time at which the alarm first |
|
533 * expired. |
|
534 */ |
|
535 TTime iOriginalExpiryTime; |
|
536 |
|
537 /** |
|
538 * The message associated with this alarm, typically used |
|
539 * in an application UI to inform the user as to the reason |
|
540 * for the alarm. |
|
541 */ |
|
542 TAlarmMessage iMessage; |
|
543 |
|
544 /** |
|
545 * A descriptor which holds the name of the sound file which |
|
546 * should be played when the alarm expires. |
|
547 */ |
|
548 TAlarmSoundName iSoundName; |
|
549 |
|
550 protected: |
|
551 |
|
552 // Client Specific Data |
|
553 |
|
554 /** |
|
555 * Flags for use by any particular client. These will |
|
556 * only be relevant to a client who can interpret them. |
|
557 */ |
|
558 TBitFlags16 iClientFlags; |
|
559 |
|
560 /** |
|
561 * For arbitrary client data 1 |
|
562 */ |
|
563 TInt iClientData1; |
|
564 |
|
565 /** |
|
566 * For arbitrary client data 2 |
|
567 */ |
|
568 TInt iClientData2; |
|
569 |
|
570 private: |
|
571 // Binary Compatibility Proofing |
|
572 TSecureId iTASShdAlarmSID; |
|
573 |
|
574 #ifdef SYMBIAN_SYSTEM_STATE_MANAGEMENT |
|
575 /** |
|
576 * Various flags - used internally by the alarm object |
|
577 */ |
|
578 TBitFlags16 iFlags2; |
|
579 TUint16 iTASShdAlarm_2; |
|
580 #else |
|
581 |
|
582 #ifdef SYMBIAN_ALARM_REPEAT_EXTENSIONS |
|
583 /** |
|
584 * Various flags - used internally by the alarm object |
|
585 */ |
|
586 TBitFlags16 iFlags2; |
|
587 TUint16 iTASShdAlarm_2; |
|
588 #else |
|
589 TAny* iTASShdAlarm_2; |
|
590 #endif |
|
591 #endif |
|
592 TAny* iTASShdAlarm_3; |
|
593 }; |
|
594 |
|
595 #endif // #ifndef __ASSHDALARM_H__ |