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 Enumeration for inexact interval.
  77  * @since_tizen 6.0
  78  */
  79 typedef enum {
  80         ALARM_STANDARD_INTERVAL_FIFTEEN_MINUTES = 900, /**< 900 seconds */
  81         ALARM_STANDARD_INTERVAL_HALF_HOUR = ALARM_STANDARD_INTERVAL_FIFTEEN_MINUTES * 2, /**< 1800 seconds */
  82         ALARM_STANDARD_INTERVAL_HOUR = ALARM_STANDARD_INTERVAL_HALF_HOUR * 2, /**< 3600 seconds */
  83         ALARM_STANDARD_INTERVAL_DAY = ALARM_STANDARD_INTERVAL_HOUR * 24 /**< 86400 seconds */
  84 } alarm_standard_interval_e;
  85
  86
  87 /**
  88  * @brief Called once for each scheduled alarm to get the alarm ID.
  89  *
  90  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  91  * @param[in] alarm_id The alarm ID returned when the alarm is scheduled
  92  * @param[in] user_data The user data passed from the foreach function
  93  * @return @c true to continue with the next iteration of the loop,
  94  *         otherwise @c false to break out of the loop
  95  * @pre   alarm_foreach_registered_alarm() will invoke this callback to get all the registered alarm IDs.
  96  * @see   alarm_foreach_registered_alarm()
  97  */
  98 typedef bool (*alarm_registered_alarm_cb)(int alarm_id, void *user_data);
  99
 100
 101 /**
 102  * @brief Sets an alarm to be triggered after a specific time.
 103  * @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. To cancel the alarm, call alarm_cancel() with @a alarm_id.
 104  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 105  * @privlevel public
 106  * @privilege %http://tizen.org/privilege/alarm.set
 107  * @privilege %http://tizen.org/privilege/appmanager.launch
 108  * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 109  *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
 110  *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
 111  *          Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif, this function does not support exact period and delay for minimizing the wakeups of the device. The system can adjust when the alarm expires.
 112  *          If you want to trigger an alarm exactly, see @see alarm_schedule_once_after_delay()
 113  *          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.
 114  *          Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif If the appid of @a app_control is not specified, this function is not allowed. In other words, the explicit @a app_control is only allowed.
 115  *          Since 4.0, %http://tizen.org/privilege/appmanager.launch privilege is additionally required.
 116  *          Since 6.0, You can use #alarm_standard_interval_e for @a period. If you use it, the period of alarm is guaranteed.
 117  *
 118  * @param[in] app_control The destination app_control to perform a specific task when the alarm is triggered
 119  * @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
 120  * @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.
 121  *            Since 6.0 this can be one of the values of #alarm_standard_interval_e. If you uses raw integer value, the value will be phase-aligned with other period of alarm.
 122
 123  * @param[out] alarm_id The alarm ID that uniquely identifies an alarm
 124  * @return @c 0 on success,
 125  *         otherwise a negative error value
 126  * @retval #ALARM_ERROR_NONE Successful
 127  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 128  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 129  * @retval #ALARM_ERROR_INVALID_TIME Triggered time is invalid
 130  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 131  * @retval #ALARM_ERROR_NOT_PERMITTED_APP @a app_control is not permitted
 132  * @see alarm_cancel()
 133  * @see alarm_cancel_all()
 134  * @see alarm_get_scheduled_date()
 135  * @see alarm_get_scheduled_period()
 136  * @see alarm_schedule_once_after_delay()
 137  */
 138 int alarm_schedule_after_delay(app_control_h app_control, int delay, int period, int *alarm_id);
 139
 140
 141 /**
 142  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. [Use alarm_schedule_once_at_date() instead]
 143  * @brief Sets an alarm to be triggered at a specific time.
 144  * @details The @a date describes the time of the first occurrence.
 145  *          If @a period is bigger than @c 0, the alarm will be scheduled after the @a period time.
 146  *          If @a period is set to @c 0, the alarm will go off just once without repetition.
 147  *          To cancel the alarm, call alarm_cancel() with @a alarm_id.
 148  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 149  * @privlevel public
 150  * @privilege %http://tizen.org/privilege/alarm.set
 151  * @remarks If application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 152  *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
 153  *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
 154  *
 155  * @param[in] app_control The destination app_control to perform specific work when the alarm is triggered
 156  * @param[in] date The first active alarm time
 157  * @param[in] period The amount of time between subsequent alarms(in second)
 158  * @param[out] alarm_id The alarm ID that uniquely identifies an alarm
 159  * @return @c 0 on success,
 160  *         otherwise a negative error value
 161  * @retval #ALARM_ERROR_NONE Successful
 162  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 163  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 164  * @retval #ALARM_ERROR_INVALID_DATE Triggered date is invalid
 165  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 166  * @see alarm_cancel()
 167  * @see alarm_cancel_all()
 168  * @see alarm_get_scheduled_date()
 169  * @see alarm_get_scheduled_period()
 170  */
 171 int alarm_schedule_at_date(app_control_h app_control, struct tm *date, int period, int *alarm_id) TIZEN_DEPRECATED_API;
 172
 173 /**
 174  * @brief Sets an alarm to be triggered after a specific time.
 175  * @details The alarm will go off @a delay seconds later. To cancel the alarm, call alarm_cancel() with @a alarm_id.
 176  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 177  * @privlevel public
 178  * @privilege %http://tizen.org/privilege/alarm.set
 179  * @privilege %http://tizen.org/privilege/appmanager.launch
 180  * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 181  *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
 182  *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
 183  *          If the appid of @a app_control is not specified, this function is not allowed. In other words, the explicit @a app_control is only allowed.
 184  *          The @a app_control only supports UI application with this function. If @a app_control is not UI application, #ALARM_ERROR_NOT_PERMITTED_APP returned.
 185  *          When the alarm is expired, Alarm Manager will turn on LCD to prohibit background jobs.
 186  *          Since 4.0, %http://tizen.org/privilege/appmanager.launch privilege is additionally required.
 187  *
 188  * @param[in] app_control The destination app_control to perform a specific task when the alarm is triggered
 189  * @param[in] delay The amount of time before the execution (in seconds)
 190  * @param[out] alarm_id The alarm ID that uniquely identifies an alarm
 191  * @return @c 0 on success,
 192  *         otherwise a negative error value
 193  * @retval #ALARM_ERROR_NONE Successful
 194  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 195  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 196  * @retval #ALARM_ERROR_INVALID_TIME Triggered time is invalid
 197  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 198  * @retval #ALARM_ERROR_NOT_PERMITTED_APP @a app_control is not permitted. @a app_control for UI application is only permitted.
 199  * @see alarm_cancel()
 200  * @see alarm_cancel_all()
 201  * @see alarm_get_scheduled_date()
 202  */
 203 int alarm_schedule_once_after_delay(app_control_h app_control, int delay, int *alarm_id);
 204
 205
 206 /**
 207  * @brief Sets an alarm to be triggered at a specific time.
 208  * @details The @a date describes the time of the first occurrence. To cancel the alarm, call alarm_cancel() with @a alarm_id.
 209  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 210  * @privlevel public
 211  * @privilege %http://tizen.org/privilege/alarm.set
 212  * @privilege %http://tizen.org/privilege/appmanager.launch
 213  * @remarks If application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 214  *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
 215  *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
 216  *          If the appid of @a app_control is not specified, this function is not allowed. In other words, the explicit @a app_control is only allowed.
 217  *          The @a app_control only supports UI application with this function. If @a app_control is not UI application, #ALARM_ERROR_NOT_PERMITTED_APP returned.
 218  *          When the alarm is expired, Alarm Manager will turn on LCD to prohibit background jobs.
 219  *          Since 4.0, %http://tizen.org/privilege/appmanager.launch privilege is additionally required.
 220  *
 221  * @param[in] app_control The destination app_control to perform specific work when the alarm is triggered
 222  * @param[in] date The first active alarm time
 223  * @param[out] alarm_id The alarm ID that uniquely identifies an alarm
 224  * @return @c 0 on success,
 225  *         otherwise a negative error value
 226  * @retval #ALARM_ERROR_NONE   Successful
 227  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 228  * @retval #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 229  * @retval #ALARM_ERROR_INVALID_DATE Triggered date is invalid
 230  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 231  * @retval #ALARM_ERROR_NOT_PERMITTED_APP @a app_control is not permitted. @a app_control for UI application is only permitted.
 232  * @see alarm_cancel()
 233  * @see alarm_cancel_all()
 234  * @see alarm_get_scheduled_date()
 235  */
 236 int alarm_schedule_once_at_date(app_control_h app_control, struct tm *date, int *alarm_id);
 237
 238
 239 /**
 240  * @brief Sets an alarm to be triggered periodically, starting at a specific time.
 241  * @details The @a date describes the time of the first occurrence.
 242  *          @a week_flag is the repeat value of the days of the week.
 243  *          If @a week_flag is #ALARM_WEEK_FLAG_TUESDAY, the alarm will repeat every Tuesday at a specific time.
 244  *          To cancel the alarm, call alarm_cancel() with @a alarm_id.
 245  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 246  * @privlevel public
 247  * @privilege %http://tizen.org/privilege/alarm.set
 248  * @privilege %http://tizen.org/privilege/appmanager.launch
 249  * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 250  *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
 251  *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
 252  *          Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif, The @a app_control only supports UI application with this function. If @a app_control is not UI application, #ALARM_ERROR_NOT_PERMITTED_APP returned.
 253  *          When the alarm is expired, Alarm Manager will turn on LCD to prohibit background jobs.
 254  *          Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif, If the appid of @a app_control is not specified, this function is not allowed. In other words, the explicit @a app_control is only allowed.
 255  *          Since 4.0, %http://tizen.org/privilege/appmanager.launch privilege is additionally required.
 256  *
 257  * @param[in] app_control The destination app_control to perform specific work when the alarm is triggered
 258  * @param[in] date The first active alarm time
 259  * @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
 260  * @param[out] alarm_id The alarm ID that uniquely identifies an alarm
 261  * @return @c 0 on success,
 262  *         otherwise a negative error value
 263  * @retval #ALARM_ERROR_NONE Successful
 264  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 265  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 266  * @retval #ALARM_ERROR_INVALID_DATE Triggered date is invalid
 267  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 268  * @retval #ALARM_ERROR_NOT_PERMITTED_APP @a app_control is not permitted. @a app_control for UI application is only permitted.
 269  * @see alarm_cancel()
 270  * @see alarm_cancel_all()
 271  * @see alarm_get_scheduled_recurrence_week_flag()
 272  * @see alarm_get_scheduled_date()
 273  * @see #alarm_week_flag_e
 274  */
 275 int alarm_schedule_with_recurrence_week_flag(app_control_h app_control, struct tm *date, int week_flag, int *alarm_id);
 276
 277
 278 /**
 279  * @brief Gets the recurrence days of the week.
 280  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 281  * @privlevel public
 282  * @privilege %http://tizen.org/privilege/alarm.get
 283  * @remarks If the given @a alarm_id is not obtained by using the alarm_schedule_with_recurrence_week_flag() function,
 284  *          an error (error code #ALARM_ERROR_INVALID_PARAMETER) will occur because this alarm is scheduled with no recurrence.
 285  * @param[in] alarm_id The alarm ID returned when the alarm is scheduled
 286  * @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
 287  * @return @c 0 on success,
 288  *         otherwise a negative error value
 289  * @retval #ALARM_ERROR_NONE Successful
 290  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 291  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 292  * @see alarm_schedule_with_recurrence_week_flag()
 293  * @see #alarm_week_flag_e
 294  */
 295 int alarm_get_scheduled_recurrence_week_flag(int alarm_id, int *week_flag);
 296
 297
 298 /**
 299  * @brief Cancels the alarm with the specific alarm ID.
 300  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 301  * @privlevel public
 302  * @privilege %http://tizen.org/privilege/alarm.set
 303  * @param[in] alarm_id The alarm ID that is cancelled
 304  * @return @c 0 on success,
 305  *         otherwise a negative error value
 306  * @retval #ALARM_ERROR_NONE Successful
 307  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 308  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 309  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 310  * @see alarm_schedule_once_at_date()
 311  * @see alarm_schedule_after_delay()
 312  * @see alarm_schedule_with_recurrence_week_flag()
 313  * @see alarm_cancel_all()
 314  */
 315 int alarm_cancel(int alarm_id);
 316
 317
 318 /**
 319  * @brief Cancels all scheduled alarms that are registered by the application that calls this function.
 320  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 321  * @privlevel public
 322  * @privilege %http://tizen.org/privilege/alarm.set
 323  * @return @c 0 on success,
 324  *         otherwise a negative error value
 325  * @retval #ALARM_ERROR_NONE Successful
 326  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 327  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 328  * @see alarm_schedule_once_at_date()
 329  * @see alarm_schedule_after_delay()
 330  * @see alarm_schedule_with_recurrence_week_flag()
 331  * @see alarm_cancel()
 332  */
 333 int alarm_cancel_all(void);
 334
 335
 336 /**
 337  * @brief Retrieves the IDs of all registered alarms by invoking a callback once for each scheduled alarm.
 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] callback The callback function to invoke
 342  * @param[in] user_data The user data to be passed to the callback function
 343  * @return @c 0 on success,
 344  *         otherwise a negative error value
 345  * @retval #ALARM_ERROR_NONE Successful
 346  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 347  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 348  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 349  * @post This function invokes alarm_registered_alarm_cb() repeatedly for each registered alarm.
 350  * @see alarm_registered_alarm_cb()
 351  */
 352 int alarm_foreach_registered_alarm(alarm_registered_alarm_cb callback, void *user_data);
 353
 354
 355 /**
 356  * @brief Gets the scheduled time from the given alarm ID in C standard time struct.
 357  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 358  * @privlevel public
 359  * @privilege %http://tizen.org/privilege/alarm.get
 360  * @remarks @a date is not needed by the function after the call.
 361  * @param[in] alarm_id The alarm ID returned when the alarm is scheduled
 362  * @param[out] date The time value of the next alarm event
 363  * @return @c 0 on success,
 364  *         otherwise a negative error value
 365  * @retval #ALARM_ERROR_NONE Successful
 366  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 367  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 368  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 369  * @see alarm_schedule_once_at_date()
 370  * @see alarm_schedule_after_delay()
 371  * @see alarm_schedule_with_recurrence_week_flag()
 372  */
 373 int alarm_get_scheduled_date(int alarm_id, struct tm *date);
 374
 375
 376 /**
 377  * @brief Gets the period of time between the recurrent alarms.
 378  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 379  * @privlevel public
 380  * @privilege %http://tizen.org/privilege/alarm.get
 381  * @remarks If the given @a alarm_id is not obtained by using the alarm_schedule_once_at_date() or alarm_schedule_after_delay() function,
 382  *          an error (error code #ALARM_ERROR_INVALID_PARAMETER) will occur.
 383  * @param[in] alarm_id The alarm ID returned when the alarm is scheduled
 384  * @param[out] period The period of time between recurrent alarms in seconds
 385  * @return @c 0 on success,
 386  *         otherwise a negative error value
 387  * @retval #ALARM_ERROR_NONE Successful
 388  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 389  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 390  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 391  * @see alarm_schedule_once_at_date()
 392  * @see alarm_schedule_after_delay()
 393  * @see alarm_schedule_with_recurrence_week_flag()
 394  */
 395 int alarm_get_scheduled_period(int alarm_id, int *period);
 396
 397
 398 /**
 399  * @brief Gets the current system time using C standard time struct.
 400  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 401  * @param[out] date The current system time
 402  * @return @c 0 on success,
 403  *         otherwise a negative error value
 404  * @retval #ALARM_ERROR_NONE Successful
 405  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 406  */
 407 int alarm_get_current_time(struct tm *date);
 408
 409
 410 /**
 411  * @brief Gets the app_control to be invoked when the alarm is triggered.
 412  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 413  * @privlevel public
 414  * @privilege %http://tizen.org/privilege/alarm.get
 415  * @remarks The @a app_control must be released using app_control_destroy().
 416  * @param[in] alarm_id The alarm ID uniquely identifies an alarm
 417  * @param[out] app_control The app_control handle to launch when the alarm is triggered
 418  * @return @c 0 on success,
 419  *         otherwise a negative error value
 420  * @retval #ALARM_ERROR_NONE Successful
 421  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 422  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 423  * @retval #ALARM_ERROR_OUT_OF_MEMORY Out of memory
 424  * @see alarm_schedule_once_at_date()
 425  * @see alarm_schedule_after_delay()
 426  * @see alarm_schedule_with_recurrence_week_flag()
 427  */
 428 int alarm_get_app_control(int alarm_id, app_control_h *app_control);
 429
 430
 431 /**
 432  * @brief Sets global flag in the alarm.
 433  * @details Sets @a global flag to set/unset alarm globally.
 434  * @since_tizen 3.0
 435  * @privlevel public
 436  * @privilege %http://tizen.org/privilege/alarm.set
 437  * @remarks The @a alarm_id must be id of alarm which will launch global application.
 438  *          The function returns an error (error code #ALARM_ERROR_NOT_PERMITTED_APP) if it is not.
 439  *          Note that the application which is launched by global alarm runs in the user session that is logged in currently.
 440  *          It doesn't run in the session for the user who registers the global alarm.
 441  *          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.
 442  *          Therefore, We recommend to contain all the data for the alarm to the app_control handle for the global alarm.
 443  *          Then, the launched application would be able to use the data to show proper alarm UX to the user.
 444  * @param[in] alarm_id The alarm ID uniquely identifies an alarm
 445  * @param[in] global The global flag to set/unset alarm globally
 446  * @return @c 0 on success,
 447  *         otherwise a negative error value
 448  * @retval #ALARM_ERROR_NONE Successful
 449  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 450  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 451  * @retval #ALARM_ERROR_NOT_PERMITTED_APP @a alarm_id is not permitted
 452  * @see alarm_schedule_once_at_date()
 453  * @see alarm_schedule_after_delay()
 454  * @see alarm_schedule_with_recurrence_week_flag()
 455  */
 456 int alarm_set_global(int alarm_id, bool global);
 457
 458
 459 /**
 460  * @brief Gets whether the alarm will launch global application or not.
 461  * @since_tizen 3.0
 462  * @privlevel public
 463  * @privilege %http://tizen.org/privilege/alarm.get
 464  * @param[in] alarm_id The alarm ID uniquely identifies an alarm
 465  * @param[out] global Whether the alarm will launch global application or not
 466  * @return @c 0 on success,
 467  *         otherwise a negative error value
 468  * @retval #ALARM_ERROR_NONE Successful
 469  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 470  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 471  * @see alarm_set_global()
 472  */
 473 int alarm_get_global(int alarm_id, bool *global);
 474
 475
 476 /**
 477  * @brief Sets a notification alarm to be triggered at a specific time.
 478  * @details The @a date describes the time of the alarm occurrence.
 479  *          To cancel the alarm, call alarm_cancel() with @a alarm_id.
 480  * @since_tizen 3.0
 481  * @privlevel public
 482  * @privilege %http://tizen.org/privilege/alarm.set
 483  * @privilege %http://tizen.org/privilege/notification
 484  * @remarks If application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 485  *          When the alarm goes off, Alarm Manager will turn on LCD to prohibit background jobs.
 486  *
 487  * @param[in] noti The notification to be posted when the alarm is triggered
 488  * @param[in] date The active alarm time
 489  * @param[out] alarm_id The ID which uniquely identifies the scheduled alarm
 490  * @return @c 0 on success,
 491  *         otherwise a negative error value
 492  * @retval  #ALARM_ERROR_NONE   Successful
 493  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 494  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 495  * @retval  #ALARM_ERROR_INVALID_DATE Triggered date is invalid
 496  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 497  * @see alarm_cancel()
 498  * @see alarm_cancel_all()
 499  * @see alarm_get_scheduled_date()
 500  */
 501 int alarm_schedule_noti_once_at_date(notification_h noti, struct tm *date, int *alarm_id);
 502
 503 /**
 504  * @brief Sets a notification alarm to be triggered after a specific delay.
 505  * @details The alarm will first go off after @a delay seconds.
 506  *          The alarm will then go off every period seconds until canceled.
 507  *          To cancel the alarm, call alarm_cancel() with @a alarm_id.
 508  * @since_tizen 3.0
 509  * @privlevel public
 510  * @privilege %http://tizen.org/privilege/alarm.set
 511  * @privilege %http://tizen.org/privilege/notification
 512  * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 513  *          This function is a minimally intrusive way to trigger alarms when precision is not important.
 514  *          The system will adjust the @a delay and @a period requests to suit internal needs; the requests
 515  *          will be treated as minimum values. Note that @a period cannot be less than 600 seconds, if
 516  *          a smaller request is supplied it will be silently adjusted to a request of 600.
 517  *          When the alarm goes off, Alarm Manager will turn on LCD to prohibit background jobs.
 518  *          Since 6.0, You can use #alarm_standard_interval_e for @a period. If you use it, the period of alarm is guaranteed.
 519  *          Since 6.0, Note that @a period cannot be less than 900 seconds.
 520  *
 521  * @param[in] noti The notification to be posted when the alarm is triggered
 522  * @param[in] delay The amount of time before the first execution (in seconds).
 523  * @param[in] period The amount of time between subsequent alarms (in seconds).
 524  *            Since 6.0 this can be one of the values of #alarm_standard_interval_e. If you uses raw integer value, the value will be phase-aligned with other period of alarm.
 525  * @param[out] alarm_id The ID which uniquely identifies the scheduled alarm
 526  * @return @c 0 on success,
 527  *         otherwise a negative error value
 528  * @retval #ALARM_ERROR_NONE Successful
 529  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 530  * @retval #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 531  * @retval #ALARM_ERROR_INVALID_TIME Triggered time is invalid
 532  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 533  * @see alarm_cancel()
 534  * @see alarm_cancel_all()
 535  * @see alarm_get_scheduled_date()
 536  * @see alarm_get_scheduled_period()
 537  * @see alarm_schedule_noti_once_after_delay()
 538  */
 539 int alarm_schedule_noti_after_delay(notification_h noti, int delay, int period, int *alarm_id);
 540
 541 /**
 542  * @brief Sets a notification alarm to be triggered after a specific delay.
 543  * @details The alarm will go off @a delay seconds later.
 544  *          To cancel the alarm, call alarm_cancel() with @a alarm_id.
 545  * @since_tizen 3.0
 546  * @privlevel public
 547  * @privilege %http://tizen.org/privilege/alarm.set
 548  * @privilege %http://tizen.org/privilege/notification
 549  * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 550  *          When the alarm goes off, Alarm Manager will turn on LCD to prohibit background jobs.
 551  *
 552  * @param[in] noti The notification to be posted when the alarm is triggered
 553  * @param[in] delay The amount of time before the execution (in seconds)
 554  * @param[out] alarm_id The ID which uniquely identifies the scheduled alarm
 555  * @return @c 0 on success,
 556  *         otherwise a negative error value
 557  * @retval #ALARM_ERROR_NONE Successful
 558  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 559  * @retval #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 560  * @retval #ALARM_ERROR_INVALID_TIME Triggered time is invalid
 561  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 562  * @see alarm_cancel()
 563  * @see alarm_cancel_all()
 564  * @see alarm_get_scheduled_date()
 565  */
 566 int alarm_schedule_noti_once_after_delay(notification_h noti, int delay, int *alarm_id);
 567
 568 /**
 569  * @brief Sets a notification to be triggered periodically, starting at a specific time.
 570  * @details The @a date describes the time of the first occurrence.
 571  *              @a week_flag describes the day(s) of the week when the notification recurs.
 572  *              If @a week_flag is #ALARM_WEEK_FLAG_TUESDAY, the alarm will repeat every Tuesday at a specific time.
 573  *              If @a week_flag is less than or equal to zero, the alarm is not repeated.
 574  *              To cancel the alarm, call alarm_cancel() with @a alarm_id.
 575  * @since_tizen 3.0
 576  * @privlevel public
 577  * @privilege %http://tizen.org/privilege/alarm.set
 578  * @privilege %http://tizen.org/privilege/notification
 579  * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 580  *
 581  * @param[in] noti The notification to be posted when the alarm is triggered
 582  * @param[in] date The first active alarm time
 583  * @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
 584  * @param[out] alarm_id The ID which uniquely identifies the scheduled alarm
 585  * @return @c 0 on success,
 586  *         otherwise a negative error value
 587  * @retval #ALARM_ERROR_NONE Successful
 588  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 589  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 590  * @retval #ALARM_ERROR_INVALID_DATE Triggered date is invalid
 591  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 592  * @see alarm_cancel()
 593  * @see alarm_cancel_all()
 594  * @see alarm_get_scheduled_recurrence_week_flag()
 595  * @see alarm_get_scheduled_date()
 596  * @see #alarm_week_flag_e
 597  */
 598 int alarm_schedule_noti_with_recurrence_week_flag(notification_h noti, struct tm *date, int week_flag, int *alarm_id);
 599
 600 /**
 601  * @brief Gets the notification to be posted when an alarm is triggered.
 602  * @since_tizen 3.0
 603  * @privlevel public
 604  * @privilege %http://tizen.org/privilege/alarm.get
 605  * @remarks @a noti must be released using notification_free().
 606  *
 607  * @param[in] alarm_id The ID which uniquely identifies a scheduled alarm
 608  * @param[out] noti The notification to be posted when the alarm is triggered
 609  * @return @c 0 on success,
 610  *         otherwise a negative error value
 611  * @retval #ALARM_ERROR_NONE Successful
 612  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 613  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 614  * @retval #ALARM_ERROR_OUT_OF_MEMORY Out of memory
 615  * @see alarm_schedule_noti_once_at_date()
 616  * @see alarm_schedule_noti_after_delay()
 617  * @see alarm_schedule_noti_once_after_delay()
 618  * @see alarm_schedule_noti_with_recurrence_week_flag()
 619  */
 620 int alarm_get_notification(int alarm_id, notification_h *noti);
 621
 622 /**
 623  * @brief Updates the delay of the registered alarm.
 624  * @details The @a delay is the time (in seconds) before the alarm's first setting off.
 625  *          The delay is an exact value, see alarm_schedule_once_after_delay() for details.
 626  *          This function can be called for any alarm.
 627  *          If the delay was set before, it will be overwritten. If it was not, it will be set.
 628  * @since_tizen 4.0
 629  * @privlevel public
 630  * @privilege %http://tizen.org/privilege/alarm.set
 631  * @remarks This function can be called only for alarms whose app control launches an UI application.
 632  *          If this condition is not met, #ALARM_ERROR_NOT_PERMITTED_APP is returned.
 633  * @param[in] alarm_id  The ID which uniquely identifies the scheduled alarm
 634  * @param[in] delay     The amount of time before the first execution (in seconds).
 635  * @return @c 0 on success,
 636  *         otherwise a negative error value
 637  * @retval #ALARM_ERROR_NONE               Successful
 638  * @retval #ALARM_ERROR_PERMISSION_DENIED  Permission denied
 639  * @retval #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 640  * @retval #ALARM_ERROR_CONNECTION_FAIL    Failed to connect to an alarm server
 641  * @retval #ALARM_ERROR_OUT_OF_MEMORY      Out of memory
 642  * @retval #ALARM_ERROR_NOT_PERMITTED_APP  App control does not launch an UI application
 643  */
 644 int alarm_update_delay(int alarm_id, int delay);
 645
 646 /**
 647  * @brief Updates the date of the registered alarm.
 648  * @details The @a date describes the date on which the alarm is set off for the first time.
 649  *          This function can be called for any alarm.
 650  *          If the date was set before, it will be overwritten. If it was not, it will be set.
 651  * @since_tizen 4.0
 652  * @privlevel public
 653  * @privilege %http://tizen.org/privilege/alarm.set
 654  * @remarks This function can be called only for alarms whose app control launches an UI application.
 655  *          If this condition is not met, #ALARM_ERROR_NOT_PERMITTED_APP is returned.
 656  * @param[in] alarm_id  The ID which uniquely identifies the scheduled alarm
 657  * @param[in] date      The time value of the next alarm event
 658  * @return @c 0 on success,
 659  *         otherwise a negative error value
 660  * @retval #ALARM_ERROR_NONE               Successful
 661  * @retval #ALARM_ERROR_PERMISSION_DENIED  Permission denied
 662  * @retval #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 663  * @retval #ALARM_ERROR_INVALID_TIME       Triggered time is invalid
 664  * @retval #ALARM_ERROR_INVALID_DATE       Triggered time is invalid
 665  * @retval #ALARM_ERROR_CONNECTION_FAIL    Failed to connect to an alarm server
 666  * @retval #ALARM_ERROR_OUT_OF_MEMORY      Out of memory
 667  * @retval #ALARM_ERROR_NOT_PERMITTED_APP  App control does not launch an UI application
 668  */
 669 int alarm_update_date(int alarm_id, struct tm *date);
 670
 671 /**
 672  * @brief Updates the period of the registered alarm.
 673  * @details The alarm will then go off every @a period seconds until canceled.
 674  *          This function can be called for any alarm.
 675  *          If the week recurrence flag was set before, it will be removed and the period will be set.
 676  *          If the period was set before, it will be overwritten. If it was not, it will be set.
 677  *          If the @a period argument is 0 and the period was previously set,
 678  *          the period attribute will be cleared and the alarm will be changed to one-time.
 679  *          If the @a period argument is 0 and the period was not set,
 680  *          or the week recurrence flag was set, the alarm will be unchanged.
 681  * @since_tizen 4.0
 682  * @privlevel public
 683  * @privilege %http://tizen.org/privilege/alarm.set
 684  * @param[in] alarm_id  The ID which uniquely identifies the scheduled alarm
 685  * @param[in] period    The amount of time between subsequent alarms (in seconds).
 686  *                      Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif, this
 687  *                      value does not guarantee the accuracy. The actual interval
 688  *                      is calculated by the OS. The minimum value is 600sec.
 689  * @return @c 0 on success,
 690  *         otherwise a negative error value
 691  * @retval #ALARM_ERROR_NONE               Successful
 692  * @retval #ALARM_ERROR_PERMISSION_DENIED  Permission denied
 693  * @retval #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 694  * @retval #ALARM_ERROR_CONNECTION_FAIL    Failed to connect to an alarm server
 695  * @retval #ALARM_ERROR_OUT_OF_MEMORY      Out of memory
 696  */
 697 int alarm_update_period(int alarm_id, int period);
 698
 699 /**
 700  * @brief Updates the week recurrence flag of the registered alarm.
 701  * @details @a week_flag is the repeat value of the days of the week.
 702  *          For example, if @a week_flag is #ALARM_WEEK_FLAG_TUESDAY, the alarm will repeat every
 703  *          Tuesday at a specific time.
 704  *          This function can be called for any alarm.
 705  *          If the period was set before, it will be removed and the week recurrence flag will be set.
 706  *          If the week recurrence flag was set before, it will be overwritten. If it was not, it will be set.
 707  *          If the @a week_flag argument is 0 and the flag was previously set,
 708  *          the flag attribute will be cleared and the alarm will be changed to one-time.
 709  *          If the @a week_flag argument is 0 and the flag was not set,
 710  *          or the period was set, the alarm will be unchanged.
 711  * @since_tizen 4.0
 712  * @privlevel public
 713  * @privilege %http://tizen.org/privilege/alarm.set
 714  * @remarks This function can be called only for alarms whose app control launches an UI application.
 715  *          If this condition is not met, #ALARM_ERROR_NOT_PERMITTED_APP is returned.
 716  * @param[in] alarm_id   The ID which uniquely identifies the scheduled alarm
 717  * @param[in] week_flag  The day of the week, @a week_flag may be a combination
 718  *                       of days, like #ALARM_WEEK_FLAG_TUESDAY | #ALARM_WEEK_FLAG_FRIDAY
 719  * @return @c 0 on success,
 720  *         otherwise a negative error value
 721  * @retval #ALARM_ERROR_NONE               Successful
 722  * @retval #ALARM_ERROR_PERMISSION_DENIED  Permission denied
 723  * @retval #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 724  * @retval #ALARM_ERROR_CONNECTION_FAIL    Failed to connect to an alarm server
 725  * @retval #ALARM_ERROR_OUT_OF_MEMORY      Out of memory
 726  * @retval #ALARM_ERROR_NOT_PERMITTED_APP  App control does not launch an UI application
 727  */
 728 int alarm_update_week_flag(int alarm_id, int week_flag);
 729
 730 /**
 731  * @}
 732  */
 733
 734 #ifdef __cplusplus
 735 }
 736 #endif
 737
 738 #endif /* __TIZEN_APPFW_ALARM_H__ */
 739