include/app_alarm.h

   1 /*
   2  * Copyright (c) 2011 - 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
  18 #ifndef __TIZEN_APPFW_ALARM_H__
  19 #define __TIZEN_APPFW_ALARM_H__
  20
  21 #include <tizen.h>
  22 #include <time.h>
  23 #include <app_control.h>
  24 #include <notification.h>
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /**
  31  * @file app_alarm.h
  32  */
  33
  34 /**
  35  * @addtogroup CAPI_ALARM_MODULE
  36  * @{
  37  */
  38
  39 /**
  40  * @brief Definition to app_control extra data : the ID of the alarm registered.
  41  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  42  */
  43 #define APP_CONTROL_DATA_ALARM_ID "http://tizen.org/appcontrol/data/alarm_id"
  44
  45 /**
  46  * @brief Enumeration for Alarm Error.
  47  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  48  */
  49 typedef enum {
  50         ALARM_ERROR_NONE = TIZEN_ERROR_NONE,    /**< Successful */
  51         ALARM_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,  /**< Invalid parameter */
  52         ALARM_ERROR_INVALID_TIME = TIZEN_ERROR_APPLICATION | 0x05,      /**< Invalid time */
  53         ALARM_ERROR_INVALID_DATE = TIZEN_ERROR_APPLICATION | 0x06,      /**< Invalid date */
  54         ALARM_ERROR_CONNECTION_FAIL = TIZEN_ERROR_APPLICATION | 0x07,   /**< The alarm service connection failed */
  55         ALARM_ERROR_NOT_PERMITTED_APP = TIZEN_ERROR_APPLICATION | 0x08, /**< Application is not permitted. (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif) */
  56         ALARM_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,  /**< Out of memory */
  57         ALARM_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED   /**< Permission denied */
  58 } alarm_error_e;
  59
  60
  61 /**
  62  * @brief Enumeration for Alarm Week Flag, the days of the week.
  63  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  64  */
  65 typedef enum {
  66         ALARM_WEEK_FLAG_SUNDAY = 0x01,  /**< Sunday */
  67         ALARM_WEEK_FLAG_MONDAY = 0x02,  /**< Monday */
  68         ALARM_WEEK_FLAG_TUESDAY = 0x04, /**< Tuesday */
  69         ALARM_WEEK_FLAG_WEDNESDAY = 0x08,       /**< Wednesday */
  70         ALARM_WEEK_FLAG_THURSDAY = 0x10,        /**< Thursday */
  71         ALARM_WEEK_FLAG_FRIDAY = 0x20,  /**< Friday */
  72         ALARM_WEEK_FLAG_SATURDAY = 0x40 /**< Saturday */
  73 } alarm_week_flag_e;
  74
  75 /**
  76  * @brief Called once for each scheduled alarm to get the alarm ID.
  77  *
  78  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  79  * @param[in] alarm_id The alarm ID returned when the alarm is scheduled
  80  * @param[in] user_data The user data passed from the foreach function
  81  * @return @c true to continue with the next iteration of the loop,
  82  *         otherwise @c false to break out of the loop
  83  * @pre alarm_foreach_registered_alarm() will invoke this callback to get all the registered alarm IDs.
  84  * @see alarm_foreach_registered_alarm()
  85  */
  86 typedef bool (*alarm_registered_alarm_cb)(int alarm_id, void *user_data);
  87
  88 /**
  89  * @brief Sets an alarm to be triggered after a specific time.
  90  * @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.
  91  *          To cancel the alarm, call alarm_cancel() with @a alarm_id.
  92  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  93  * @privlevel   public
  94  * @privilege   %http://tizen.org/privilege/alarm.set
  95  * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
  96  *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
  97  *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
  98  *          Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif, this api does not support exact period and delay for minimizing the wakeups of the device. The system can adjust when the alarm expires.
  99  *          If you want to trigger an alarm exactly, see @see alarm_schedule_once_after_delay()
 100  *          Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif If @a app_control is specified with service-application, the application is only allowed to run on which has Background Category.
 101  *          Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif 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.
 102  *
 103  * @param[in] app_control The destination app_control to perform a specific task when the alarm is triggered
 104  * @param[in] delay     The amount of time before the first execution (in seconds). Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif, Although this is inexact, the alarm will not fire before this time
 105  * @param[in] period The amount of time between subsequent alarms (in seconds). Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif, This value does not guarantee the accuracy. The actual interval is calculated by the OS. The minimum value is 600sec
 106  * @param[out] alarm_id The alarm ID that uniquely identifies an alarm
 107  * @return      @c 0 on success,
 108  *          otherwise a negative error value
 109  * @retval  #ALARM_ERROR_NONE Successful
 110  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 111  * @retval  #ALARM_ERROR_INVALID_TIME Triggered time is invalid
 112  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 113  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 114  * @retval  #ALARM_ERROR_NOT_PERMITTED_APP @a app_control is not permitted
 115  * @see alarm_cancel()
 116  * @see alarm_cancel_all()
 117  * @see alarm_get_scheduled_date()
 118  * @see alarm_get_scheduled_period()
 119  * @see alarm_schedule_once_after_delay()
 120  */
 121 int alarm_schedule_after_delay(app_control_h app_control, int delay, int period, int *alarm_id);
 122
 123
 124 /**
 125  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. [Use alarm_schedule_once_at_date() instead]
 126  * @brief Sets an alarm to be triggered at a specific time.
 127  * @details The @a date describes the time of the first occurrence.
 128  *          If @a period is bigger than @c 0, the alarm will be scheduled after the @a period time.
 129  *          If @a period is set to @c 0, the alarm will go off just once without repetition.
 130  *          To cancel the alarm, call alarm_cancel() with @a alarm_id.
 131  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 132  * @privlevel   public
 133  * @privilege   %http://tizen.org/privilege/alarm.set
 134  * @remarks If application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 135  *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
 136  *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
 137  *
 138  * @param[in]   app_control The destination app_control to perform specific work when the alarm is triggered
 139  * @param[in]   date    The first active alarm time
 140  * @param[in]   period  The amount of time between subsequent alarms(in second)
 141  * @param[out]  alarm_id        The alarm ID that uniquely identifies an alarm
 142  * @return      @c 0 on success,
 143  *          otherwise a negative error value
 144  * @retval  #ALARM_ERROR_NONE   Successful
 145  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 146  * @retval  #ALARM_ERROR_INVALID_DATE Triggered date is invalid
 147  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 148  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 149  * @see alarm_cancel()
 150  * @see alarm_cancel_all()
 151  * @see alarm_get_scheduled_date()
 152  * @see alarm_get_scheduled_period()
 153  */
 154 int alarm_schedule_at_date(app_control_h app_control, struct tm *date, int period, int *alarm_id) TIZEN_DEPRECATED_API;
 155
 156 /**
 157  * @brief Sets an alarm to be triggered after a specific time.
 158  * @details The alarm will go off @a delay seconds later.
 159  *          To cancel the alarm, call alarm_cancel() with @a alarm_id.
 160  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 161  * @privlevel   public
 162  * @privilege   %http://tizen.org/privilege/alarm.set
 163  * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 164  *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
 165  *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
 166  *          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.
 167  *          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.
 168  *          When the alarm is expired, Alarm Manager will turn on LCD to prohibit background jobs.
 169  *
 170  * @param[in] app_control The destination app_control to perform a specific task when the alarm is triggered
 171  * @param[in] delay     The amount of time before the execution (in seconds)
 172  * @param[out] alarm_id The alarm ID that uniquely identifies an alarm
 173  * @return      @c 0 on success,
 174  *          otherwise a negative error value
 175  * @retval  #ALARM_ERROR_NONE Successful
 176  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 177  * @retval  #ALARM_ERROR_INVALID_TIME Triggered time is invalid
 178  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 179  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 180  * @retval  #ALARM_ERROR_NOT_PERMITTED_APP @a app_control is not permitted. @a app_control for UI application is only permitted.
 181  * @see alarm_cancel()
 182  * @see alarm_cancel_all()
 183  * @see alarm_get_scheduled_date()
 184  */
 185 int alarm_schedule_once_after_delay(app_control_h app_control, int delay, int *alarm_id);
 186
 187
 188 /**
 189  * @brief Sets an alarm to be triggered at a specific time.
 190  * @details The @a date describes the time of the first occurrence.
 191  *          To cancel the alarm, call alarm_cancel() with @a alarm_id.
 192  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 193  * @privlevel   public
 194  * @privilege   %http://tizen.org/privilege/alarm.set
 195  * @remarks If application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 196  *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
 197  *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
 198  *          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.
 199  *          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.
 200  *          When the alarm is expired, Alarm Manager will turn on LCD to prohibit background jobs.
 201  *
 202  * @param[in]   app_control The destination app_control to perform specific work when the alarm is triggered
 203  * @param[in]   date    The first active alarm time
 204  * @param[out]  alarm_id        The alarm ID that uniquely identifies an alarm
 205  * @return      @c 0 on success,
 206  *          otherwise a negative error value
 207  * @retval  #ALARM_ERROR_NONE   Successful
 208  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 209  * @retval  #ALARM_ERROR_INVALID_DATE Triggered date is invalid
 210  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 211  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 212  * @retval  #ALARM_ERROR_NOT_PERMITTED_APP @a app_control is not permitted. @a app_control for UI application is only permitted.
 213  * @see alarm_cancel()
 214  * @see alarm_cancel_all()
 215  * @see alarm_get_scheduled_date()
 216  */
 217 int alarm_schedule_once_at_date(app_control_h app_control, struct tm *date, int *alarm_id);
 218
 219
 220 /**
 221  * @brief Sets an alarm to be triggered periodically, starting at a specific time.
 222  * @details The @a date describes the time of the first occurrence.
 223  *              @a week_flag is the repeat value of the days of the week.
 224  *              If @a week_flag is #ALARM_WEEK_FLAG_TUESDAY, the alarm will repeat every Tuesday at a specific time.
 225  *              To cancel the alarm, call alarm_cancel() with @a alarm_id.
 226  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 227  * @privlevel   public
 228  * @privilege   %http://tizen.org/privilege/alarm.set
 229  * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 230  *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
 231  *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
 232  *          Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif, 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.
 233  *          When the alarm is expired, Alarm Manager will turn on LCD to prohibit background jobs.
 234  *          Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif, 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.
 235  *
 236  * @param[in] app_control The destination app_control to perform specific work when the alarm is triggered
 237  * @param[in] date      The first active alarm time
 238  * @param[in] week_flag The day of the week, @a week_flag may be a combination of days, like #ALARM_WEEK_FLAG_TUESDAY | #ALARM_WEEK_FLAG_FRIDAY
 239  * @param[out] alarm_id The alarm ID that uniquely identifies an alarm
 240  * @return @c 0 on success,
 241  *         otherwise a negative error value
 242  * @retval #ALARM_ERROR_NONE Successful
 243  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 244  * @retval #ALARM_ERROR_INVALID_DATE Triggered date is invalid
 245  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 246  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 247  * @retval #ALARM_ERROR_NOT_PERMITTED_APP @a app_control is not permitted. @a app_control for UI application is only permitted.
 248  * @see alarm_cancel()
 249  * @see alarm_cancel_all()
 250  * @see alarm_get_scheduled_recurrence_week_flag()
 251  * @see alarm_get_scheduled_date()
 252  * @see #alarm_week_flag_e
 253  */
 254 int alarm_schedule_with_recurrence_week_flag(app_control_h app_control, struct tm *date, int week_flag, int *alarm_id);
 255
 256
 257 /**
 258  * @brief Gets the recurrence days of the week.
 259  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 260  * @privlevel   public
 261  * @privilege   %http://tizen.org/privilege/alarm.get
 262  * @remarks If the given @a alarm_id is not obtained by using the alarm_schedule_with_recurrence_week_flag() function,
 263  *          an error (error code #ALARM_ERROR_INVALID_PARAMETER) will occur because this alarm is scheduled with no recurrence.
 264  *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
 265  *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
 266  * @param[in] alarm_id The alarm ID returned when the alarm is scheduled
 267  * @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
 268  * @return @c 0 on success,
 269  *         otherwise a negative error value
 270  * @retval #ALARM_ERROR_NONE Successful
 271  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 272  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 273  * @see alarm_schedule_with_recurrence_week_flag()
 274  * @see #alarm_week_flag_e
 275  */
 276 int alarm_get_scheduled_recurrence_week_flag(int alarm_id, int *week_flag);
 277
 278
 279 /**
 280  * @brief Cancels the alarm with the specific alarm ID.
 281  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 282  * @privlevel   public
 283  * @privilege   %http://tizen.org/privilege/alarm.set
 284  * @param[in] alarm_id  The alarm ID that is cancelled
 285  * @return @c 0 on success,
 286  *         otherwise a negative error value
 287  * @retval #ALARM_ERROR_NONE Successful
 288  * @retval #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 289  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 290  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 291  * @see alarm_schedule_at_date()
 292  * @see alarm_schedule_after_delay()
 293  * @see alarm_schedule_with_recurrence_week_flag()
 294  * @see alarm_cancel_all()
 295  */
 296 int alarm_cancel(int alarm_id);
 297
 298
 299 /**
 300  * @brief Cancels all scheduled alarms that are registered by the application that calls this API.
 301  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 302  * @privlevel   public
 303  * @privilege   %http://tizen.org/privilege/alarm.set
 304  * @return  @c 0 on success,
 305  *          otherwise a negative error value
 306  * @retval  #ALARM_ERROR_NONE Successful
 307  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 308  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 309  * @see alarm_schedule_at_date()
 310  * @see alarm_schedule_after_delay()
 311  * @see alarm_schedule_with_recurrence_week_flag()
 312  * @see alarm_cancel()
 313  */
 314 int alarm_cancel_all(void);
 315
 316
 317 /**
 318  * @brief Retrieves the IDs of all registered alarms by invoking a callback once for each scheduled alarm.
 319  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 320  * @privlevel   public
 321  * @privilege   %http://tizen.org/privilege/alarm.get
 322  * @param[in] callback The callback function to invoke
 323  * @param[in] user_data The user data to be passed to the callback function
 324  * @return @c 0 on success,
 325  *         otherwise a negative error value
 326  * @retval #ALARM_ERROR_NONE   Successful
 327  * @retval #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 328  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 329  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 330  * @post   This function invokes alarm_registered_alarm_cb() repeatedly for each registered alarm.
 331  * @see alarm_registered_alarm_cb()
 332  */
 333 int alarm_foreach_registered_alarm(alarm_registered_alarm_cb callback, void *user_data);
 334
 335
 336 /**
 337  * @brief Gets the scheduled time from the given alarm ID in C standard time struct.
 338  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 339  * @privlevel   public
 340  * @privilege   %http://tizen.org/privilege/alarm.get
 341  * @param[in] alarm_id The alarm ID returned when the alarm is scheduled
 342  * @param[out] date     The time value of the next alarm event
 343  * @return @c 0 on success,
 344  *         otherwise a negative error value
 345  * @retval #ALARM_ERROR_NONE   Successful
 346  * @retval #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 347  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 348  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 349  * @see alarm_schedule_at_date()
 350  * @see alarm_schedule_after_delay()
 351  * @see alarm_schedule_with_recurrence_week_flag()
 352  */
 353 int alarm_get_scheduled_date(int alarm_id, struct tm *date);
 354
 355
 356 /**
 357  * @brief Gets the period of time between the recurrent alarms.
 358  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 359  * @privlevel   public
 360  * @privilege   %http://tizen.org/privilege/alarm.get
 361  * @remarks If the given @a alarm_id is not obtained by using the alarm_schedule_at_date() or alarm_schedule_after_delay() function,
 362  *          an error (error code #ALARM_ERROR_INVALID_PARAMETER) will occur.
 363  * @param[in] alarm_id The alarm ID returned when the alarm is scheduled
 364  * @param[out] period The period of time between recurrent alarms in seconds
 365  * @return @c 0 on success,
 366  *         otherwise a negative error value
 367  * @retval #ALARM_ERROR_NONE   Successful
 368  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 369  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 370  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 371  * @see alarm_schedule_at_date()
 372  * @see alarm_schedule_after_delay()
 373  * @see alarm_schedule_with_recurrence_week_flag()
 374  */
 375 int alarm_get_scheduled_period(int alarm_id, int *period);
 376
 377
 378 /**
 379  * @brief Gets the current system time using C standard time struct.
 380  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 381  * @param[out] date The current system time
 382  * @return @c 0 on success,
 383  *         otherwise a negative error value
 384  * @retval #ALARM_ERROR_NONE Successful
 385  * @retval #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 386  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 387  */
 388 int alarm_get_current_time(struct tm *date);
 389
 390
 391 /**
 392  * @brief Gets the app_control to be invoked when the the alarm is triggered.
 393  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 394  * @privlevel   public
 395  * @privilege   %http://tizen.org/privilege/alarm.get
 396  * @remarks The @a app_control must be released using app_control_destroy().
 397  * @param[in] alarm_id The alarm ID uniquely identifies an alarm
 398  * @param[out] app_control The app_control handle to launch when the alarm is triggered
 399  * @return @c 0 on success,
 400  *         otherwise a negative error value
 401  * @retval #ALARM_ERROR_NONE Successful
 402  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 403  * @retval #ALARM_ERROR_OUT_OF_MEMORY Out of memory
 404  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 405  * @see alarm_schedule_at_date()
 406  * @see alarm_schedule_after_delay()
 407  * @see alarm_schedule_with_recurrence_week_flag()
 408  */
 409 int alarm_get_app_control(int alarm_id, app_control_h *app_control);
 410
 411
 412 /**
 413  * @brief Sets global flag in the alarm.
 414  * @details Sets @a global flag to set/unset alarm globally.
 415  * @since_tizen 3.0
 416  * @privlevel public
 417  * @privilege %http://tizen.org/privilege/alarm.set
 418  * @remarks The @a alarm_id must be id of alarm which will launch global application.
 419  *              The function returns an error (error code #ALARM_ERROR_NOT_PERMITTED_APP) if it is not.
 420  *              Note that the application which is launched by global alarm runs in the user session that is logined currently.
 421  *              It doesn't run in the session for the user who registers the global alarm.
 422  *              So, If the application uses application's private data for each user to handling the app_control for the alarm, it might not show proper data to the user.
 423  *              Therefore, We recommend to contain all the data for the alarm to the app_control handle for the global alarm.
 424  *              Then, the launched application would be able to use the data to show proper alarm UX to the user.
 425  * @param[in] alarm_id The alarm ID uniquely identifies an alarm
 426  * @param[in] global The global flag to set/unset alarm globally
 427  * @return @c 0 on success,
 428  *         otherwise a negative error value
 429  * @retval #ALARM_ERROR_NONE Successful
 430  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 431  * @retval #ALARM_ERROR_NOT_PERMITTED_APP @a alarm_id is not permitted
 432  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 433  * @see alarm_schedule_at_date()
 434  * @see alarm_schedule_after_delay()
 435  * @see alarm_schedule_with_recurrence_week_flag()
 436  */
 437 int alarm_set_global(int alarm_id, bool global);
 438
 439
 440 /**
 441  * @brief Gets whether the alarm will launch global application or not.
 442  * @since_tizen 3.0
 443  * @privlevel public
 444  * @privilege %http://tizen.org/privilege/alarm.get
 445  * @param[in] alarm_id The alarm ID uniquely identifies an alarm
 446  * @param[out] global Whether the alarm will launch global application or not
 447  * @return @c 0 on success,
 448  *         otherwise a negative error value
 449  * @retval #ALARM_ERROR_NONE Successful
 450  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 451  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 452  * @see alarm_set_global()
 453  */
 454 int alarm_get_global(int alarm_id, bool *global);
 455
 456
 457 /**
 458  * @brief Sets a notification alarm to be triggered at a specific time.
 459  * @details The @a date describes the time of the alarm occurrence.
 460  *          To cancel the alarm, call alarm_cancel() with @a alarm_id.
 461  * @since_tizen 3.0
 462  * @privlevel   public
 463  * @privilege   %http://tizen.org/privilege/alarm.set
 464  * @privilege   %http://tizen.org/privilege/notification
 465  * @remarks If application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 466  *          When the alarm goes off, Alarm Manager will turn on LCD to prohibit background jobs.
 467  *
 468  * @param[in]   noti The notification to be posted when the alarm is triggered
 469  * @param[in]   date    The active alarm time
 470  * @param[out]  alarm_id        The ID which uniquely identifies the scheduled alarm
 471  * @return      @c 0 on success,
 472  *          otherwise a negative error value
 473  * @retval  #ALARM_ERROR_NONE   Successful
 474  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 475  * @retval  #ALARM_ERROR_INVALID_DATE Triggered date is invalid
 476  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 477  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 478  * @see alarm_cancel()
 479  * @see alarm_cancel_all()
 480  * @see alarm_get_scheduled_date()
 481  */
 482 int alarm_schedule_noti_once_at_date(notification_h noti, struct tm *date, int *alarm_id);
 483
 484 /**
 485  * @brief Sets a notification alarm to be triggered after a specific delay.
 486  * @details The alarm will first go off after @a delay seconds.
 487  *          The alarm will then go off every period seconds until canceled.
 488  *          To cancel the alarm, call alarm_cancel() with @a alarm_id.
 489  * @since_tizen 3.0
 490  * @privlevel   public
 491  * @privilege   %http://tizen.org/privilege/alarm.set
 492  * @privilege   %http://tizen.org/privilege/notification
 493  * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 494  *          This function is a minimally intrusive way to trigger alarms when precision is not important.
 495  *          The system will adjust the @a delay and @a period requests to suit internal needs; the requests
 496  *          will be treated as minimum values. Note that @a period cannot be less than 600 seconds, if
 497  *          a smaller request is supplied it will be silently adjusted to a request of 600.
 498  *          When the alarm goes off, Alarm Manager will turn on LCD to prohibit background jobs.
 499  *
 500  * @param[in] noti The notification to be posted when the alarm is triggered
 501  * @param[in] delay     The amount of time before the first execution (in seconds).
 502  * @param[in] period The amount of time between subsequent alarms (in seconds).
 503  * @param[out] alarm_id The ID which uniquely identifies the scheduled alarm
 504  * @return      @c 0 on success,
 505  *          otherwise a negative error value
 506  * @retval  #ALARM_ERROR_NONE Successful
 507  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 508  * @retval  #ALARM_ERROR_INVALID_TIME Triggered time is invalid
 509  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 510  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 511  * @see alarm_cancel()
 512  * @see alarm_cancel_all()
 513  * @see alarm_get_scheduled_date()
 514  * @see alarm_get_scheduled_period()
 515  * @see alarm_schedule_noti_once_after_delay()
 516  */
 517 int alarm_schedule_noti_after_delay(notification_h noti, int delay, int period, int *alarm_id);
 518
 519 /**
 520  * @brief Sets a notification alarm to be triggered after a specific delay.
 521  * @details The alarm will go off @a delay seconds later.
 522  *          To cancel the alarm, call alarm_cancel() with @a alarm_id.
 523  * @since_tizen 3.0
 524  * @privlevel   public
 525  * @privilege   %http://tizen.org/privilege/alarm.set
 526  * @privilege   %http://tizen.org/privilege/notification
 527  * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 528  *          When the alarm goes off, Alarm Manager will turn on LCD to prohibit background jobs.
 529  *
 530  * @param[in] noti The notification to be posted when the alarm is triggered
 531  * @param[in] delay     The amount of time before the execution (in seconds)
 532  * @param[out] alarm_id The ID which uniquely identifies the scheduled alarm
 533  * @return      @c 0 on success,
 534  *          otherwise a negative error value
 535  * @retval  #ALARM_ERROR_NONE Successful
 536  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 537  * @retval  #ALARM_ERROR_INVALID_TIME Triggered time is invalid
 538  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 539  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 540  * @see alarm_cancel()
 541  * @see alarm_cancel_all()
 542  * @see alarm_get_scheduled_date()
 543  */
 544 int alarm_schedule_noti_once_after_delay(notification_h noti, int delay, int *alarm_id);
 545
 546 /**
 547  * @brief Sets a notification to be triggered periodically, starting at a specific time.
 548  * @details The @a date describes the time of the first occurrence.
 549  *              @a week_flag describes the day(s) of the week when the notification recurs.
 550  *              If @a week_flag is #ALARM_WEEK_FLAG_TUESDAY, the alarm will repeat every Tuesday at a specific time.
 551  *              If @a week_flag is less than or equal to zero, the alarm is not repeated.
 552  *              To cancel the alarm, call alarm_cancel() with @a alarm_id.
 553  * @since_tizen 3.0
 554  * @privlevel   public
 555  * @privilege   %http://tizen.org/privilege/alarm.set
 556  * @privilege   %http://tizen.org/privilege/notification
 557  * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 558  *
 559  * @param[in] noti The notification to be posted when the alarm is triggered
 560  * @param[in] date      The first active alarm time
 561  * @param[in] week_flag The day of the week the notification recurs. @a week_flag may be a combination of days, like #ALARM_WEEK_FLAG_TUESDAY | #ALARM_WEEK_FLAG_FRIDAY
 562  * @param[out] alarm_id The ID which uniquely identifies the scheduled alarm
 563  * @return @c 0 on success,
 564  *         otherwise a negative error value
 565  * @retval #ALARM_ERROR_NONE Successful
 566  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 567  * @retval #ALARM_ERROR_INVALID_DATE Triggered date is invalid
 568  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 569  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 570  * @see alarm_cancel()
 571  * @see alarm_cancel_all()
 572  * @see alarm_get_scheduled_recurrence_week_flag()
 573  * @see alarm_get_scheduled_date()
 574  * @see #alarm_week_flag_e
 575  */
 576 int alarm_schedule_noti_with_recurrence_week_flag(notification_h noti, struct tm *date, int week_flag, int *alarm_id);
 577
 578 /**
 579  * @brief Gets the notification to be posted when an alarm is triggered.
 580  * @since_tizen 3.0
 581  * @privlevel   public
 582  * @privilege   %http://tizen.org/privilege/alarm.get
 583  * @remarks @a noti must be released using notification_free().
 584  *
 585  * @param[in] alarm_id The ID which uniquely identifies a scheduled alarm
 586  * @param[out] noti The notification to be posted when the alarm is triggered
 587  * @return @c 0 on success,
 588  *         otherwise a negative error value
 589  * @retval #ALARM_ERROR_NONE Successful
 590  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 591  * @retval #ALARM_ERROR_OUT_OF_MEMORY Out of memory
 592  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 593  * @see alarm_schedule_noti_once_at_date()
 594  * @see alarm_schedule_noti_after_delay()
 595  * @see alarm_schedule_noti_once_after_delay()
 596  * @see alarm_schedule_noti_with_recurrence_week_flag()
 597  */
 598 int alarm_get_notification(int alarm_id, notification_h *noti);
 599
 600 /**
 601  * @}
 602  */
 603
 604 #ifdef __cplusplus
 605 }
 606 #endif
 607
 608 #endif /* __TIZEN_APPFW_ALARM_H__ */
 609