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