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