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_service.h>
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 /**
  30  * @addtogroup CAPI_ALARM_MODULE
  31  * @{
  32  */
  33
  34 /**
  35  * @brief       Service extra data : the id of the alarm registered
  36  */
  37 #define SERVICE_DATA_ALARM_ID "http://tizen.org/appcontrol/data/alarm_id"
  38
  39 /**
  40  * @brief   Enumerations of error codes for the alarm
  41  */
  42 typedef enum
  43 {
  44         ALARM_ERROR_NONE = TIZEN_ERROR_NONE,    /**< Successful */
  45         ALARM_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,  /**< Invalid parameter */
  46         ALARM_ERROR_INVALID_TIME = TIZEN_ERROR_APPLICATION_CLASS | 0x05,        /**< Invalid time */
  47         ALARM_ERROR_INVALID_DATE = TIZEN_ERROR_APPLICATION_CLASS | 0x06,        /**< Invalid date */
  48         ALARM_ERROR_CONNECTION_FAIL = TIZEN_ERROR_APPLICATION_CLASS | 0x07,     /**< The alarm service connection failed */
  49         ALARM_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY   /**< Out of memory */
  50 } alarm_error_e;
  51
  52
  53 /**
  54  * @brief   Enumerations of the days of the week.
  55  */
  56 typedef enum
  57 {
  58         ALARM_WEEK_FLAG_SUNDAY = 0x01,  /**< Sunday */
  59         ALARM_WEEK_FLAG_MONDAY = 0x02,  /**< Monday */
  60         ALARM_WEEK_FLAG_TUESDAY = 0x04, /**< Tuesday */
  61         ALARM_WEEK_FLAG_WEDNESDAY = 0x08,       /**< Wednesday */
  62         ALARM_WEEK_FLAG_THURSDAY = 0x10,        /**< Thursday */
  63         ALARM_WEEK_FLAG_FRIDAY = 0x20,  /**< Friday */
  64         ALARM_WEEK_FLAG_SATURDAY = 0x40 /**< Saturday */
  65 } alarm_week_flag_e;
  66
  67 /**
  68  * @brief       Called once for each scheduled alarm to get the alarm ID.
  69  *
  70  * @param[in]   alarm_id        The alarm ID returned when the alarm is scheduled
  71  * @param[in]   user_data       The user data passed from the foreach function
  72  * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
  73  * @pre alarm_foreach_registered_alarm() will invoke this callback to get all registered alarm IDs.
  74  * @see alarm_foreach_registered_alarm()
  75  */
  76 typedef bool (*alarm_registered_alarm_cb)(int alarm_id, void *user_data);
  77
  78 /**
  79  * @brief   Sets an alarm to be triggered after specific time.
  80  * @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.
  81  * If @a period is bigger than 0, the alarm will be scheduled after the @a period time.
  82  * If @a period is set to 0, the alarm will go off just once without repetition.
  83  * To cancel the alarm, call alarm_cancel() with @alarm_id
  84  *
  85  * @remarks  If application is uninstalled after setting an alarm, the alarm is canceled automatically.
  86  *
  87  * @param[in]   service The destination service to perform specific work when the alarm is triggered.
  88  * @param[in]   delay   The amount of time before first execution(in second)
  89  * @param[in]   period  The amount of time between subsequent alarms(in second)
  90  * @param[out]  alarm_id        The alarm ID uniquely identifies an alarm
  91  * @return      0 on success, otherwise a negative error value.
  92  * @retval  #ALARM_ERROR_NONE Successful
  93  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
  94  * @retval  #ALARM_ERROR_INVALID_TIME Triggered time is invalid
  95  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
  96  * @see alarm_cancel()
  97  * @see alarm_cancel_all()
  98  * @see alarm_get_scheduled_date()
  99  * @see alarm_get_scheduled_period()
 100  */
 101 int alarm_schedule_after_delay(service_h service, int delay, int period, int *alarm_id);
 102
 103
 104 /**
 105  * @brief   Sets an alarm to be triggered at a specific time.
 106  * @details
 107  * The @a date describes the time of first occurrence.
 108  * If @a period is bigger than 0, the alarm will be scheduled after the @a period time.
 109  * If @a period is set to 0, the alarm will go off just once without repetition.
 110  * To cancel the alarm, call alarm_cancel() with alarm id
 111  *
 112  * @remarks  If application is uninstalled after setting an alarm, the alarm is canceled automatically.
 113  *
 114  * @param[in]   service The destination service to perform specific work when the alarm is triggered
 115  * @param[in]   date    The first active alarm time
 116  * @param[in]   period  The amount of time between subsequent alarms(in second)
 117  * @param[out]  alarm_id        The alarm ID uniquely identifies an alarm
 118  * @return      0 on success, otherwise a negative error value.
 119  * @retval  #ALARM_ERROR_NONE   Successful
 120  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 121  * @retval  #ALARM_ERROR_INVALID_DATE Triggered date is invalid
 122  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 123  * @see alarm_cancel()
 124  * @see alarm_cancel_all()
 125  * @see alarm_get_scheduled_date()
 126  * @see alarm_get_scheduled_period()
 127  */
 128 int alarm_schedule_at_date(service_h service, struct tm *date, int period, int *alarm_id);
 129
 130
 131 /**
 132  * @brief   Sets an alarm to be triggered at a specific time with recurrence repeat.
 133  * @details
 134  * The @a date describes the time of first occurrence.
 135  * @a week_flag is the repeat value of days of the week. If @a week_flag is #ALARM_WEEK_FLAG_TUESDAY, the alarm will repeat at every Tuesday specific time.
 136  * To cancel the alarm, call alarm_cancel() with the @alarm_id
 137  * @remarks  If application is uninstalled after setting an alarm, the alarm is canceled automatically.
 138  *
 139  * @param[in]   service The destination service to perform specific work when the alarm is triggered.
 140  * @param[in]   date    The first active alarm time
 141  * @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.
 142  * @param[out]  alarm_id        The alarm ID uniquely identifies an alarm
 143  * @return      0 on success, 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  * @see alarm_cancel()
 149  * @see alarm_cancel_all()
 150  * @see alarm_get_scheduled_recurrence_week_flag()
 151  * @see alarm_get_scheduled_recurrence_week_flag()
 152  * @see alarm_get_scheduled_date()
 153  * @see #alarm_week_flag_e
 154  */
 155 int alarm_schedule_with_recurrence_week_flag(service_h service, struct tm *date, int week_flag,int *alarm_id);
 156
 157
 158 /**
 159  * @brief Gets the recurrence days of the week.
 160  * @remarks If the given @a alarm_id is not obtained by using the alarm_schedule_with_recurrence_week_flag() function,
 161  * an error (error code #ALARM_ERROR_INVALID_PARAMETER) will occur because this alarm is scheduled with no recurrence.
 162  * @param[in]   alarm_id        The alarm ID returned when the alarm is scheduled
 163  * @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.
 164  * @return 0 on success, otherwise a negative error value.
 165  * @retval  #ALARM_ERROR_NONE                Successful
 166  * @retval  #ALARM_ERROR_INVALID_PARAMETER   Invalid parameter
 167  * @see alarm_schedule_with_recurrence_week_flag()
 168  * @see #alarm_week_flag_e
 169  */
 170 int alarm_get_scheduled_recurrence_week_flag(int alarm_id, int *week_flag);
 171
 172
 173 /**
 174  * @brief   Cancels the alarm with the specific alarm ID.
 175  * @param[in] alarm_id  The alarm ID that will be canceled
 176  * @return      0 on success, otherwise a negative error value.
 177  * @retval  #ALARM_ERROR_NONE Successful
 178  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 179  * @see alarm_schedule_at_date()
 180  * @see alarm_schedule_after_delay()
 181  * @see alarm_schedule_with_recurrence_week_flag()
 182  * @see alarm_cancel_all()
 183  */
 184 int alarm_cancel(int alarm_id);
 185
 186
 187 /**
 188  * @brief   Cancels all alarms scheduled.
 189  *
 190  * @return  0 on success, otherwise a negative error value.
 191  * @retval  #ALARM_ERROR_NONE Successful
 192  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 193  * @see alarm_schedule_at_date()
 194  * @see alarm_schedule_after_delay()
 195  * @see alarm_schedule_with_recurrence_week_flag()
 196  * @see alarm_cancel()
 197  */
 198 int alarm_cancel_all(void);
 199
 200
 201 /**
 202  * @brief   Retrieves the IDs of all registered alarms by invoking callback once for each scheduled alarm.
 203  *
 204  * @param[in]   callback        The callback function to invoke
 205  * @param[in]   user_data       The user data to be passed to the callback function
 206  * @return      0 on success, otherwise a negative error value.
 207  * @retval  #ALARM_ERROR_NONE   Successful
 208  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 209  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 210  * @post        This function invokes alarm_registered_alarm_cb() repeatedly for each registered alarm.
 211  * @see alarm_registered_alarm_cb()
 212  */
 213 int alarm_foreach_registered_alarm(alarm_registered_alarm_cb callback, void *user_data);
 214
 215
 216 /**
 217  * @brief   Gets the scheduled time from the given alarm ID in C standard time struct.
 218  *
 219  * @param[in]   alarm_id        The alarm ID returned when the alarm is scheduled
 220  * @param[out]  date    The time value of next alarm event
 221  * @return  0 on success, otherwise a negative error value.
 222  * @retval  #ALARM_ERROR_NONE   Successful
 223  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 224  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 225  * @see alarm_schedule_at_date()
 226  * @see alarm_schedule_after_delay()
 227  * @see alarm_schedule_with_recurrence_week_flag()
 228  */
 229 int alarm_get_scheduled_date(int alarm_id, struct tm *date);
 230
 231
 232 /**
 233  * @brief   Gets the period of time between the recurrent alarms.
 234  * @remarks If the given @a alarm_id is not obtained by using the alarm_get_scheduled_date() or  alarm_schedule_after_delay() function,
 235  * an error (error code #ALARM_ERROR_INVALID_PARAMETER) will occur.
 236  * @param[in]   alarm_id The alarm ID returned when the alarm is scheduled
 237  * @param[out]  period   The period of time between recurrent alarms in seconds
 238  * @return  0 on success, otherwise a negative error value.
 239  * @retval  #ALARM_ERROR_NONE   Successful
 240  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 241  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 242  * @see alarm_schedule_at_date()
 243  * @see alarm_schedule_after_delay()
 244  * @see alarm_schedule_with_recurrence_week_flag()
 245  */
 246 int alarm_get_scheduled_period(int alarm_id, int *period);
 247
 248
 249 /**
 250  * @brief   Gets the current system time using C standard time struct.
 251  *
 252  * @param[out] date The current system time
 253  * @return  0 on success, otherwise a negative error value.
 254  * @retval  #ALARM_ERROR_NONE   Successful
 255  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 256  */
 257 int alarm_get_current_time(struct tm *date);
 258
 259
 260 /**
 261  * @brief Gets the service to be invoked when the the alarm is triggered
 262  * @remarks The @a service must be released with service_destroy() by you.
 263  * @param[in]   alarm_id        The alarm ID uniquely identifies an alarm
 264  * @param[out] service The service handle to launch when the alarm is triggered
 265  * @return 0 on success, otherwise a negative error value.
 266  * @retval #ALARM_ERROR_NONE Successful
 267  * @retval #ALARM_ERROR_INVALID_PARAMETER Invalid parameter
 268  * @retval #ALARM_ERROR_OUT_OF_MEMORY Out of memory
 269  * @see alarm_schedule_at_date()
 270  * @see alarm_schedule_after_delay()
 271  * @see alarm_schedule_with_recurrence_week_flag()
 272  */
 273 int alarm_get_service(int alarm_id, service_h *service);
 274
 275 /**
 276  * @}
 277  */
 278
 279 #ifdef __cplusplus
 280 }
 281 #endif
 282
 283 #endif /* __TIZEN_APPFW_ALARM_H__ */
 284