src/Tizen.Applications.Alarm/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 namespace Tizen.Applications
  18 {
  19     using System;
  20     using System.Collections.Generic;
  21     using System.Runtime.InteropServices;
  22     using Tizen.Applications.Notifications;
  23
  24     /// <summary>
  25     /// Enumeration for Alarm Week Flag, the days of the week.
  26     /// </summary>
  27     [Flags]
  28     public enum AlarmWeekFlag
  29     {
  30         /// <summary>
  31         /// Identifier for Sunday.
  32         /// </summary>
  33         Sunday = 0x01,
  34
  35         /// <summary>
  36         /// Identifier for Monday.
  37         /// </summary>
  38         Monday = 0x02,
  39
  40         /// <summary>
  41         /// Identifier for Tuesday.
  42         /// </summary>
  43         Tuesday = 0x04,
  44
  45         /// <summary>
  46         /// Identifier for Wednesday.
  47         /// </summary>
  48         Wednesday = 0x08,
  49
  50         /// <summary>
  51         /// Identifier for Thursday.
  52         /// </summary>
  53         Thursday = 0x10,
  54
  55         /// <summary>
  56         /// Identifier for Friday.
  57         /// </summary>
  58         Friday = 0x20,
  59
  60         /// <summary>
  61         /// Identifier for Saturday.
  62         /// </summary>
  63         Saturday = 0x40,
  64
  65         /// <summary>
  66         /// All Days of the Week.
  67         /// </summary>
  68         AllDays = Sunday |Monday|Tuesday|Wednesday|Thursday|Friday|Saturday,
  69
  70         /// <summary>
  71         /// Only Weekdays
  72         /// </summary>
  73         WeekDays = Monday | Tuesday | Wednesday | Thursday | Friday
  74     }
  75
  76     /// <summary>
  77     /// Mobile devices typically give constant access to information from various sources.Some of this information is best delivered through alarms -
  78     /// 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.
  79     /// They are also better than putting an interface to sleep because they do not block your main UI thread.
  80     /// Use of alarms helps build smooth user experiences and implements unattended data synchronization tasks.
  81     /// If an application is installed after setting the alarm, your alarm is cancelled automatically.
  82     /// </summary>
  83     /// <example>
  84     /// <code>
  85     /// public class AlarmManagerExample
  86     /// {
  87     ///     /// ...
  88     ///     Alarm alarm = AlarmManager.CreateAlarm(24000,1000,null);
  89     ///     AlarmManager.CancelAll();
  90     /// }
  91     /// </code>
  92     /// </example>
  93
  94     public static class AlarmManager
  95     {
  96         private const string LogTag = "Tizen.Applications.Alarm";
  97
  98         private static Interop.Alarm.DateTime ConvertDateTimeToStruct(DateTime value)
  99         {
 100             Interop.Alarm.DateTime time = new Interop.Alarm.DateTime();
 101             time.sec = value.Second;
 102             time.min = value.Minute;
 103             time.hour = value.Hour;
 104             time.mday = value.Day;
 105             time.mon = value.Month - 1;
 106             time.year = value.Year - 1900;
 107             time.wday = (int)value.DayOfWeek;
 108             time.yday = value.DayOfYear;
 109             time.isdst = 0;
 110             return time;
 111         }
 112
 113         internal static DateTime ConvertIntPtrToDateTime(Interop.Alarm.DateTime time)
 114         {
 115             DateTime value = new DateTime(1900 + time.year, 1 + time.mon, time.mday, time.hour, time.min, time.sec, DateTimeKind.Utc);
 116             return value;
 117         }
 118
 119         /// <summary>
 120         /// Sets an alarm to be triggered after a specific time.
 121         /// The alarm will first go off delay seconds later and then will go off every certain amount of time defined using period seconds.
 122         /// </summary>
 123         /// <param name="delay">The amount of time before the first execution (in seconds).</param>
 124         /// <param name="period"> The amount of time between subsequent alarms (in seconds). This value does not guarantee the accuracy.
 125         /// The actual interval is calculated by the OS. The minimum value is 600sec</param>
 126         /// <param name="appControl"> The destination AppControl to perform a specific task when the alarm is triggered </param>
 127         /// <returns>Alarm Instance created with the set param values.</returns>
 128         /// <exception cref="ArgumentException">Thrown in case of Invalid parameter.</exception>
 129         /// <exception cref="UnauthorizedAccessException">Thrown in case of permission denied.</exception>
 130         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 131         /// <privilege>http://tizen.org/privilege/alarm.set</privilege>
 132         public static Alarm CreateAlarm(int delay, int period, AppControl appControl)
 133         {
 134             Alarm alarm = null;
 135             int alarmId;
 136             SafeAppControlHandle handle = (appControl == null) ? null : appControl.SafeAppControlHandle;
 137             AlarmError ret = (AlarmError)Interop.Alarm.CreateAlarmAfterDelay(handle, delay, period, out alarmId);
 138             alarm = new Alarm(alarmId);
 139             if (ret != AlarmError.None)
 140             {
 141                 throw AlarmErrorFactory.GetException(ret, "Failed to create Alarm");
 142             }
 143
 144             return alarm;
 145         }
 146
 147         /// <summary>
 148         /// Sets an alarm to be triggered after a specific time.
 149         /// The alarm will go off delay seconds later.
 150         /// </summary>
 151         /// <param name="delay"> The amount of time before the execution (in seconds) </param>
 152         /// <param name="appControl"> The destination AppControl to perform a specific task when the alarm is triggered </param>
 153         /// <returns> Alarm Instance created with the set param values.</returns>
 154         /// <exception cref="ArgumentException">Thrown in case of Invalid parameter.</exception>
 155         /// <exception cref="UnauthorizedAccessException">Thrown in case of permission denied.</exception>
 156         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 157         /// <privilege>http://tizen.org/privilege/alarm.set</privilege>
 158         public static Alarm CreateAlarm(int delay, AppControl appControl)
 159         {
 160             Alarm alarm = null;
 161             int alarmId;
 162             AlarmError ret = (AlarmError)Interop.Alarm.CreateAlarmOnceAfterDelay(appControl.SafeAppControlHandle, delay, out alarmId);
 163             alarm = new Alarm(alarmId);
 164             if (ret != AlarmError.None)
 165             {
 166                 throw AlarmErrorFactory.GetException(ret, "Failed to create Alarm");
 167             }
 168
 169             return alarm;
 170         }
 171
 172         /// <summary>
 173         /// Sets an alarm to be triggered at a specific time.
 174         /// The date describes the time of the first occurrence.
 175         /// </summary>
 176         /// <param name="value"> The first active alarm time </param>
 177         /// <param name="appControl"> The destination AppControl to perform specific work when the alarm is triggered </param>
 178         /// <returns> Alarm Instance created with the set param values.</returns>
 179         /// <remarks>This operation is permitted wit UI application appcontrol only.</remarks>
 180         /// <exception cref="ArgumentException">Thrown in case of Invalid parameter.</exception>
 181         /// <exception cref="UnauthorizedAccessException">Thrown in case of permission denied.</exception>
 182         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 183         /// <privilege>http://tizen.org/privilege/alarm.set</privilege>
 184         public static Alarm CreateAlarm(DateTime value, AppControl appControl)
 185         {
 186             Alarm alarm = null;
 187             int alarmId;
 188             Interop.Alarm.DateTime time = ConvertDateTimeToStruct(value);
 189             AlarmError ret = (AlarmError)Interop.Alarm.CreateAlarmOnceAtDate(appControl.SafeAppControlHandle, ref time, out alarmId);
 190             alarm = new Alarm(alarmId);
 191             if (ret != AlarmError.None)
 192             {
 193                 throw AlarmErrorFactory.GetException(ret, "Failed to create Alarm");
 194             }
 195
 196             return alarm;
 197         }
 198
 199         /// <summary>
 200         /// Sets an alarm to be triggered periodically, starting at a specific time.
 201         /// The date describes the time of the first occurrence.
 202         /// weekFlag is the repeat value of the days of the week.
 203         /// If weekFlag is AlarmWeekFlag.Tuesday, the alarm will repeat every Tuesday at a specific time.
 204         /// </summary>
 205         /// <remarks>This operation is permitted wit UI application appcontrol only.</remarks>
 206         /// <param name="value"> The first active alarm time </param>
 207         /// <param name="weekFlag"> The day of the week, AlarmWeekFlag may be a combination of days, like AlarmWeekFlag.Sunday | AlarmWeekFlag.Monday</param>
 208         /// <param name="appControl"> The destination AppControl to perform specific work when the alarm is triggered </param>
 209         /// <returns> Alarm Instance created with the set param values.</returns>
 210         /// <exception cref="ArgumentException">Thrown in case of Invalid parameter.</exception>
 211         /// <exception cref="UnauthorizedAccessException">Thrown in case of permission denied.</exception>
 212         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 213         /// <privilege>http://tizen.org/privilege/alarm.set</privilege>
 214         public static Alarm CreateAlarm(DateTime value, AlarmWeekFlag weekFlag, AppControl appControl)
 215         {
 216             Alarm alarm = null;
 217             int alarmId;
 218             Interop.Alarm.DateTime time = ConvertDateTimeToStruct(value);
 219             AlarmError ret = (AlarmError)Interop.Alarm.CreateAlarmRecurWeek(appControl.SafeAppControlHandle, ref time, (int)weekFlag, out alarmId);
 220             alarm = new Alarm(alarmId);
 221             if (ret != AlarmError.None)
 222             {
 223                 throw AlarmErrorFactory.GetException(ret, "Failed to create Alarm");
 224             }
 225
 226             return alarm;
 227         }
 228
 229         /// <summary>
 230         /// Sets a notification alarm to be triggered at a specific time.
 231         /// The date describes the time of the first occurrence.
 232         /// </summary>
 233         /// <param name="dateTime"> The first active alarm time </param>
 234         /// <param name="notification"> The notification to be posted when the alarm is triggered </param>
 235         /// <returns> Alarm Instance created with the set param values.</returns>
 236         /// <exception cref="ArgumentException">Thrown in case of Invalid parameter.</exception>
 237         /// <exception cref="UnauthorizedAccessException">Thrown in case of permission denied.</exception>
 238         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 239         /// <privilege>http://tizen.org/privilege/alarm.set</privilege>
 240         /// <privilege>http://tizen.org/privilege/notification</privilege>
 241         public static Alarm CreateAlarm(DateTime dateTime, Notification notification)
 242         {
 243             Alarm alarm = null;
 244             int alarmId;
 245             NotificationSafeHandle safeHandle = NotificationManager.MakeNotificationSafeHandle(notification);
 246             Interop.Alarm.DateTime time = ConvertDateTimeToStruct(dateTime);
 247             AlarmError ret = Interop.Alarm.CreateAlarmNotiOnceAtDate(safeHandle, ref time, out alarmId);
 248             if (ret != AlarmError.None)
 249             {
 250                 throw AlarmErrorFactory.GetException(ret, "Failed to create Alarm");
 251             }
 252
 253             alarm = new Alarm(alarmId);
 254
 255             return alarm;
 256         }
 257
 258         /// <summary>
 259         /// Sets a notification alarm to be triggered after a specific time.
 260         /// The alarm will first go off delay seconds later and then will go off every certain amount of time defined using period seconds.
 261         /// </summary>
 262         /// <param name="delay">The amount of time before the first execution (in seconds). </param>
 263         /// <param name="period"> The amount of time between subsequent alarms (in seconds). This value does not guarantee the accuracy. </param>
 264         /// <param name="notification"> The notification to be posted when the alarm is triggered </param>
 265         /// <returns> Alarm Instance created with the set param values.</returns>
 266         /// <exception cref="ArgumentException">Thrown in case of Invalid parameter.</exception>
 267         /// <exception cref="UnauthorizedAccessException">Thrown in case of permission denied.</exception>
 268         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 269         /// <privilege>http://tizen.org/privilege/alarm.set</privilege>
 270         /// <privilege>http://tizen.org/privilege/notification</privilege>
 271         public static Alarm CreateAlarm(int delay, int period, Notification notification)
 272         {
 273             Alarm alarm = null;
 274             int alarmId;
 275             NotificationSafeHandle safeHandle = NotificationManager.MakeNotificationSafeHandle(notification);
 276             AlarmError ret = Interop.Alarm.CreateAlarmNotiAfterDelay(safeHandle, delay, period, out alarmId);
 277             if (ret != AlarmError.None)
 278             {
 279                 throw AlarmErrorFactory.GetException(ret, "Failed to create Alarm");
 280             }
 281
 282             alarm = new Alarm(alarmId);
 283
 284             return alarm;
 285         }
 286
 287         /// <summary>
 288         /// Sets a notification alarm to be triggered periodically, starting at a specific time.
 289         /// The date describes the time of the first occurrence.
 290         /// weekFlag is the repeat value of the days of the week.
 291         /// If weekFlag is AlarmWeekFlag.Tuesday, the alarm will repeat every Tuesday at a specific time.
 292         /// </summary>
 293         /// <param name="dateTime"> The first active alarm time </param>
 294         /// <param name="weekFlag"> The day of the week, AlarmWeekFlag may be a combination of days,
 295         ///                         like AlarmWeekFlag.Sunday | AlarmWeekFlag.Monday</param>
 296         /// <param name="notification"> The notification to be posted when the alarm is triggered </param>
 297         /// <returns> Alarm Instance created with the set param values.</returns>
 298         /// <exception cref="ArgumentException">Thrown in case of Invalid parameter.</exception>
 299         /// <exception cref="UnauthorizedAccessException">Thrown in case of permission denied.</exception>
 300         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 301         /// <privilege>http://tizen.org/privilege/alarm.set</privilege>
 302         /// <privilege>http://tizen.org/privilege/notification</privilege>
 303         public static Alarm CreateAlarm(DateTime dateTime, AlarmWeekFlag weekFlag, Notification notification)
 304         {
 305             Alarm alarm = null;
 306             int alarmId;
 307             NotificationSafeHandle safeHandle = NotificationManager.MakeNotificationSafeHandle(notification);
 308             Interop.Alarm.DateTime time = ConvertDateTimeToStruct(dateTime);
 309             AlarmError ret = Interop.Alarm.CreateAlarmNotiRecurWeek(safeHandle, ref time, (int)weekFlag, out alarmId);
 310             if (ret != AlarmError.None)
 311             {
 312                 throw AlarmErrorFactory.GetException(ret, "Failed to create Alarm");
 313             }
 314
 315             alarm = new Alarm(alarmId);
 316
 317             return alarm;
 318         }
 319
 320         /// <summary>
 321         /// Sets a notification alarm to be triggered after a specific time.
 322         /// The alarm will go off delay seconds later.
 323         /// </summary>
 324         /// <param name="delay">The amount of time before the first execution (in seconds).</param>
 325         /// <param name="notification"> The notification to be posted when the alarm is triggered </param>
 326         /// <returns> Alarm Instance created with the set param values.</returns>
 327         /// <exception cref="ArgumentException">Thrown in case of Invalid parameter.</exception>
 328         /// <exception cref="UnauthorizedAccessException">Thrown in case of permission denied.</exception>
 329         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 330         /// <privilege>http://tizen.org/privilege/alarm.set</privilege>
 331         /// <privilege>http://tizen.org/privilege/notification</privilege>
 332         public static Alarm CreateAlarm(int delay, Notification notification)
 333         {
 334             Alarm alarm = null;
 335             int alarmId;
 336             NotificationSafeHandle safeHandle = NotificationManager.MakeNotificationSafeHandle(notification);
 337             AlarmError ret = Interop.Alarm.CreateAlarmNotiOnceAfterDelay(safeHandle, delay, out alarmId);
 338             if (ret != AlarmError.None)
 339             {
 340                 throw AlarmErrorFactory.GetException(ret, "Failed to create Alarm");
 341             }
 342
 343             alarm = new Alarm(alarmId);
 344
 345             return alarm;
 346         }
 347
 348         /// <summary>
 349         /// Cancels all scheduled alarms that are registered by the application that calls this API.
 350         /// </summary>
 351         /// <exception cref="UnauthorizedAccessException">Thrown in case of permission denied.</exception>
 352         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 353         /// <privilege>http://tizen.org/privilege/alarm.set</privilege>
 354         public static void CancelAll()
 355         {
 356             AlarmError ret = (AlarmError)Interop.Alarm.CancelAllAlarms();
 357             if (ret != AlarmError.None)
 358             {
 359                 throw AlarmErrorFactory.GetException(ret, "Failed to cancel Alarms");
 360             }
 361         }
 362
 363         /// <summary>
 364         /// Retrieves all registered alarms.
 365         /// </summary>
 366         /// <returns>List of all Alarm instances.</returns>
 367         /// <exception cref="UnauthorizedAccessException">Thrown in case of permission denied.</exception>
 368         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 369         /// <privilege>http://tizen.org/privilege/alarm.get</privilege>
 370         public static IEnumerable<Alarm> GetAllScheduledAlarms()
 371         {
 372             List<Alarm> alarms = new List<Alarm>();
 373             Interop.Alarm.RegisteredAlarmCallback callback = (int alarmId, IntPtr userData) =>
 374             {
 375                 alarms.Add(new Alarm(alarmId));
 376                 return true;
 377             };
 378
 379             AlarmError ret = (AlarmError)Interop.Alarm.GetAllRegisteredAlarms(callback, IntPtr.Zero);
 380             if (ret != AlarmError.None)
 381             {
 382                 throw AlarmErrorFactory.GetException(ret, "Failed to get Alarms");
 383             }
 384
 385             return alarms;
 386         }
 387
 388         /// <summary>
 389         /// Gets the current system time.
 390         /// </summary>
 391         /// <returns>The current system time</returns>
 392         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
 393         public static DateTime GetCurrentTime()
 394         {
 395             DateTime time;
 396             Interop.Alarm.DateTime value;
 397             AlarmError ret = (AlarmError)Interop.Alarm.GetCurrentTime(out value);
 398             if (ret != AlarmError.None)
 399             {
 400                 throw AlarmErrorFactory.GetException(ret, "Failed to get Currenttime");
 401             }
 402             else
 403             {
 404
 405                 time = ConvertIntPtrToDateTime(value);
 406             }
 407
 408             return time;
 409         }
 410
 411     }
 412 }