commonappservices/alarmserver/Shared/Include/ASShdAlarm.h
changeset 0 2e3d3ce01487
equal deleted inserted replaced
-1:000000000000 0:2e3d3ce01487
       
     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__