update app_alarm.h from tizen_2.4

Change-Id: I5881c5f27a196f80afa464872a1b10170bca145e
Signed-off-by: Jiwoong Im <jiwoong.im@samsung.com>

diff --git a/include/app_alarm.h b/include/app_alarm.h
index 7c7c518..f6ae64b 100644 (file)
--- a/include/app_alarm.h
+++ b/include/app_alarm.h
@@ -85,27 +85,24 @@ typedef enum {
 typedef bool (*alarm_registered_alarm_cb)(int alarm_id, void *user_data);
 
 /**
- * @deprecated Deprecated since 2.4. [Use alarm_schedule_once_after_delay() instead]
  * @brief Sets an alarm to be triggered after a specific time.
  * @details The alarm will first go off @a delay seconds later and then will go off every certain amount of time defined using @a period seconds.
- *          If @a period is bigger than @c 0, the alarm will be scheduled after the @a period time.
- *          If @a period is set to @c 0, the alarm will go off just once without repetition.
  *          To cancel the alarm, call alarm_cancel() with @a alarm_id.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @privlevel  public
  * @privilege  %http://tizen.org/privilege/alarm.set
  * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
- *         If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
- *         If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
- *         Since 2.4, this api does not support exact period and delay for minimizing the wakeups of the device. The system can adjust when the alarm expires.
- *         If you want to trigger an alarm exactly, see @see alarm_schedule_once_after_delay()
- *         Since 2.4 If @a app_control is specified with service-application, the application is only allowed to run on which has Background Category.
- *         Since 2.4 If the appid of @a app_control is not specified, this api is not allowed. In other words, the explicit @a app_control is only allowed.
+ *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
+ *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
+ *          Since 2.4, this api does not support exact period and delay for minimizing the wakeups of the device. The system can adjust when the alarm expires.
+ *          If you want to trigger an alarm exactly, see @see alarm_schedule_once_after_delay()
+ *          Since 2.4 If @a app_control is specified with service-application, the application is only allowed to run on which has Background Category.
+ *          Since 2.4 If the appid of @a app_control is not specified, this api is not allowed. In other words, the explicit @a app_control is only allowed.
  *
  * @param[in] app_control The destination app_control to perform a specific task when the alarm is triggered
  * @param[in] delay    The amount of time before the first execution (in seconds). Since 2.4, Although this is inexact, the alarm will not fire before this time
  * @param[in] period The amount of time between subsequent alarms (in seconds). Since 2.4, This value does not guarantee the accuracy. The actual interval is calculated by the OS. The minimum value is 600sec
- * @param[out] alarm_id        The alarm ID that uniquely identifies an alarm.
+ * @param[out] alarm_id        The alarm ID that uniquely identifies an alarm
  * @return     @c 0 on success,
  *          otherwise a negative error value
  * @retval  #ALARM_ERROR_NONE Successful
@@ -117,6 +114,8 @@ typedef bool (*alarm_registered_alarm_cb)(int alarm_id, void *user_data);
  * @see alarm_cancel()
  * @see alarm_cancel_all()
  * @see alarm_get_scheduled_date()
+ * @see alarm_get_scheduled_period()
+ * @see alarm_schedule_once_after_delay()
  */
 int alarm_schedule_after_delay(app_control_h app_control, int delay, int period, int *alarm_id);
 
@@ -161,11 +160,11 @@ int alarm_schedule_at_date(app_control_h app_control, struct tm *date, int perio
  * @privlevel  public
  * @privilege  %http://tizen.org/privilege/alarm.set
  * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
- *         If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
- *         If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
- *         If the appid of @a app_control is not specified, this api is not allowed. In other words, the explicit @a app_control is only allowed.
- *         The @a app_control only supports UI application with this api. If @a app_control is not UI application, #ALARM_ERROR_NOT_PERMITTED_APP returned.
- *         When the alarm is expired, Alarm Manager will turn on LCD to prohibit background jobs.
+ *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
+ *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
+ *          If the appid of @a app_control is not specified, this api is not allowed. In other words, the explicit @a app_control is only allowed.
+ *          The @a app_control only supports UI application with this api. If @a app_control is not UI application, #ALARM_ERROR_NOT_PERMITTED_APP returned.
+ *          When the alarm is expired, Alarm Manager will turn on LCD to prohibit background jobs.
  *
  * @param[in] app_control The destination app_control to perform a specific task when the alarm is triggered
  * @param[in] delay    The amount of time before the execution (in seconds)
@@ -216,6 +215,7 @@ int alarm_schedule_once_after_delay(app_control_h app_control, int delay, int *a
  */
 int alarm_schedule_once_at_date(app_control_h app_control, struct tm *date, int *alarm_id);
 
+
 /**
  * @brief Sets an alarm to be triggered periodically, starting at a specific time.
  * @details The @a date describes the time of the first occurrence.
@@ -228,6 +228,9 @@ int alarm_schedule_once_at_date(app_control_h app_control, struct tm *date, int
  * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
  *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
  *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
+ *          Since 2.4, The @a app_control only supports UI application with this api. If @a app_control is not UI application, #ALARM_ERROR_NOT_PERMITTED_APP returned.
+ *          When the alarm is expired, Alarm Manager will turn on LCD to prohibit background jobs.
+ *          Since 2.4, If the appid of @a app_control is not specified, this api is not allowed. In other words, the explicit @a app_control is only allowed.
  *
  * @param[in] app_control The destination app_control to perform specific work when the alarm is triggered
  * @param[in] date     The first active alarm time
@@ -239,14 +242,16 @@ int alarm_schedule_once_at_date(app_control_h app_control, struct tm *date, int
  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #ALARM_ERROR_INVALID_DATE Triggered date is invalid
  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
- * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
+ * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
+ * @retval #ALARM_ERROR_NOT_PERMITTED_APP @a app_control is not permitted. @a app_control for UI application is only permitted.
  * @see alarm_cancel()
  * @see alarm_cancel_all()
  * @see alarm_get_scheduled_recurrence_week_flag()
  * @see alarm_get_scheduled_date()
  * @see        #alarm_week_flag_e
  */
-int alarm_schedule_with_recurrence_week_flag(app_control_h app_control, struct tm *date, int week_flag, int *alarm_id);
+int alarm_schedule_with_recurrence_week_flag(app_control_h app_control, struct tm *date, int week_flag,int *alarm_id);
+
 
 /**
  * @brief Gets the recurrence days of the week.
@@ -257,9 +262,6 @@ int alarm_schedule_with_recurrence_week_flag(app_control_h app_control, struct t
  *          an error (error code #ALARM_ERROR_INVALID_PARAMETER) will occur because this alarm is scheduled with no recurrence.
  *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
  *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
- *          Since 2.4, The @a app_control only supports UI application with this api. If @a app_control is not UI application, #ALARM_ERROR_NOT_PERMITTED_APP returned.
- *          When the alarm is expired, Alarm Manager will turn on LCD to prohibit background jobs.
- *          Since 2.4, If the appid of @a app_control is not specified, this api is not allowed. In other words, the explicit @a app_control is only allowed.
  * @param[in] alarm_id The alarm ID returned when the alarm is scheduled
  * @param[out] week_flag The recurrence days of the week, @a week_flag may be a combination of days, like #ALARM_WEEK_FLAG_TUESDAY | #ALARM_WEEK_FLAG_FRIDAY
  * @return @c 0 on success,
@@ -267,7 +269,6 @@ int alarm_schedule_with_recurrence_week_flag(app_control_h app_control, struct t
  * @retval #ALARM_ERROR_NONE Successful
  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
- * @retval #ALARM_ERROR_NOT_PERMITTED_APP @a app_control is not permitted. @a app_control for UI application is only permitted.
  * @see alarm_schedule_with_recurrence_week_flag()
  * @see        #alarm_week_flag_e
  */
@@ -356,7 +357,7 @@ int alarm_get_scheduled_date(int alarm_id, struct tm *date);
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @privlevel  public
  * @privilege  %http://tizen.org/privilege/alarm.get
- * @remarks If the given @a alarm_id is not obtained by using the alarm_get_scheduled_date() or alarm_schedule_after_delay() function,
+ * @remarks If the given @a alarm_id is not obtained by using the alarm_schedule_at_date() or alarm_schedule_after_delay() function,
  *          an error (error code #ALARM_ERROR_INVALID_PARAMETER) will occur.
  * @param[in] alarm_id The alarm ID returned when the alarm is scheduled
  * @param[out] period The period of time between recurrent alarms in seconds