include/app_alarm.h

   1 /*
   2  * Copyright (c) 2011 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
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 /**
  30  * @file app_alarm.h
  31  */
  32
  33 /**
  34  * @addtogroup CAPI_ALARM_MODULE
  35  * @{
  36  */
  37
  38 /**
  39  * @brief Definition to app_control extra data : the ID of the alarm registered.
  40  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  41  */
  42 #define APP_CONTROL_DATA_ALARM_ID "http://tizen.org/appcontrol/data/alarm_id"
  43
  44 /**
  45  * @brief Enumeration for Alarm Error.
  46  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  47  */
  48 typedef enum
  49 {
  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_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,  /**< Out of memory */
  56         ALARM_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED   /**< Permission denied */
  57 } alarm_error_e;
  58
  59
  60 /**
  61  * @brief Enumeration for Alarm Week Flag, the days of the week.
  62  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  63  */
  64 typedef enum
  65 {
  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  * @deprecated Deprecated since 2.4. [Use alarm_schedule_once_after_delay() instead]
  90  * @brief Sets an alarm to be triggered after a specific time.
  91  * @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.
  92  *          If @a period is bigger than @c 0, the alarm will be scheduled after the @a period time.
  93  *          If @a period is set to @c 0, the alarm will go off just once without repetition.
  94  *          To cancel the alarm, call alarm_cancel() with @a alarm_id.
  95  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  96  * @privlevel   public
  97  * @privilege   %http://tizen.org/privilege/alarm.set
  98  * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
  99  *
 100  * @param[in] app_control The destination app_control to perform a specific task when the alarm is triggered
 101  * @param[in] delay     The amount of time before the first execution (in seconds)
 102  * @param[in] period The amount of time between subsequent alarms (in seconds)
 103  * @param[out] alarm_id The alarm ID that uniquely identifies an alarm
 104  * @return      @c 0 on success,
 105  *          otherwise a negative error value
 106  * @retval  #ALARM_ERROR_NONE Successful
 107  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 108  * @retval  #ALARM_ERROR_INVALID_TIME Triggered time is invalid
 109  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 110  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 111  * @see alarm_cancel()
 112  * @see alarm_cancel_all()
 113  * @see alarm_get_scheduled_date()
 114  * @see alarm_get_scheduled_period()
 115  */
 116 int alarm_schedule_after_delay(app_control_h app_control, int delay, int period, int *alarm_id);
 117
 118
 119 /**
 120  * @deprecated Deprecated since 2.4. [Use alarm_schedule_once_at_date() instead]
 121  * @brief Sets an alarm to be triggered at a specific time.
 122  * @details The @a date describes the time of the first occurrence.
 123  *          If @a period is bigger than @c 0, the alarm will be scheduled after the @a period time.
 124  *          If @a period is set to @c 0, the alarm will go off just once without repetition.
 125  *          To cancel the alarm, call alarm_cancel() with @a alarm_id.
 126  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 127  * @privlevel   public
 128  * @privilege   %http://tizen.org/privilege/alarm.set
 129  * @remarks If application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 130  *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
 131  *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
 132  *
 133  * @param[in]   app_control The destination app_control to perform specific work when the alarm is triggered
 134  * @param[in]   date    The first active alarm time
 135  * @param[in]   period  The amount of time between subsequent alarms(in second)
 136  * @param[out]  alarm_id        The alarm ID that uniquely identifies an alarm
 137  * @return      @c 0 on success,
 138  *          otherwise a negative error value
 139  * @retval  #ALARM_ERROR_NONE   Successful
 140  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 141  * @retval  #ALARM_ERROR_INVALID_DATE Triggered date is invalid
 142  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 143  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 144  * @see alarm_cancel()
 145  * @see alarm_cancel_all()
 146  * @see alarm_get_scheduled_date()
 147  * @see alarm_get_scheduled_period()
 148  */
 149 int alarm_schedule_at_date(app_control_h app_control, struct tm *date, int period, int *alarm_id);
 150
 151 /**
 152  * @brief Sets an alarm to be triggered after a specific time.
 153  * @details The alarm will go off @a delay seconds later.
 154  *          To cancel the alarm, call alarm_cancel() with @a alarm_id.
 155  * @since_tizen 2.4
 156  * @privlevel   public
 157  * @privilege   %http://tizen.org/privilege/alarm.set
 158  * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 159  *
 160  * @param[in] app_control The destination app_control to perform a specific task when the alarm is triggered
 161  * @param[in] delay     The amount of time before the execution (in seconds)
 162  * @param[out] alarm_id The alarm ID that uniquely identifies an alarm
 163  * @return      @c 0 on success,
 164  *          otherwise a negative error value
 165  * @retval  #ALARM_ERROR_NONE Successful
 166  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 167  * @retval  #ALARM_ERROR_INVALID_TIME Triggered time is invalid
 168  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 169  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 170  * @see alarm_cancel()
 171  * @see alarm_cancel_all()
 172  * @see alarm_get_scheduled_date()
 173  * @see alarm_get_scheduled_period()
 174  */
 175 int alarm_schedule_once_after_delay(app_control_h app_control, int delay, int *alarm_id);
 176
 177
 178 /**
 179  * @brief Sets an alarm to be triggered at a specific time.
 180  * @details The @a date describes the time of the first occurrence.
 181  *          To cancel the alarm, call alarm_cancel() with @a alarm_id.
 182  * @since_tizen 2.4
 183  * @privlevel   public
 184  * @privilege   %http://tizen.org/privilege/alarm.set
 185  * @remarks If application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 186  *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
 187  *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
 188  *
 189  * @param[in]   app_control The destination app_control to perform specific work when the alarm is triggered
 190  * @param[in]   date    The first active alarm time
 191  * @param[out]  alarm_id        The alarm ID that uniquely identifies an alarm
 192  * @return      @c 0 on success,
 193  *          otherwise a negative error value
 194  * @retval  #ALARM_ERROR_NONE   Successful
 195  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 196  * @retval  #ALARM_ERROR_INVALID_DATE Triggered date is invalid
 197  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 198  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 199  * @see alarm_cancel()
 200  * @see alarm_cancel_all()
 201  * @see alarm_get_scheduled_date()
 202  * @see alarm_get_scheduled_period()
 203  */
 204 int alarm_schedule_once_at_date(app_control_h app_control, struct tm *date, int *alarm_id);
 205
 206 /**
 207  * @brief Sets an alarm to be triggered periodically, starting at a specific time.
 208  * @details The @a date describes the time of the first occurrence.
 209  *              @a week_flag is the repeat value of the days of the week.
 210  *              If @a week_flag is #ALARM_WEEK_FLAG_TUESDAY, the alarm will repeat every Tuesday at a specific time.
 211  *              To cancel the alarm, call alarm_cancel() with @a alarm_id.
 212  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 213  * @privlevel   public
 214  * @privilege   %http://tizen.org/privilege/alarm.set
 215  * @remarks If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
 216  *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
 217  *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
 218  *
 219  * @param[in] app_control The destination app_control to perform specific work when the alarm is triggered
 220  * @param[in] date      The first active alarm time
 221  * @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
 222  * @param[out] alarm_id The alarm ID that uniquely identifies an alarm
 223  * @return @c 0 on success,
 224  *         otherwise a negative error value
 225  * @retval #ALARM_ERROR_NONE Successful
 226  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 227  * @retval #ALARM_ERROR_INVALID_DATE Triggered date is invalid
 228  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 229  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 230  * @see alarm_cancel()
 231  * @see alarm_cancel_all()
 232  * @see alarm_get_scheduled_recurrence_week_flag()
 233  * @see alarm_get_scheduled_date()
 234  * @see #alarm_week_flag_e
 235  */
 236 int alarm_schedule_with_recurrence_week_flag(app_control_h app_control, struct tm *date, int week_flag,int *alarm_id);
 237
 238
 239 /**
 240  * @brief Gets the recurrence days of the week.
 241  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 242  * @privlevel   public
 243  * @privilege   %http://tizen.org/privilege/alarm.get
 244  * @remarks If the given @a alarm_id is not obtained by using the alarm_schedule_with_recurrence_week_flag() function,
 245  *          an error (error code #ALARM_ERROR_INVALID_PARAMETER) will occur because this alarm is scheduled with no recurrence.
 246  *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
 247  *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
 248  * @param[in] alarm_id The alarm ID returned when the alarm is scheduled
 249  * @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
 250  * @return @c 0 on success,
 251  *         otherwise a negative error value
 252  * @retval #ALARM_ERROR_NONE Successful
 253  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 254  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 255  * @see alarm_schedule_with_recurrence_week_flag()
 256  * @see #alarm_week_flag_e
 257  */
 258 int alarm_get_scheduled_recurrence_week_flag(int alarm_id, int *week_flag);
 259
 260
 261 /**
 262  * @brief Cancels the alarm with the specific alarm ID.
 263  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 264  * @privlevel   public
 265  * @privilege   %http://tizen.org/privilege/alarm.set
 266  * @param[in] alarm_id  The alarm ID that is cancelled
 267  * @return @c 0 on success,
 268  *         otherwise a negative error value
 269  * @retval #ALARM_ERROR_NONE Successful
 270  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 271  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 272  * @see alarm_schedule_at_date()
 273  * @see alarm_schedule_after_delay()
 274  * @see alarm_schedule_with_recurrence_week_flag()
 275  * @see alarm_cancel_all()
 276  */
 277 int alarm_cancel(int alarm_id);
 278
 279
 280 /**
 281  * @brief Cancels all scheduled alarms that are registered by the application that calls this API.
 282  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 283  * @privlevel   public
 284  * @privilege   %http://tizen.org/privilege/alarm.set
 285  * @return  @c 0 on success,
 286  *          otherwise a negative error value
 287  * @retval  #ALARM_ERROR_NONE Successful
 288  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 289  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 290  * @see alarm_schedule_at_date()
 291  * @see alarm_schedule_after_delay()
 292  * @see alarm_schedule_with_recurrence_week_flag()
 293  * @see alarm_cancel()
 294  */
 295 int alarm_cancel_all(void);
 296
 297
 298 /**
 299  * @brief Retrieves the IDs of all registered alarms by invoking a callback once for each scheduled alarm.
 300  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 301  * @privlevel   public
 302  * @privilege   %http://tizen.org/privilege/alarm.get
 303  * @param[in] callback The callback function to invoke
 304  * @param[in] user_data The user data to be passed to the callback function
 305  * @return @c 0 on success,
 306  *         otherwise a negative error value
 307  * @retval #ALARM_ERROR_NONE   Successful
 308  * @retval #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 309  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 310  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 311  * @post   This function invokes alarm_registered_alarm_cb() repeatedly for each registered alarm.
 312  * @see alarm_registered_alarm_cb()
 313  */
 314 int alarm_foreach_registered_alarm(alarm_registered_alarm_cb callback, void *user_data);
 315
 316
 317 /**
 318  * @brief Gets the scheduled time from the given alarm ID in C standard time struct.
 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] alarm_id The alarm ID returned when the alarm is scheduled
 323  * @param[out] date     The time value of the next alarm event
 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  * @see alarm_schedule_at_date()
 331  * @see alarm_schedule_after_delay()
 332  * @see alarm_schedule_with_recurrence_week_flag()
 333  */
 334 int alarm_get_scheduled_date(int alarm_id, struct tm *date);
 335
 336
 337 /**
 338  * @brief Gets the period of time between the recurrent alarms.
 339  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 340  * @privlevel   public
 341  * @privilege   %http://tizen.org/privilege/alarm.get
 342  * @remarks If the given @a alarm_id is not obtained by using the alarm_get_scheduled_date() or alarm_schedule_after_delay() function,
 343  *          an error (error code #ALARM_ERROR_INVALID_PARAMETER) will occur.
 344  * @param[in] alarm_id The alarm ID returned when the alarm is scheduled
 345  * @param[out] period The period of time between recurrent alarms in seconds
 346  * @return @c 0 on success,
 347  *         otherwise a negative error value
 348  * @retval #ALARM_ERROR_NONE   Successful
 349  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 350  * @retval #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 351  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 352  * @see alarm_schedule_at_date()
 353  * @see alarm_schedule_after_delay()
 354  * @see alarm_schedule_with_recurrence_week_flag()
 355  */
 356 int alarm_get_scheduled_period(int alarm_id, int *period);
 357
 358
 359 /**
 360  * @brief Gets the current system time using C standard time struct.
 361  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 362  * @param[out] date The current system time
 363  * @return @c 0 on success,
 364  *         otherwise a negative error value
 365  * @retval #ALARM_ERROR_NONE Successful
 366  * @retval #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 367  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
 368  */
 369 int alarm_get_current_time(struct tm *date);
 370
 371
 372 /**
 373  * @brief Gets the app_control to be invoked when the the alarm is triggered.
 374  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 375  * @privlevel   public
 376  * @privilege   %http://tizen.org/privilege/alarm.get
 377  * @remarks The @a app_control must be released using app_control_destroy().
 378  * @param[in] alarm_id The alarm ID uniquely identifies an alarm
 379  * @param[out] app_control The app_control handle to launch when the alarm is triggered
 380  * @return @c 0 on success,
 381  *         otherwise a negative error value
 382  * @retval #ALARM_ERROR_NONE Successful
 383  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 384  * @retval #ALARM_ERROR_OUT_OF_MEMORY Out of memory
 385  * @retval #ALARM_ERROR_PERMISSION_DENIED Permission denied
 386  * @see alarm_schedule_at_date()
 387  * @see alarm_schedule_after_delay()
 388  * @see alarm_schedule_with_recurrence_week_flag()
 389  */
 390 int alarm_get_app_control(int alarm_id, app_control_h *app_control);
 391
 392 /**
 393  * @}
 394  */
 395
 396 #ifdef __cplusplus
 397 }
 398 #endif
 399
 400 #endif /* __TIZEN_APPFW_ALARM_H__ */
 401