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