master -> DevelNUI

src/Tizen.Applications.Alarm/Interop/Interop.Alarm.cs

@@ -54,6 +54,15 @@ internal struct DateTime
         [DllImport(Libraries.Alarm, EntryPoint = "alarm_schedule_with_recurrence_week_flag")]
         internal static extern int CreateAlarmRecurWeek(SafeAppControlHandle appControl, ref DateTime date, int week, out int alarmId);
 
+        [DllImport(Libraries.Alarm, EntryPoint = "alarm_schedule_service_with_recurrence_seconds")]
+        internal static extern int CreateAlarmRecurForService(SafeAppControlHandle appControl, ref DateTime date, int period, out int alarmId);
+
+        [DllImport(Libraries.Alarm, EntryPoint = "alarm_schedule_service_once_after_delay")]
+        internal static extern int CreateAlarmOnceAfterDelayForService(SafeAppControlHandle appControl, int delay, out int alarmId);
+
+        [DllImport(Libraries.Alarm, EntryPoint = "alarm_schedule_service_once_at_date")]
+        internal static extern int CreateAlarmOnceAtDateForService(SafeAppControlHandle appControl, ref DateTime date, out int alarmId);
+
         [DllImport(Libraries.Alarm, EntryPoint = "alarm_get_scheduled_recurrence_week_flag")]
         internal static extern int GetAlarmWeekFlag(int alarmId, out int weekFlag);
 

src/Tizen.Applications.Alarm/Tizen.Applications/Alarm.cs

@@ -61,14 +61,17 @@ public int AlarmId
         /// <privilege>http://tizen.org/privilege/alarm.get</privilege>
         /// <remarks>
         /// The setter for <c>WeekFlag</c> property is available since API Level 6.
-        /// Weekflag can be a combination of the days of the week, for example Tuesday | Friday.
-        /// If the period is already set, it will be removed and the week repetition flag will be set.
-        /// If the week repetition flag is already set, it will be overwritten. If not, it will be set.
+        /// Weekflag can represent a combination of days of the week, such as Tuesday | Friday.
+        /// If the period is already set, it will be removed and the week repetition flag will be set instead.
+        /// If the week repetition flag is already set, it will be overwritten. Otherwise, it will be set.
         /// If the Weekflag argument is 0 and the flag is already set,
-        /// the flag will be cleared and the alarm will be changed to set once.
-        /// If the Weekflag argument is 0, and the flag is not set or the period is set,
-        /// the alarm won't be changed.
+        /// the flag will be cleared and the alarm will be changed to a single occurrence.
+        /// If the Weekflag argument is 0 and no flag is set or if the period is set,
+        /// the alarm will remain unchanged.
         /// </remarks>
+        /// <exception cref="ArgumentException">Thrown in case of an invalid parmaeter.</exception>
+        /// <exception cref="UnauthorizedAccessException">Thrown in case of a permission denied due to insufficient privileges.</exception>
+        /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
         /// <since_tizen> 3 </since_tizen>
         public AlarmWeekFlag WeekFlag
         {
@@ -103,6 +106,9 @@ public AlarmWeekFlag WeekFlag
         /// <remarks>
         /// The <c>SchduleDate</c> property setter is available since API Level 6.
         /// </remarks>
+        /// <exception cref="ArgumentException">Thrown in case of an invalid parmaeter.</exception>
+        /// <exception cref="UnauthorizedAccessException">Thrown in case of a permission denied due to insufficient privileges.</exception>
+        /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
         /// <since_tizen> 3 </since_tizen>
         public DateTime ScheduledDate
         {
@@ -141,19 +147,22 @@ public DateTime ScheduledDate
         }
 
         /// <summary>
-        /// Gets the period of time between the recurrent alarms.
+        /// Gets or sets the period of time between the recurrent alarms.
         /// </summary>
         /// <privilege>http://tizen.org/privilege/alarm.set</privilege>
         /// <privilege>http://tizen.org/privilege/alarm.get</privilege>
         /// <remarks>
         /// The <c>Period</c> property setter is available since API Level 6.
         /// If the week recurrence flag was set before, it will be removed and the period will be set
-        /// If the period was set before, it will be overwritten.If it was not, it will be set.
+        /// If the period was set before, it will be overwritten. If it was not, it will be set.
         /// If the @a period argument is 0 and the period was previously set,
         /// the period attribute will be cleared and the alarm will be changed to one-time.
         /// If the @a period argument is 0 and the period was not set,
-        /// or the week recurrence flag was set, the alarm will be unchanged.
+        /// or the week recurrence flag was set, the alarm will remain unchanged.
         /// </remarks>
+        /// <exception cref="ArgumentException">Thrown in case of an invalid parmaeter.</exception>
+        /// <exception cref="UnauthorizedAccessException">Thrown in case of a permission denied due to insufficient privileges.</exception>
+        /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
         /// <since_tizen> 3 </since_tizen>
         public int Period
         {

src/Tizen.Applications.Alarm/Tizen.Applications/AlarmManager.cs

@@ -18,6 +18,7 @@ namespace Tizen.Applications
 {
     using System;
     using System.Collections.Generic;
+    using System.ComponentModel;
     using System.Runtime.InteropServices;
     using Tizen.Applications.Notifications;
 
@@ -102,7 +103,7 @@ public enum AlarmStandardPeriod
     }
 
     /// <summary>
-    /// Mobile devices typically give constant access to information from various sources. Some of this information is best delivered through alarms.
+    /// Devices typically give constant access to information from various sources. Some of this information is best delivered through alarms.
     /// 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.
     /// They are also better than putting an interface to sleep because they do not block your main UI thread.
     /// Use of alarms helps build smooth user experiences and implements unattended data synchronization tasks.
@@ -149,7 +150,7 @@ internal static DateTime ConvertIntPtrToDateTime(Interop.Alarm.DateTime time)
         /// Sets an alarm to be triggered after a specific time.
         /// The alarm will first go off delay seconds later and then will go off every certain amount of time defined using period seconds.
         /// </summary>
-        /// <param name="delay">The amount of time before the first execution (in seconds).</param>
+        /// <param name="delay">The amount of time before the first execution (in seconds). Although this is inexact, the alarm will not fire before this time</param>
         /// <param name="period"> The amount of time between subsequent alarms (in seconds). This value does not guarantee the accuracy.
         /// The actual interval is calculated by the OS. The minimum value is 600sec.</param>
         /// <param name="appControl"> The destination AppControl is used to perform a specific task when the alarm is triggered. </param>
@@ -185,6 +186,7 @@ public static Alarm CreateAlarm(int delay, int period, AppControl appControl)
         /// <param name="delay"> The amount of time before the execution (in seconds). </param>
         /// <param name="appControl"> The destination AppControl to perform a specific task when the alarm is triggered. </param>
         /// <returns> An alarm instance is created with the set param values.</returns>
+        /// <remarks>This operation is permitted with the UI application appcontrol only.</remarks>
         /// <exception cref="ArgumentException">Thrown in case of an invalid parameter.</exception>
         /// <exception cref="UnauthorizedAccessException">Thrown in case of a permission denied.</exception>
         /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
@@ -330,7 +332,7 @@ public static Alarm CreateAlarm(DateTime dateTime, Notification notification)
         /// Sets a notification alarm to be triggered after a specific time.
         /// The alarm will first go off delay seconds later and then will go off every certain amount of time defined using period seconds.
         /// </summary>
-        /// <param name="delay">The amount of time before the first execution (in seconds). </param>
+        /// <param name="delay">The amount of time before the first execution (in seconds). Although this is inexact, the alarm will not fire before this time</param>
         /// <param name="period"> The amount of time between subsequent alarms (in seconds). This value does not guarantee the accuracy. </param>
         /// <param name="notification"> The notification to be posted when the alarm is triggered. </param>
         /// <returns> An alarm instance is created with the set param values.</returns>
@@ -438,6 +440,119 @@ public static Alarm CreateAlarm(int delay, AlarmStandardPeriod standardPeriod, N
             return CreateAlarm(delay, (int)standardPeriod, notification);
         }
 
+        /// <summary>
+        /// Sets an alarm to be triggered after a specific time.
+        /// The alarm will go off delay seconds later.
+        /// </summary>
+        /// <param name="delay"> The amount of time before the execution (in seconds). </param>
+        /// <param name="appControl"> The destination AppControl to perform a specific task when the alarm is triggered. </param>
+        /// <returns> An alarm instance is created with the set param values.</returns>
+        /// <remarks>
+        /// This operation only allows service application which has Background Category to set an exact alarm.
+        /// </remarks>
+        /// <exception cref="ArgumentException">Thrown in case of an invalid parameter.</exception>
+        /// <exception cref="UnauthorizedAccessException">Thrown in case of a permission denied.</exception>
+        /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
+        /// <privilege>http://tizen.org/privilege/alarm.set</privilege>
+        /// <privilege>http://tizen.org/privilege/appmanager.launch</privilege>
+        /// <since_tizen> 12 </since_tizen>
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        public static Alarm CreateAlarmForServiceApp(int delay, AppControl appControl)
+        {
+            if (appControl == null)
+            {
+                throw AlarmErrorFactory.GetException(AlarmError.InvalidParameter, "AppControl should be not null");
+            }
+
+            Alarm alarm = null;
+            int alarmId;
+            AlarmError ret = (AlarmError)Interop.Alarm.CreateAlarmOnceAfterDelayForService(appControl.SafeAppControlHandle, delay, out alarmId);
+            alarm = new Alarm(alarmId);
+            if (ret != AlarmError.None)
+            {
+                throw AlarmErrorFactory.GetException(ret, "Failed to create Alarm");
+            }
+
+            return alarm;
+        }
+
+        /// <summary>
+        /// Sets an alarm to be triggered at a specific time.
+        /// The date describes the time of the first occurrence.
+        /// </summary>
+        /// <param name="value"> The first active alarm time. </param>
+        /// <param name="appControl"> The destination AppControl to perform specific work when the alarm is triggered. </param>
+        /// <returns> An alarm instance is created with the set param values.</returns>
+        /// <remarks>
+        /// This operation only allows service application which has Background Category to set an exact alarm.
+        /// </remarks>
+        /// <exception cref="ArgumentException">Thrown in case of an invalid parameter.</exception>
+        /// <exception cref="UnauthorizedAccessException">Thrown in case of a permission denied.</exception>
+        /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
+        /// <privilege>http://tizen.org/privilege/alarm.set</privilege>
+        /// <privilege>http://tizen.org/privilege/appmanager.launch</privilege>
+        /// <since_tizen> 12 </since_tizen>
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        public static Alarm CreateAlarmForServiceApp(DateTime value, AppControl appControl)
+        {
+            if (appControl == null)
+            {
+                throw AlarmErrorFactory.GetException(AlarmError.InvalidParameter, "AppControl should be not null");
+            }
+
+            Alarm alarm = null;
+            int alarmId;
+            Interop.Alarm.DateTime time = ConvertDateTimeToStruct(value);
+            AlarmError ret = (AlarmError)Interop.Alarm.CreateAlarmOnceAtDateForService(appControl.SafeAppControlHandle, ref time, out alarmId);
+            alarm = new Alarm(alarmId);
+            if (ret != AlarmError.None)
+            {
+                throw AlarmErrorFactory.GetException(ret, "Failed to create Alarm");
+            }
+
+            return alarm;
+        }
+
+        /// <summary>
+        /// Sets an alarm to be triggered at a specific time.
+        /// The alarm will first go off at a specific time and then will go off every certain amount of time defined using period seconds.
+        /// </summary>
+        /// <param name="value"> The first active alarm time. </param>
+        /// <param name="period"> The amount of time between subsequent alarms (in seconds).</param>
+        /// <param name="appControl"> The destination AppControl is used to perform a specific task when the alarm is triggered. </param>
+        /// <returns> An alarm instance is created with the set param values.</returns>
+        /// <remarks>
+        /// This operation only allows service application which has Background Category to set an exact alarm.
+        /// This API can have a significant impact on power usage when the device is in idle state, so apps that use it may greatly increase battery consumption.
+        /// Therefore, caution should be taken when using this API.
+        /// </remarks>
+        /// <exception cref="ArgumentException">Thrown in case of an invalid parameter.</exception>
+        /// <exception cref="UnauthorizedAccessException">Thrown in case of a permission denied.</exception>
+        /// <exception cref="InvalidOperationException">Thrown in case of any internal error.</exception>
+        /// <privilege>http://tizen.org/privilege/alarm.set</privilege>
+        /// <privilege>http://tizen.org/privilege/appmanager.launch</privilege>
+        /// <since_tizen> 12 </since_tizen>
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        public static Alarm CreateAlarmForServiceApp(DateTime value, int period, AppControl appControl)
+        {
+            if (appControl == null)
+            {
+                throw AlarmErrorFactory.GetException(AlarmError.InvalidParameter, "AppControl should be not null");
+            }
+
+            Alarm alarm = null;
+            int alarmId;
+            Interop.Alarm.DateTime time = ConvertDateTimeToStruct(value);
+            AlarmError ret = (AlarmError)Interop.Alarm.CreateAlarmRecurForService(appControl.SafeAppControlHandle, ref time, period, out alarmId);
+            alarm = new Alarm(alarmId);
+            if (ret != AlarmError.None)
+            {
+                throw AlarmErrorFactory.GetException(ret, "Failed to create Alarm");
+            }
+
+            return alarm;
+        }
+
         /// <summary>
         /// Cancels all scheduled alarms that are registered by the application that calls this API.
         /// </summary>