Tizen.Applications/Tizen.Applications/AlarmManager.cs

   1 /*
   2  * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 using System;
  18 using System.Collections.Generic;
  19 using System.Runtime.InteropServices;
  20
  21 namespace Tizen.Applications
  22 {
  23     /// <summary>
  24     /// Enumeration for Alarm Week Flag, the days of the week.
  25     /// </summary>
  26     [Flags]
  27     public enum AlarmWeekFlag
  28     {
  29         /// <summary>
  30         /// Identifier for Sunday.
  31         /// </summary>
  32         Sunday = 0x01,
  33
  34         /// <summary>
  35         /// Identifier for Monday.
  36         /// </summary>
  37         Monday = 0x02,
  38
  39         /// <summary>
  40         /// Identifier for Tuesday.
  41         /// </summary>
  42         Tuesday = 0x04,
  43
  44         /// <summary>
  45         /// Identifier for Wednesday.
  46         /// </summary>
  47         Wednesday = 0x08,
  48
  49         /// <summary>
  50         /// Identifier for Thursday.
  51         /// </summary>
  52         Thursday = 0x10,
  53
  54         /// <summary>
  55         /// Identifier for Friday.
  56         /// </summary>
  57         Friday = 0x20,
  58
  59         /// <summary>
  60         /// Identifier for Saturday.
  61         /// </summary>
  62         Saturday = 0x40,
  63
  64         /// <summary>
  65         /// All Days of the Week.
  66         /// </summary>
  67         AllDays = Sunday |Monday|Tuesday|Wednesday|Thursday|Friday|Saturday,
  68
  69         /// <summary>
  70         /// Only Weekdays
  71         /// </summary>
  72         WeekDays = Monday | Tuesday | Wednesday | Thursday | Friday
  73     }
  74
  75     /// <summary>
  76     /// Mobile devices typically give constant access to information from various sources.Some of this information is best delivered through alarms -
  77     /// the most obvious case is a calendar scheduling application which lets you know when a meeting is about to start.Alarms are certainly better than actively waiting in a loop.
  78     /// They are also better than putting an interface to sleep because they do not block your main UI thread.
  79     /// Use of alarms helps build smooth user experiences and implements unattended data synchronization tasks.
  80     /// If an application is installed after setting the alarm, your alarm is cancelled automatically.
  81     /// </summary>
  82     /// <example>
  83     /// <code>
  84     /// public class AlarmManagerExample
  85     /// {
  86     ///     /// ...
  87     ///     Alarm alarm = AlarmManager.CreateAlarm(24000,1000,null);
  88     ///     AlarmManager.CancelAll();
  89     /// }
  90     /// </code>
  91     /// </example>
  92
  93     public static class AlarmManager
  94     {
  95         private const string LogTag = "Tizen.Applications.Alarm";
  96
  97         private static Interop.Alarm.DateTime ConvertDateTimeToStruct(DateTime value)
  98         {
  99             Interop.Alarm.DateTime time = new Interop.Alarm.DateTime();
 100             time.sec = value.Second;
 101             time.min = value.Minute;
 102             time.hour = value.Hour;
 103             time.mday = value.Day;
 104             time.mon = value.Month - 1;
 105             time.year = value.Year - 1900;
 106             time.wday = (int)value.DayOfWeek;
 107             time.yday = value.DayOfYear;
 108             time.isdst = 0;
 109             return time;
 110         }
 111
 112         internal static DateTime ConvertIntPtrToDateTime(Interop.Alarm.DateTime time)
 113         {
 114             DateTime value = new DateTime(1900 + time.year, 1 + time.mon, time.mday, time.hour, time.min, time.sec, DateTimeKind.Utc);
 115             return value;
 116         }
 117
 118         /// <summary>
 119         /// Sets an alarm to be triggered after a specific time.
 120         /// The alarm will first go off delay seconds later and then will go off every certain amount of time defined using period seconds.
 121         /// </summary>
 122         /// <param name="delay">The amount of time before the first execution (in seconds).</param>
 123         /// <param name="period"> The amount of time between subsequent alarms (in seconds). This value does not guarantee the accuracy.
 124         /// The actual interval is calculated by the OS. The minimum value is 600sec</param>
 125         /// <param name="appControl"> The destination AppControl to perform a specific task when the alarm is triggered </param>
 126         /// <returns>Alarm Instance created with the set param values.</returns>
 127         /// <exception cref="ArgumentException">Thrown in case of Invalid parmaeter.</exception>
 128         /// <exception cref="UnauthorizedAccessException">Thrown in case of permission denied.</exception>
 129         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 130         /// <privilege>http://tizen.org/privilege/alarm.set</privilege>
 131         public static Alarm CreateAlarm(int delay, int period, AppControl appControl)
 132         {
 133             Alarm alarm = null;
 134             int alarmId;
 135             SafeAppControlHandle handle = (appControl == null) ? null : appControl.SafeAppControlHandle;
 136             AlarmError ret = (AlarmError)Interop.Alarm.CreateAlarmAfterDelay(handle, delay, period, out alarmId);
 137             alarm = new Alarm(alarmId);
 138             if (ret != AlarmError.None)
 139             {
 140                 throw AlarmErrorFactory.GetException(ret, "Failed to create Alarm");
 141             }
 142
 143             return alarm;
 144         }
 145
 146         /// <summary>
 147         /// Sets an alarm to be triggered after a specific time.
 148         /// The alarm will go off delay seconds later.
 149         /// </summary>
 150         /// <param name="delay"> The amount of time before the execution (in seconds) </param>
 151         /// <param name="appControl"> The destination AppControl to perform a specific task when the alarm is triggered </param>
 152         /// <returns> Alarm Instance created with the set param values.</returns>
 153         /// <exception cref="ArgumentException">Thrown in case of Invalid parmaeter.</exception>
 154         /// <exception cref="UnauthorizedAccessException">Thrown in case of permission denied.</exception>
 155         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 156         /// <privilege>http://tizen.org/privilege/alarm.set</privilege>
 157         public static Alarm CreateAlarm(int delay, AppControl appControl)
 158         {
 159             Alarm alarm = null;
 160             int alarmId;
 161             AlarmError ret = (AlarmError)Interop.Alarm.CreateAlarmOnceAfterDelay(appControl.SafeAppControlHandle, delay, out alarmId);
 162             alarm = new Alarm(alarmId);
 163             if (ret != AlarmError.None)
 164             {
 165                 throw AlarmErrorFactory.GetException(ret, "Failed to create Alarm");
 166             }
 167
 168             return alarm;
 169         }
 170
 171         /// <summary>
 172         /// Sets an alarm to be triggered at a specific time.
 173         /// The date describes the time of the first occurrence.
 174         /// </summary>
 175         /// <param name="value"> The first active alarm time </param>
 176         /// <param name="appControl"> The destination AppControl to perform specific work when the alarm is triggered </param>
 177         /// <returns> Alarm Instance created with the set param values.</returns>
 178         /// <remarks>This operation is permitted wit UI application appcontrol only.</remarks>
 179         /// <exception cref="ArgumentException">Thrown in case of Invalid parmaeter.</exception>
 180         /// <exception cref="UnauthorizedAccessException">Thrown in case of permission denied.</exception>
 181         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 182         /// <privilege>http://tizen.org/privilege/alarm.set</privilege>
 183         public static Alarm CreateAlarm(DateTime value, AppControl appControl)
 184         {
 185             Alarm alarm = null;
 186             int alarmId;
 187             Interop.Alarm.DateTime time = ConvertDateTimeToStruct(value);
 188             AlarmError ret = (AlarmError)Interop.Alarm.CreateAlarmOnceAtDate(appControl.SafeAppControlHandle, ref time, out alarmId);
 189             alarm = new Alarm(alarmId);
 190             if (ret != AlarmError.None)
 191             {
 192                 throw AlarmErrorFactory.GetException(ret, "Failed to create Alarm");
 193             }
 194
 195             return alarm;
 196         }
 197
 198         /// <summary>
 199         /// Sets an alarm to be triggered periodically, starting at a specific time.
 200         /// The date describes the time of the first occurrence.
 201         /// weekFlag is the repeat value of the days of the week.
 202         /// If weekFlag is AlarmWeekFlag.Tuesday, the alarm will repeat every Tuesday at a specific time.
 203         /// </summary>
 204         /// <remarks>This operation is permitted wit UI application appcontrol only.</remarks>
 205         /// <param name="value"> The first active alarm time </param>
 206         /// <param name="weekFlag"> The day of the week, AlarmWeekFlag may be a combination of days, like AlarmWeekFlag.Sunday | AlarmWeekFlag.Monday</param>
 207         /// <param name="appControl"> The destination AppControl to perform specific work when the alarm is triggered </param>
 208         /// <returns> Alarm Instance created with the set param values.</returns>
 209         /// <exception cref="ArgumentException">Thrown in case of Invalid parmaeter.</exception>
 210         /// <exception cref="UnauthorizedAccessException">Thrown in case of permission denied.</exception>
 211         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 212         /// <privilege>http://tizen.org/privilege/alarm.set</privilege>
 213         public static Alarm CreateAlarm(DateTime value, AlarmWeekFlag weekFlag, AppControl appControl)
 214         {
 215             Alarm alarm = null;
 216             int alarmId;
 217             Interop.Alarm.DateTime time = ConvertDateTimeToStruct(value);
 218             AlarmError ret = (AlarmError)Interop.Alarm.CreateAlarmRecurWeek(appControl.SafeAppControlHandle, ref time, (int)weekFlag, out alarmId);
 219             alarm = new Alarm(alarmId);
 220             if (ret != AlarmError.None)
 221             {
 222                 throw AlarmErrorFactory.GetException(ret, "Failed to create Alarm");
 223             }
 224
 225             return alarm;
 226         }
 227
 228         /// <summary>
 229         /// Cancels all scheduled alarms that are registered by the application that calls this API.
 230         /// </summary>
 231         /// <exception cref="UnauthorizedAccessException">Thrown in case of permission denied.</exception>
 232         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 233         /// <privilege>http://tizen.org/privilege/alarm.set</privilege>
 234         public static void CancelAll()
 235         {
 236             AlarmError ret = (AlarmError)Interop.Alarm.CancelAllAlarms();
 237             if (ret != AlarmError.None)
 238             {
 239                 throw AlarmErrorFactory.GetException(ret, "Failed to cancel Alarms");
 240             }
 241         }
 242
 243         /// <summary>
 244         /// Retrieves all registered alarms.
 245         /// </summary>
 246         /// <returns>List of all Alarm instances.</returns>
 247         /// <exception cref="UnauthorizedAccessException">Thrown in case of permission denied.</exception>
 248         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 249         /// <privilege>http://tizen.org/privilege/alarm.get</privilege>
 250         public static IEnumerable<Alarm> GetAllSceduledAlarms()
 251         {
 252             List<Alarm> alarms = new List<Alarm>();
 253             Interop.Alarm.RegisteredAlarmCallback callback = (int alarmId, IntPtr userData) =>
 254             {
 255                 alarms.Add(new Alarm(alarmId));
 256                 return true;
 257             };
 258
 259             AlarmError ret = (AlarmError)Interop.Alarm.GetAllRegisteredAlarms(callback, IntPtr.Zero);
 260             if (ret != AlarmError.None)
 261             {
 262                 throw AlarmErrorFactory.GetException(ret, "Failed to get Alarms");
 263             }
 264
 265             return alarms;
 266         }
 267
 268         /// <summary>
 269         /// Gets the current system time.
 270         /// </summary>
 271         /// <returns>The current system time</returns>
 272         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 273         public static DateTime GetCurrentTime()
 274         {
 275             DateTime time;
 276             Interop.Alarm.DateTime value;
 277             AlarmError ret = (AlarmError)Interop.Alarm.GetCurrentTime(out value);
 278             if (ret != AlarmError.None)
 279             {
 280                 throw AlarmErrorFactory.GetException(ret, "Failed to get Currenttime");
 281             }
 282             else
 283             {
 284
 285                 time = ConvertIntPtrToDateTime(value);
 286             }
 287
 288             return time;
 289         }
 290
 291     }
 292 }