--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/commonappservices/alarmserver/Shared/Include/ASShdAlarm.h Tue Feb 02 10:12:00 2010 +0200
@@ -0,0 +1,595 @@
+// 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 "Eclipse Public License v1.0"
+// which accompanies this distribution, and is available
+// at the URL "http://www.eclipse.org/legal/epl-v10.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>
+
+#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
+
+/**
+ * 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;
+ };
+
+#ifdef SYMBIAN_SKIPPED_CALENDAR_ALARMS
+/**
+ * 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;
+ };
+
+#endif //SYMBIAN_SKIPPED_CALENDAR_ALARMS
+#endif //SYMBIAN_ENABLE_SPLIT_HEADERS
+
+
+#ifdef SYMBIAN_SYSTEM_STATE_MANAGEMENT
+
+/**
+ * Used for subcribing wake-up alarm set and unset notifications
+ * Belonging to the KAlarmServerPubSubCategory alarm publish and subscribe category
+ *
+ * @publishedPartner
+ * @released
+ */
+const TUint KWakeupAlarmPubSubKey = 102;
+
+/**
+ * Alarm server sets KWakeupAlarmPubSubKey value to EActiveWakeupAlarmSet when there is an active
+ * wakeup alarm in the alarm queue otherwise sets it to EActiveNoWakeupAlarmsSet.
+ * A wakeup alarm starts the device if it is powered off when the alarm expires. If
+ * the device is in normal mode then it works as a clock alarm.
+ * An active wakeup alarm is a wakeup alarm which has been set and has not started to alert yet.
+ *
+ * EActiveWakeupAlarmUninitialized is used to notify the listeners of 'KWakeupAlarmPubSubKey'
+ * key that the Alarm Server has just started at the device boot time and it needs to internalize
+ * Alarm Queue from backup before checking for the presence of active wake-up alarm.
+ *
+ * @publishedPartner
+ * @released
+ */
+enum TActiveWakeupAlarmStatus
+ {
+ EActiveWakeupAlarmUninitialized = 100,
+ EActiveWakeupAlarmSet,
+ EActiveNoWakeupAlarmsSet,
+ };
+
+#endif
+
+/**
+ * A client-side alarm object.
+ *
+ * It contains all of the information needed to create an alarm in the Alarm Server.
+ *
+ * @publishedAll
+ * @released
+ */
+class TASShdAlarm
+ {
+public:
+
+ IMPORT_C TASShdAlarm();
+
+public:
+
+ IMPORT_C void InternalizeL(RReadStream& aStream);
+ IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
+
+public:
+ // Read-Only Access
+
+ /**
+ * Returns the alarm status.
+ *
+ * @return Alarm status.
+ */
+ inline TAlarmStatus Status() const { return iStatus; }
+
+ /**
+ * Returns the alarm state.
+ *
+ * @return Alarm state.
+ */
+ inline TAlarmState State() const { return iState; }
+
+ IMPORT_C TBool HasAssociatedData() const;
+ IMPORT_C TBool HasOwningSession() const;
+ IMPORT_C TBool HasBecomeOrphaned() const;
+
+public:
+
+ IMPORT_C void Reset();
+
+ /**
+ * Returns a writable version of the alarm's unique identifier.
+ *
+ * @return Reference to the unique identifier.
+ */
+ inline TAlarmId& Id() { return iAlarmId; }
+
+ /**
+ * Return the alarm's unique identifier.
+ *
+ * @return The unique identifier.
+ */
+ inline TAlarmId Id() const { 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;}
+
+ /**
+ * Returns a writable version of the next time the alarm is scheduled to expire.
+ *
+ * @return Next expiry time.
+ */
+ inline TTime& NextDueTime() { return iNextDueTime; }
+
+ /**
+ * Returns the next time that the alarm is scheduled to expire.
+ *
+ * @return Next expiry time.
+ */
+ inline const TTime& NextDueTime() const { return iNextDueTime; }
+
+ /**
+ * Returns a writable version of the alarm's original expiry time.
+ *
+ * @return Original expiry time.
+ */
+ inline TTime& OriginalExpiryTime() { return iOriginalExpiryTime; }
+
+ /**
+ * 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.
+ */
+ inline const TTime& OriginalExpiryTime() const { return iOriginalExpiryTime; }
+
+ /**
+ * 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.
+ */
+ inline TAlarmCategory& Category() { return iCategory; }
+
+ /**
+ * Return this alarm's category.
+ *
+ * @return Alarm category.
+ */
+ inline TAlarmCategory Category() const { return iCategory; }
+
+ /**
+ * Returns a writable version of the alarm's characteristics.
+ *
+ * @return Alarm characteristics bit flags.
+ */
+ inline TAlarmCharacteristicsFlags& Characteristics() { return iCharacteristics; }
+
+ /**
+ * Returns the alarm's characteristics
+ *
+ * @return Alarm characteristics bit flags.
+ */
+ inline TAlarmCharacteristicsFlags Characteristics() const { return iCharacteristics; }
+
+ /**
+ * 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.
+ */
+ inline TAlarmRepeatDefinition& RepeatDefinition() { return iRepeatDefinition; }
+
+ /**
+ * Returns the repeat definition for the alarm.
+ *
+ * @return The alarm's repeat definition.
+ */
+ inline TAlarmRepeatDefinition RepeatDefinition() const { return iRepeatDefinition; }
+
+ /**
+ * 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.
+ */
+ inline TAlarmMessage& Message() { return iMessage; }
+
+ /**
+ * 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.
+ */
+ inline const TAlarmMessage& Message() const { return iMessage; }
+
+ /**
+ * Return a writable version of the alarm sound's filename.
+ *
+ * @return Reference to the alarm's sound filename.
+ */
+ inline TAlarmSoundName& SoundName() { return iSoundName; }
+
+ /**
+ * Returns the alarm's sound filename.
+ *
+ * @return Sound filename.
+ */
+ inline const TAlarmSoundName& SoundName() const { return iSoundName; }
+
+ /**
+ * Returns the alarm session type.
+ *
+ * @return Alarm session type.
+ */
+ inline TAlarmDayOrTimed DayOrTimed() const { return iDayOrTimed; }
+
+ /**
+ * Returns a writable version of the alarm type, i.e. day, timed
+ *
+ * @return iDayOrTimed.
+ */
+ inline TAlarmDayOrTimed& DayOrTimed() { return iDayOrTimed; }
+
+ IMPORT_C void SetUtcNextDueTime(TTime aUtcTime);
+ IMPORT_C void SetDeQueueIfDueTimeInPast();
+
+#ifdef SYMBIAN_SYSTEM_STATE_MANAGEMENT
+ IMPORT_C void SetWakeup(TBool aEnabled);
+ IMPORT_C TBool IsWakeup() const;
+#endif
+
+#ifdef SYMBIAN_ALARM_REPEAT_EXTENSIONS
+ IMPORT_C TInt SetAlarmDays(TUint8 aAlarmDays);
+ IMPORT_C TUint8 AlarmDays() const;
+ IMPORT_C void SetContinuous(TBool aContinuous);
+ IMPORT_C TBool Continuous();
+#endif
+
+public:
+ // CLient Data Access
+
+ /**
+ * 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.
+ */
+ inline TBitFlags16& ClientFlags() { return iClientFlags; }
+
+ /**
+ * Returns this alarm's client flags.
+ *
+ * @return Reference to the alarm's bit flags.
+ */
+ inline TBitFlags16 ClientFlags() const { return iClientFlags; }
+
+ /**
+ * Returns the client data from slot 1 for this alarm.
+ *
+ * @return The first client-specific integer.
+ */
+ inline TInt ClientData1() const { return iClientData1; }
+
+ /**
+ * Returns a writable version of the client data from slot 1 for this alarm.
+ *
+ * @return Reference to the first client-specific integer.
+ */
+ inline TInt& ClientData1() { return iClientData1; }
+
+ /**
+ * Returns the client data from slot 2 for this alarm.
+ *
+ * @return The second client-specific integer.
+ */
+ inline TInt ClientData2() const { return iClientData2; }
+
+ /**
+ * Returns the client data from slot 2 for this alarm.
+ *
+ * @return The second client-specific integer.
+ */
+ inline TInt& ClientData2() { return iClientData2; }
+
+
+ /**
+ * 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.
+ */
+ inline TBool IsFloating() const { return iCharacteristics.IsClear(EAlarmCharacteristicsIsFixed); }
+
+protected:
+ // Internal Flags
+
+#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
+ /*
+ * @internalAll
+ */
+ enum TASShdAlarmFlags
+ {
+ /**
+ * @publishedAll
+ */
+ EASShdAlarmFlagsHasAssociatedData = 0,
+
+ /**
+ * @publishedAll
+ */
+ EASShdAlarmFlagsHasOwningSession = 1,
+
+ /**
+ * @publishedAll
+ */
+ EASShdAlarmFlagsHasBecomeOrphaned = 2,
+
+ /**
+ * Set if alarm is disabled manually so that can not be enabled when locale changes.
+ *
+ * @publishedAll
+ */
+ EASShdAlarmFlagsPermanentDisabled = 4
+ };
+#endif
+
+private:
+#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
+
+#ifdef SYMBIAN_SYSTEM_STATE_MANAGEMENT
+ /*
+ * @internalComponent
+ */
+ enum TASShdAlarmFlags2
+ {
+ EASShdAlarmFlag2Wakeup = 0,
+ };
+#endif
+
+#ifdef SYMBIAN_ALARM_REPEAT_EXTENSIONS
+ /*
+ * @internalComponent
+ */
+ enum TASShdAlarmFlags2AlarmRepeatExtensions
+ {
+ EASShdAlarmFlag2AlarmDayMonday = 1,
+ EASShdAlarmFlag2AlarmDayTuesday = 2,
+ EASShdAlarmFlag2AlarmDayWednesday = 3,
+ EASShdAlarmFlag2AlarmDayThursday = 4,
+ EASShdAlarmFlag2AlarmDayFriday = 5,
+ EASShdAlarmFlag2AlarmDaySaturday = 6,
+ EASShdAlarmFlag2AlarmDaySunday = 7,
+ EASShdAlarmFlag2Continuous = 8
+ };
+#endif
+
+#endif //SYMBIAN_ENABLE_SPLIT_HEADERS
+
+
+protected:
+
+ /**
+ * 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:
+ // Binary Compatibility Proofing
+ TSecureId iTASShdAlarmSID;
+
+#ifdef SYMBIAN_SYSTEM_STATE_MANAGEMENT
+ /**
+ * Various flags - used internally by the alarm object
+ */
+ TBitFlags16 iFlags2;
+ TUint16 iTASShdAlarm_2;
+#else
+
+#ifdef SYMBIAN_ALARM_REPEAT_EXTENSIONS
+ /**
+ * Various flags - used internally by the alarm object
+ */
+ TBitFlags16 iFlags2;
+ TUint16 iTASShdAlarm_2;
+#else
+ TAny* iTASShdAlarm_2;
+#endif
+#endif
+ TAny* iTASShdAlarm_3;
+ };
+
+#endif // #ifndef __ASSHDALARM_H__