--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/epoc32/include/mw/asshdalarm.h Wed Mar 31 12:27:01 2010 +0100
@@ -0,0 +1,546 @@
+// Copyright (c) 1999-2009 Nokia Corporation and/or its subsidiary(-ies).
+// All rights reserved.
+// This component and the accompanying materials are made available
+// 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
+// which accompanies this distribution, and is available
+// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
+//
+// Initial Contributors:
+// Nokia Corporation - initial contribution.
+//
+// Contributors:
+//
+// Description:
+//
+
+#ifndef __ASSHDALARM_H__
+#define __ASSHDALARM_H__
+
+
+// System includes
+#include <e32base.h>
+#include <s32strm.h>
+
+// User includes
+#include <asshddefs.h>
+
+///////////////////////////////////////////////////////////////////////////////////////
+// ----> TASShdAlarm (header)
+///////////////////////////////////////////////////////////////////////////////////////
+
+/** The Alarm publish and subscribe category
+@publishedPartner
+@released
+*/
+const TUid KAlarmServerPubSubCategory = { 0x101f5027 };
+
+/** Used for subcribing missed alarms or time zone changes
+@publishedPartner
+@released
+*/
+const TUint KMissingAlarmPubSubKey = 100;
+
+/** The publish and subscribe data for KMissingAlarmPubSubKey
+@publishedPartner
+@released
+*/
+struct TMissedAlarmPubSubData
+ {
+ /** The value indicating the changes.
+ 1 - Time zone has been changes but there are no missed alarms
+ 2 - Some alarms have been missed after system time or time zone has changed.
+ */
+ TUint8 iValue;
+
+ /** The time that system time change took place, in universal (UTC) time */
+ TTime iTimeOfChangeUtc;
+ };
+
+/** Used for subscribing to data used when searching for instances in Calendar
+@publishedPartner
+@released
+*/
+const TUint KSkippedAlarmInstancesPubSubKey = 101;
+
+/** The publish and subscribe data for KMissingAlarmInstancesPubSubKey
+@publishedPartner
+@released
+*/
+struct TASShdAlarmedInstanceParams
+ {
+ /** The start of the time range in local time. */
+ TTime iLocalStartTime;
+
+ /** The end of the time range in local time. */
+ TTime iLocalEndTime;
+
+ /** The alarm time types to include. */
+ TASShdAlarmTimeType iTimeType;
+ };
+
+
+class TASShdAlarm
+/** A client-side alarm object.
+
+It contains all of the information needed to create an alarm in
+the Alarm Server.
+@publishedAll
+@released
+*/
+ {
+///////////////////////////////////////////////////////////////////////////////////////
+public: // CONSTRUCT
+///////////////////////////////////////////////////////////////////////////////////////
+
+ IMPORT_C TASShdAlarm();
+
+///////////////////////////////////////////////////////////////////////////////////////
+public: // INTERNALIZE / EXTERNALIZE
+///////////////////////////////////////////////////////////////////////////////////////
+
+ IMPORT_C void InternalizeL(RReadStream& aStream);
+
+ IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
+
+///////////////////////////////////////////////////////////////////////////////////////
+public: // READ-ONLY ACCESS
+///////////////////////////////////////////////////////////////////////////////////////
+
+ inline TAlarmStatus Status() const
+ /** Returns the alarm status.
+
+ @return Alarm status. */
+ { return iStatus; }
+
+ inline TAlarmState State() const
+ /** Returns the alarm state.
+
+ @return Alarm state. */
+ { return iState; }
+
+ inline TBool HasAssociatedData() const;
+
+ inline TBool HasOwningSession() const;
+
+ inline TBool HasBecomeOrphaned() const;
+
+///////////////////////////////////////////////////////////////////////////////////////
+public: // READ-ONLY & MODIFIABLE
+///////////////////////////////////////////////////////////////////////////////////////
+
+ IMPORT_C void Reset();
+
+ inline TAlarmId& Id()
+ /** Returns a writable version of the alarm's unique identifier.
+
+ @return Reference to the unique identifier. */
+ { return iAlarmId; }
+
+ inline TAlarmId Id() const
+ /** Return the alarm's unique identifier.
+
+ @return The unique identifier. */
+ { return iAlarmId; }
+
+//The Secure ID is only used in the secured platform
+
+ // adds a SID to the alarms private field
+ inline void SetSid(const TSecureId& aSecureID)
+ {iTASShdAlarmSID = aSecureID;}
+
+ // returns the SID of the alarm's creator
+ inline TSecureId GetSid() const
+ {return iTASShdAlarmSID;}
+
+ inline TTime& NextDueTime()
+ /** Returns a writable version of the next time the alarm is scheduled to expire.
+
+ @return Next expiry time. */
+ { return iNextDueTime; }
+
+ inline const TTime& NextDueTime() const
+ /** Returns the next time that the alarm is scheduled to expire.
+
+ @return Next expiry time. */
+ { return iNextDueTime; }
+
+ inline TTime& OriginalExpiryTime()
+ /** Returns a writable version of the alarm's original expiry time.
+
+ @return Original expiry time. */
+ { return iOriginalExpiryTime; }
+
+ inline const TTime& OriginalExpiryTime() const
+ /** Returns the alarm's original expiry time.
+
+ The original expiry time is the same as the next due time, unless the alarm
+ has been snoozed. In that case, the original expiry time is the time when
+ the alarm first expired, and the next due time is when it is to re-awaken
+ after the snooze.
+
+ @return Original expiry time. */
+ { return iOriginalExpiryTime; }
+
+ inline TAlarmCategory& Category()
+ /** Returns a writable version of the alarm's category.
+
+ Clients can use the category to tag each alarm with a specific code. This
+ allows clients to identify all related alarms, such as all alarms associated
+ with a particular application or application engine.
+
+ @return Alarm category. */
+ { return iCategory; }
+
+ inline TAlarmCategory Category() const
+ /** Return this alarm's category.
+
+ @return Alarm category. */
+ { return iCategory; }
+
+ inline TAlarmCharacteristicsFlags& Characteristics()
+ /** Returns a writable version of the alarm's characteristics.
+
+ @return Alarm characteristics bit flags. */
+ { return iCharacteristics; }
+
+ inline TAlarmCharacteristicsFlags Characteristics() const
+ /** Returns the alarm's characteristics
+
+ @return Alarm characteristics bit flags. */
+ { return iCharacteristics; }
+
+ inline TAlarmRepeatDefinition& RepeatDefinition()
+ /** Returns a writable version of the alarm's repeat definition.
+
+ The repeat definition controls the alarm's behaviour after it has expired.
+ For example, you can set the repeat definition so that the server automatically
+ queues the alarm to expire again in exactly 24 hours time.
+
+ @return Alarm repeat definition. */
+ { return iRepeatDefinition; }
+
+ inline TAlarmRepeatDefinition RepeatDefinition() const
+ /** Returns the repeat definition for the alarm.
+
+ @return The alarm's repeat definition. */
+ { return iRepeatDefinition; }
+
+ inline TAlarmMessage& Message()
+ /** Returns a writable version of the alarm's message.
+
+ The message is usually displayed in the application UI
+ when the alarm expires.
+
+ @return Reference to the alarm's associated message. */
+ { return iMessage; }
+
+ inline const TAlarmMessage& Message() const
+ /** Returns the alarm's message.
+
+ The message is usually displayed in the application UI when the alarm expires.
+
+ @return Reference to the alarm's associated message. */
+ { return iMessage; }
+
+ inline TAlarmSoundName& SoundName()
+ /** Return a writable version of the alarm sound's filename.
+
+ @return Reference to the alarm's sound filename. */
+ { return iSoundName; }
+
+ inline const TAlarmSoundName& SoundName() const
+ /** Returns the alarm's sound filename.
+
+ @return Sound filename. */
+ { return iSoundName; }
+
+ inline TAlarmDayOrTimed DayOrTimed() const
+ /** Returns the alarm session type.
+
+ @return Alarm session type. */
+ { return iDayOrTimed; }
+
+
+ inline TAlarmDayOrTimed& DayOrTimed()
+ /** Returns a writable version of the alarm type, i.e. day, timed
+
+ @return iDayOrTimed. */
+ { return iDayOrTimed; }
+
+
+ IMPORT_C void SetUtcNextDueTime(TTime aUtcTime);
+
+ IMPORT_C void SetDeQueueIfDueTimeInPast();
+
+ IMPORT_C TInt SetAlarmDays(TUint8 aAlarmDays);
+ IMPORT_C TUint8 AlarmDays() const;
+ IMPORT_C void SetContinuous(TBool aContinuous);
+ IMPORT_C TBool Continuous();
+
+///////////////////////////////////////////////////////////////////////////////////////
+public: // CLIENT DATA ACCESS
+///////////////////////////////////////////////////////////////////////////////////////
+
+ inline TBitFlags16& ClientFlags()
+ /** Returns a writable version of the alarm's client flags.
+
+ The client flags may be used for any client-specific data -
+ the alarm server does not use them.
+
+ @return Reference to the alarm's bit flags. */
+ { return iClientFlags; }
+
+ inline TBitFlags16 ClientFlags() const
+ /** Returns this alarm's client flags.
+
+ @return Reference to the alarm's bit flags. */
+ { return iClientFlags; }
+
+ inline TInt ClientData1() const
+ /** Returns the client data from slot 1 for this alarm.
+
+ @return The first client-specific integer. */
+ { return iClientData1; }
+
+ inline TInt& ClientData1()
+ /** Returns a writable version of the client data from slot 1 for this alarm.
+
+ @return Reference to the first client-specific integer. */
+ { return iClientData1; }
+
+ inline TInt ClientData2() const
+ /** Returns the client data from slot 2 for this alarm.
+
+ @return The second client-specific integer. */
+ { return iClientData2; }
+
+ inline TInt& ClientData2()
+ /** Returns the client data from slot 2 for this alarm.
+
+ @return The second client-specific integer. */
+ { return iClientData2; }
+
+ inline TBool IsFloating() const
+ /** Tests whether the alarm is floating.
+
+ Floating alarms expire at a given wall-clock time regardless of the current locale and
+ whether any daylight saving time rules are in force.
+
+ @return True if the alarm is floating.
+ */
+ { return iCharacteristics.IsClear(EAlarmCharacteristicsIsFixed); }
+
+
+
+
+
+///////////////////////////////////////////////////////////////////////////////////////
+protected: // INTERNAL FLAGS
+///////////////////////////////////////////////////////////////////////////////////////
+
+ /*
+ * @internalAll
+ */
+ enum TASShdAlarmFlags
+ {
+
+ /*
+ * @internalAll
+ */
+ EASShdAlarmFlagsHasAssociatedData = 0,
+
+ /*
+ * @internalAll
+ */
+ EASShdAlarmFlagsHasOwningSession = 1,
+
+ /*
+ * @internalAll
+ */
+ EASShdAlarmFlagsHasBecomeOrphaned = 2,
+
+ /*
+ * @internalAll Set if alarm is disabled manually so that can not be enabled when
+ * locale changes.
+ */
+ EASShdAlarmFlagsPermanentDisabled = 4
+
+ };
+
+private:
+ /*
+ * @internalComponent
+ */
+ enum TASShdAlarmFlags2
+ {
+ EASShdAlarmFlag2Wakeup = 0,
+ };
+
+ enum TASShdAlarmFlags2AlarmRepeatExtensions
+ {
+ EASShdAlarmFlag2AlarmDayMonday = 1,
+ EASShdAlarmFlag2AlarmDayTuesday = 2,
+ EASShdAlarmFlag2AlarmDayWednesday = 3,
+ EASShdAlarmFlag2AlarmDayThursday = 4,
+ EASShdAlarmFlag2AlarmDayFriday = 5,
+ EASShdAlarmFlag2AlarmDaySaturday = 6,
+ EASShdAlarmFlag2AlarmDaySunday = 7,
+ EASShdAlarmFlag2Continuous = 8
+ };
+
+
+///////////////////////////////////////////////////////////////////////////////////////
+protected: // MEMBER DATA
+///////////////////////////////////////////////////////////////////////////////////////
+
+ /*
+ * Various flags - used internally by the alarm object
+ */
+ TBitFlags8 iFlags;
+
+ /*
+ * This represents the desired behaviour for a given alarm.
+ * The Alarm Server uses this information to control the
+ * behaviour of the alarm.
+ *
+ * @see TAlarmCharacteristics
+ */
+ TAlarmCharacteristicsFlags iCharacteristics;
+
+ /*
+ * The unique identifier assoicated with each alarm maintained
+ * by the alarm world server.
+ */
+ TAlarmId iAlarmId;
+
+ /*
+ * The status of this alarm (e.g. enabled, disabled)
+ */
+ TAlarmStatus iStatus;
+
+ /*
+ * The state of this alarm (e.g. queued, notifying, notified, snoozed etc)
+ */
+ TAlarmState iState;
+
+ /*
+ * The type of this alarm (e.g. day, timed)
+ */
+ TAlarmDayOrTimed iDayOrTimed;
+
+ /*
+ * Controls how the alarm repeats after it has expired. Note that
+ * session alarms are not allowed to repeat (they must be "once
+ * only").
+ */
+ TAlarmRepeatDefinition iRepeatDefinition;
+
+ /*
+ * This UID is supplied by the client and is used to indicate
+ * the category that this alarm is part of. The Alarm Server
+ * is category-agnostic, that is, this information is for
+ * the client's use only
+ */
+ TAlarmCategory iCategory;
+
+ /*
+ * The date and time at which this alarm is next due. For alarms
+ * that haven't been snoozed, then this is the original due time.
+ *
+ * For alarms that have been snoozed, this is the time at which
+ * the alarm will reawaken.
+ */
+ TTime iNextDueTime;
+
+ /*
+ * This attribute is only used in the instance whereby an alarm
+ * is snoozed. It represents the time at which the alarm first
+ * expired.
+ */
+ TTime iOriginalExpiryTime;
+
+ /*
+ * The message associated with this alarm, typically used
+ * in an application UI to inform the user as to the reason
+ * for the alarm.
+ */
+ TAlarmMessage iMessage;
+
+ /*
+ * A descriptor which holds the name of the sound file which
+ * should be played when the alarm expires.
+ */
+ TAlarmSoundName iSoundName;
+
+///////////////////////////////////////////////////////////////////////////////////////
+protected: // CLIENT SPECIFIC DATA
+///////////////////////////////////////////////////////////////////////////////////////
+
+ /*
+ * Flags for use by any particular client. These will
+ * only be relevant to a client who can interpret them.
+ */
+ TBitFlags16 iClientFlags;
+
+ /*
+ * For arbitrary client data 1
+ */
+ TInt iClientData1;
+
+ /*
+ * For arbitrary client data 2
+ */
+ TInt iClientData2;
+
+///////////////////////////////////////////////////////////////////////////////////////
+private: // BC PROOFING
+///////////////////////////////////////////////////////////////////////////////////////
+ TSecureId iTASShdAlarmSID;
+ /*
+ * Various flags - used internally by the alarm object
+ */
+ TBitFlags16 iFlags2;
+ TUint16 iTASShdAlarm_2;
+ TAny* iTASShdAlarm_3;
+ };
+
+
+///////////////////////////////////////////////////////////////////////////////////////
+// ----> TASShdAlarm (inline)
+///////////////////////////////////////////////////////////////////////////////////////
+
+
+/** Tests whether the alarm has any associated data.
+
+@return True if the alarm has associated data. */
+inline TBool TASShdAlarm::HasAssociatedData() const
+
+ {
+ return iFlags.IsSet(EASShdAlarmFlagsHasAssociatedData);
+ }
+
+
+/** Tests whether the alarm has an active owning session.
+
+@return True if the alarm has an active owning session. */
+inline TBool TASShdAlarm::HasOwningSession() const
+
+ {
+ return iFlags.IsSet(EASShdAlarmFlagsHasOwningSession);
+ }
+
+inline TBool TASShdAlarm::HasBecomeOrphaned() const
+/** Tests whether the alarm is orphaned.
+
+An alarm is ophaned if it used to have an owning session, but no longer does.
+If an alarm is owned by a session, it is removed from the queue when the session
+disconnects. However, orphaned alarms stay in the queue.
+
+@return True if the alarm has becomed orphaned. */
+ {
+ return iFlags.IsSet(EASShdAlarmFlagsHasBecomeOrphaned);
+ }
+
+
+
+#endif // #ifndef __ASSHDALARM_H__