1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/asshdalarm.h Wed Mar 31 12:27:01 2010 +0100
1.3 @@ -0,0 +1,546 @@
1.4 +// Copyright (c) 1999-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// 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
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +#ifndef __ASSHDALARM_H__
1.20 +#define __ASSHDALARM_H__
1.21 +
1.22 +
1.23 +// System includes
1.24 +#include <e32base.h>
1.25 +#include <s32strm.h>
1.26 +
1.27 +// User includes
1.28 +#include <asshddefs.h>
1.29 +
1.30 +///////////////////////////////////////////////////////////////////////////////////////
1.31 +// ----> TASShdAlarm (header)
1.32 +///////////////////////////////////////////////////////////////////////////////////////
1.33 +
1.34 +/** The Alarm publish and subscribe category
1.35 +@publishedPartner
1.36 +@released
1.37 +*/
1.38 +const TUid KAlarmServerPubSubCategory = { 0x101f5027 };
1.39 +
1.40 +/** Used for subcribing missed alarms or time zone changes
1.41 +@publishedPartner
1.42 +@released
1.43 +*/
1.44 +const TUint KMissingAlarmPubSubKey = 100;
1.45 +
1.46 +/** The publish and subscribe data for KMissingAlarmPubSubKey
1.47 +@publishedPartner
1.48 +@released
1.49 +*/
1.50 +struct TMissedAlarmPubSubData
1.51 + {
1.52 + /** The value indicating the changes.
1.53 + 1 - Time zone has been changes but there are no missed alarms
1.54 + 2 - Some alarms have been missed after system time or time zone has changed.
1.55 + */
1.56 + TUint8 iValue;
1.57 +
1.58 + /** The time that system time change took place, in universal (UTC) time */
1.59 + TTime iTimeOfChangeUtc;
1.60 + };
1.61 +
1.62 +/** Used for subscribing to data used when searching for instances in Calendar
1.63 +@publishedPartner
1.64 +@released
1.65 +*/
1.66 +const TUint KSkippedAlarmInstancesPubSubKey = 101;
1.67 +
1.68 +/** The publish and subscribe data for KMissingAlarmInstancesPubSubKey
1.69 +@publishedPartner
1.70 +@released
1.71 +*/
1.72 +struct TASShdAlarmedInstanceParams
1.73 + {
1.74 + /** The start of the time range in local time. */
1.75 + TTime iLocalStartTime;
1.76 +
1.77 + /** The end of the time range in local time. */
1.78 + TTime iLocalEndTime;
1.79 +
1.80 + /** The alarm time types to include. */
1.81 + TASShdAlarmTimeType iTimeType;
1.82 + };
1.83 +
1.84 +
1.85 +class TASShdAlarm
1.86 +/** A client-side alarm object.
1.87 +
1.88 +It contains all of the information needed to create an alarm in
1.89 +the Alarm Server.
1.90 +@publishedAll
1.91 +@released
1.92 +*/
1.93 + {
1.94 +///////////////////////////////////////////////////////////////////////////////////////
1.95 +public: // CONSTRUCT
1.96 +///////////////////////////////////////////////////////////////////////////////////////
1.97 +
1.98 + IMPORT_C TASShdAlarm();
1.99 +
1.100 +///////////////////////////////////////////////////////////////////////////////////////
1.101 +public: // INTERNALIZE / EXTERNALIZE
1.102 +///////////////////////////////////////////////////////////////////////////////////////
1.103 +
1.104 + IMPORT_C void InternalizeL(RReadStream& aStream);
1.105 +
1.106 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.107 +
1.108 +///////////////////////////////////////////////////////////////////////////////////////
1.109 +public: // READ-ONLY ACCESS
1.110 +///////////////////////////////////////////////////////////////////////////////////////
1.111 +
1.112 + inline TAlarmStatus Status() const
1.113 + /** Returns the alarm status.
1.114 +
1.115 + @return Alarm status. */
1.116 + { return iStatus; }
1.117 +
1.118 + inline TAlarmState State() const
1.119 + /** Returns the alarm state.
1.120 +
1.121 + @return Alarm state. */
1.122 + { return iState; }
1.123 +
1.124 + inline TBool HasAssociatedData() const;
1.125 +
1.126 + inline TBool HasOwningSession() const;
1.127 +
1.128 + inline TBool HasBecomeOrphaned() const;
1.129 +
1.130 +///////////////////////////////////////////////////////////////////////////////////////
1.131 +public: // READ-ONLY & MODIFIABLE
1.132 +///////////////////////////////////////////////////////////////////////////////////////
1.133 +
1.134 + IMPORT_C void Reset();
1.135 +
1.136 + inline TAlarmId& Id()
1.137 + /** Returns a writable version of the alarm's unique identifier.
1.138 +
1.139 + @return Reference to the unique identifier. */
1.140 + { return iAlarmId; }
1.141 +
1.142 + inline TAlarmId Id() const
1.143 + /** Return the alarm's unique identifier.
1.144 +
1.145 + @return The unique identifier. */
1.146 + { return iAlarmId; }
1.147 +
1.148 +//The Secure ID is only used in the secured platform
1.149 +
1.150 + // adds a SID to the alarms private field
1.151 + inline void SetSid(const TSecureId& aSecureID)
1.152 + {iTASShdAlarmSID = aSecureID;}
1.153 +
1.154 + // returns the SID of the alarm's creator
1.155 + inline TSecureId GetSid() const
1.156 + {return iTASShdAlarmSID;}
1.157 +
1.158 + inline TTime& NextDueTime()
1.159 + /** Returns a writable version of the next time the alarm is scheduled to expire.
1.160 +
1.161 + @return Next expiry time. */
1.162 + { return iNextDueTime; }
1.163 +
1.164 + inline const TTime& NextDueTime() const
1.165 + /** Returns the next time that the alarm is scheduled to expire.
1.166 +
1.167 + @return Next expiry time. */
1.168 + { return iNextDueTime; }
1.169 +
1.170 + inline TTime& OriginalExpiryTime()
1.171 + /** Returns a writable version of the alarm's original expiry time.
1.172 +
1.173 + @return Original expiry time. */
1.174 + { return iOriginalExpiryTime; }
1.175 +
1.176 + inline const TTime& OriginalExpiryTime() const
1.177 + /** Returns the alarm's original expiry time.
1.178 +
1.179 + The original expiry time is the same as the next due time, unless the alarm
1.180 + has been snoozed. In that case, the original expiry time is the time when
1.181 + the alarm first expired, and the next due time is when it is to re-awaken
1.182 + after the snooze.
1.183 +
1.184 + @return Original expiry time. */
1.185 + { return iOriginalExpiryTime; }
1.186 +
1.187 + inline TAlarmCategory& Category()
1.188 + /** Returns a writable version of the alarm's category.
1.189 +
1.190 + Clients can use the category to tag each alarm with a specific code. This
1.191 + allows clients to identify all related alarms, such as all alarms associated
1.192 + with a particular application or application engine.
1.193 +
1.194 + @return Alarm category. */
1.195 + { return iCategory; }
1.196 +
1.197 + inline TAlarmCategory Category() const
1.198 + /** Return this alarm's category.
1.199 +
1.200 + @return Alarm category. */
1.201 + { return iCategory; }
1.202 +
1.203 + inline TAlarmCharacteristicsFlags& Characteristics()
1.204 + /** Returns a writable version of the alarm's characteristics.
1.205 +
1.206 + @return Alarm characteristics bit flags. */
1.207 + { return iCharacteristics; }
1.208 +
1.209 + inline TAlarmCharacteristicsFlags Characteristics() const
1.210 + /** Returns the alarm's characteristics
1.211 +
1.212 + @return Alarm characteristics bit flags. */
1.213 + { return iCharacteristics; }
1.214 +
1.215 + inline TAlarmRepeatDefinition& RepeatDefinition()
1.216 + /** Returns a writable version of the alarm's repeat definition.
1.217 +
1.218 + The repeat definition controls the alarm's behaviour after it has expired.
1.219 + For example, you can set the repeat definition so that the server automatically
1.220 + queues the alarm to expire again in exactly 24 hours time.
1.221 +
1.222 + @return Alarm repeat definition. */
1.223 + { return iRepeatDefinition; }
1.224 +
1.225 + inline TAlarmRepeatDefinition RepeatDefinition() const
1.226 + /** Returns the repeat definition for the alarm.
1.227 +
1.228 + @return The alarm's repeat definition. */
1.229 + { return iRepeatDefinition; }
1.230 +
1.231 + inline TAlarmMessage& Message()
1.232 + /** Returns a writable version of the alarm's message.
1.233 +
1.234 + The message is usually displayed in the application UI
1.235 + when the alarm expires.
1.236 +
1.237 + @return Reference to the alarm's associated message. */
1.238 + { return iMessage; }
1.239 +
1.240 + inline const TAlarmMessage& Message() const
1.241 + /** Returns the alarm's message.
1.242 +
1.243 + The message is usually displayed in the application UI when the alarm expires.
1.244 +
1.245 + @return Reference to the alarm's associated message. */
1.246 + { return iMessage; }
1.247 +
1.248 + inline TAlarmSoundName& SoundName()
1.249 + /** Return a writable version of the alarm sound's filename.
1.250 +
1.251 + @return Reference to the alarm's sound filename. */
1.252 + { return iSoundName; }
1.253 +
1.254 + inline const TAlarmSoundName& SoundName() const
1.255 + /** Returns the alarm's sound filename.
1.256 +
1.257 + @return Sound filename. */
1.258 + { return iSoundName; }
1.259 +
1.260 + inline TAlarmDayOrTimed DayOrTimed() const
1.261 + /** Returns the alarm session type.
1.262 +
1.263 + @return Alarm session type. */
1.264 + { return iDayOrTimed; }
1.265 +
1.266 +
1.267 + inline TAlarmDayOrTimed& DayOrTimed()
1.268 + /** Returns a writable version of the alarm type, i.e. day, timed
1.269 +
1.270 + @return iDayOrTimed. */
1.271 + { return iDayOrTimed; }
1.272 +
1.273 +
1.274 + IMPORT_C void SetUtcNextDueTime(TTime aUtcTime);
1.275 +
1.276 + IMPORT_C void SetDeQueueIfDueTimeInPast();
1.277 +
1.278 + IMPORT_C TInt SetAlarmDays(TUint8 aAlarmDays);
1.279 + IMPORT_C TUint8 AlarmDays() const;
1.280 + IMPORT_C void SetContinuous(TBool aContinuous);
1.281 + IMPORT_C TBool Continuous();
1.282 +
1.283 +///////////////////////////////////////////////////////////////////////////////////////
1.284 +public: // CLIENT DATA ACCESS
1.285 +///////////////////////////////////////////////////////////////////////////////////////
1.286 +
1.287 + inline TBitFlags16& ClientFlags()
1.288 + /** Returns a writable version of the alarm's client flags.
1.289 +
1.290 + The client flags may be used for any client-specific data -
1.291 + the alarm server does not use them.
1.292 +
1.293 + @return Reference to the alarm's bit flags. */
1.294 + { return iClientFlags; }
1.295 +
1.296 + inline TBitFlags16 ClientFlags() const
1.297 + /** Returns this alarm's client flags.
1.298 +
1.299 + @return Reference to the alarm's bit flags. */
1.300 + { return iClientFlags; }
1.301 +
1.302 + inline TInt ClientData1() const
1.303 + /** Returns the client data from slot 1 for this alarm.
1.304 +
1.305 + @return The first client-specific integer. */
1.306 + { return iClientData1; }
1.307 +
1.308 + inline TInt& ClientData1()
1.309 + /** Returns a writable version of the client data from slot 1 for this alarm.
1.310 +
1.311 + @return Reference to the first client-specific integer. */
1.312 + { return iClientData1; }
1.313 +
1.314 + inline TInt ClientData2() const
1.315 + /** Returns the client data from slot 2 for this alarm.
1.316 +
1.317 + @return The second client-specific integer. */
1.318 + { return iClientData2; }
1.319 +
1.320 + inline TInt& ClientData2()
1.321 + /** Returns the client data from slot 2 for this alarm.
1.322 +
1.323 + @return The second client-specific integer. */
1.324 + { return iClientData2; }
1.325 +
1.326 + inline TBool IsFloating() const
1.327 + /** Tests whether the alarm is floating.
1.328 +
1.329 + Floating alarms expire at a given wall-clock time regardless of the current locale and
1.330 + whether any daylight saving time rules are in force.
1.331 +
1.332 + @return True if the alarm is floating.
1.333 + */
1.334 + { return iCharacteristics.IsClear(EAlarmCharacteristicsIsFixed); }
1.335 +
1.336 +
1.337 +
1.338 +
1.339 +
1.340 +///////////////////////////////////////////////////////////////////////////////////////
1.341 +protected: // INTERNAL FLAGS
1.342 +///////////////////////////////////////////////////////////////////////////////////////
1.343 +
1.344 + /*
1.345 + * @internalAll
1.346 + */
1.347 + enum TASShdAlarmFlags
1.348 + {
1.349 +
1.350 + /*
1.351 + * @internalAll
1.352 + */
1.353 + EASShdAlarmFlagsHasAssociatedData = 0,
1.354 +
1.355 + /*
1.356 + * @internalAll
1.357 + */
1.358 + EASShdAlarmFlagsHasOwningSession = 1,
1.359 +
1.360 + /*
1.361 + * @internalAll
1.362 + */
1.363 + EASShdAlarmFlagsHasBecomeOrphaned = 2,
1.364 +
1.365 + /*
1.366 + * @internalAll Set if alarm is disabled manually so that can not be enabled when
1.367 + * locale changes.
1.368 + */
1.369 + EASShdAlarmFlagsPermanentDisabled = 4
1.370 +
1.371 + };
1.372 +
1.373 +private:
1.374 + /*
1.375 + * @internalComponent
1.376 + */
1.377 + enum TASShdAlarmFlags2
1.378 + {
1.379 + EASShdAlarmFlag2Wakeup = 0,
1.380 + };
1.381 +
1.382 + enum TASShdAlarmFlags2AlarmRepeatExtensions
1.383 + {
1.384 + EASShdAlarmFlag2AlarmDayMonday = 1,
1.385 + EASShdAlarmFlag2AlarmDayTuesday = 2,
1.386 + EASShdAlarmFlag2AlarmDayWednesday = 3,
1.387 + EASShdAlarmFlag2AlarmDayThursday = 4,
1.388 + EASShdAlarmFlag2AlarmDayFriday = 5,
1.389 + EASShdAlarmFlag2AlarmDaySaturday = 6,
1.390 + EASShdAlarmFlag2AlarmDaySunday = 7,
1.391 + EASShdAlarmFlag2Continuous = 8
1.392 + };
1.393 +
1.394 +
1.395 +///////////////////////////////////////////////////////////////////////////////////////
1.396 +protected: // MEMBER DATA
1.397 +///////////////////////////////////////////////////////////////////////////////////////
1.398 +
1.399 + /*
1.400 + * Various flags - used internally by the alarm object
1.401 + */
1.402 + TBitFlags8 iFlags;
1.403 +
1.404 + /*
1.405 + * This represents the desired behaviour for a given alarm.
1.406 + * The Alarm Server uses this information to control the
1.407 + * behaviour of the alarm.
1.408 + *
1.409 + * @see TAlarmCharacteristics
1.410 + */
1.411 + TAlarmCharacteristicsFlags iCharacteristics;
1.412 +
1.413 + /*
1.414 + * The unique identifier assoicated with each alarm maintained
1.415 + * by the alarm world server.
1.416 + */
1.417 + TAlarmId iAlarmId;
1.418 +
1.419 + /*
1.420 + * The status of this alarm (e.g. enabled, disabled)
1.421 + */
1.422 + TAlarmStatus iStatus;
1.423 +
1.424 + /*
1.425 + * The state of this alarm (e.g. queued, notifying, notified, snoozed etc)
1.426 + */
1.427 + TAlarmState iState;
1.428 +
1.429 + /*
1.430 + * The type of this alarm (e.g. day, timed)
1.431 + */
1.432 + TAlarmDayOrTimed iDayOrTimed;
1.433 +
1.434 + /*
1.435 + * Controls how the alarm repeats after it has expired. Note that
1.436 + * session alarms are not allowed to repeat (they must be "once
1.437 + * only").
1.438 + */
1.439 + TAlarmRepeatDefinition iRepeatDefinition;
1.440 +
1.441 + /*
1.442 + * This UID is supplied by the client and is used to indicate
1.443 + * the category that this alarm is part of. The Alarm Server
1.444 + * is category-agnostic, that is, this information is for
1.445 + * the client's use only
1.446 + */
1.447 + TAlarmCategory iCategory;
1.448 +
1.449 + /*
1.450 + * The date and time at which this alarm is next due. For alarms
1.451 + * that haven't been snoozed, then this is the original due time.
1.452 + *
1.453 + * For alarms that have been snoozed, this is the time at which
1.454 + * the alarm will reawaken.
1.455 + */
1.456 + TTime iNextDueTime;
1.457 +
1.458 + /*
1.459 + * This attribute is only used in the instance whereby an alarm
1.460 + * is snoozed. It represents the time at which the alarm first
1.461 + * expired.
1.462 + */
1.463 + TTime iOriginalExpiryTime;
1.464 +
1.465 + /*
1.466 + * The message associated with this alarm, typically used
1.467 + * in an application UI to inform the user as to the reason
1.468 + * for the alarm.
1.469 + */
1.470 + TAlarmMessage iMessage;
1.471 +
1.472 + /*
1.473 + * A descriptor which holds the name of the sound file which
1.474 + * should be played when the alarm expires.
1.475 + */
1.476 + TAlarmSoundName iSoundName;
1.477 +
1.478 +///////////////////////////////////////////////////////////////////////////////////////
1.479 +protected: // CLIENT SPECIFIC DATA
1.480 +///////////////////////////////////////////////////////////////////////////////////////
1.481 +
1.482 + /*
1.483 + * Flags for use by any particular client. These will
1.484 + * only be relevant to a client who can interpret them.
1.485 + */
1.486 + TBitFlags16 iClientFlags;
1.487 +
1.488 + /*
1.489 + * For arbitrary client data 1
1.490 + */
1.491 + TInt iClientData1;
1.492 +
1.493 + /*
1.494 + * For arbitrary client data 2
1.495 + */
1.496 + TInt iClientData2;
1.497 +
1.498 +///////////////////////////////////////////////////////////////////////////////////////
1.499 +private: // BC PROOFING
1.500 +///////////////////////////////////////////////////////////////////////////////////////
1.501 + TSecureId iTASShdAlarmSID;
1.502 + /*
1.503 + * Various flags - used internally by the alarm object
1.504 + */
1.505 + TBitFlags16 iFlags2;
1.506 + TUint16 iTASShdAlarm_2;
1.507 + TAny* iTASShdAlarm_3;
1.508 + };
1.509 +
1.510 +
1.511 +///////////////////////////////////////////////////////////////////////////////////////
1.512 +// ----> TASShdAlarm (inline)
1.513 +///////////////////////////////////////////////////////////////////////////////////////
1.514 +
1.515 +
1.516 +/** Tests whether the alarm has any associated data.
1.517 +
1.518 +@return True if the alarm has associated data. */
1.519 +inline TBool TASShdAlarm::HasAssociatedData() const
1.520 +
1.521 + {
1.522 + return iFlags.IsSet(EASShdAlarmFlagsHasAssociatedData);
1.523 + }
1.524 +
1.525 +
1.526 +/** Tests whether the alarm has an active owning session.
1.527 +
1.528 +@return True if the alarm has an active owning session. */
1.529 +inline TBool TASShdAlarm::HasOwningSession() const
1.530 +
1.531 + {
1.532 + return iFlags.IsSet(EASShdAlarmFlagsHasOwningSession);
1.533 + }
1.534 +
1.535 +inline TBool TASShdAlarm::HasBecomeOrphaned() const
1.536 +/** Tests whether the alarm is orphaned.
1.537 +
1.538 +An alarm is ophaned if it used to have an owning session, but no longer does.
1.539 +If an alarm is owned by a session, it is removed from the queue when the session
1.540 +disconnects. However, orphaned alarms stay in the queue.
1.541 +
1.542 +@return True if the alarm has becomed orphaned. */
1.543 + {
1.544 + return iFlags.IsSet(EASShdAlarmFlagsHasBecomeOrphaned);
1.545 + }
1.546 +
1.547 +
1.548 +
1.549 +#endif // #ifndef __ASSHDALARM_H__