include/app_alarm_extension.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_EXTENSION_H
  19 #define __TIZEN_APPFW_ALARM_EXTENSION_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_extension.h
  31  */
  32
  33 /**
  34  * @addtogroup CAPI_ALARM_MODULE
  35  * @{
  36  */
  37
  38 /**
  39  * @brief Sets an exact alarm to be triggered after a specific time.
  40  * @details The alarm will go off @a delay seconds later.
  41  *          To cancel the alarm, call alarm_cancel() with @a alarm_id.
  42  * @since_tizen 3.0
  43  * @privlevel   public
  44  * @privilege   %http://tizen.org/privilege/alarm.set
  45  * @remarks This API only allows service application which has Background Category to set an exact alarm.
  46  *                      If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
  47  *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used r the launch request.
  48  *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
  49  *          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.
  50  *          The @a app_control only supports service application which has Background Category with this api.
  51  *
  52  * @param[in] app_control The destination app_control to perform a specific task when the alarm is triggered
  53  * @param[in] delay     The amount of time before the execution (in seconds)
  54  * @param[out] alarm_id The alarm ID that uniquely identifies an alarm
  55  * @return      @c 0 on success,
  56  *          otherwise a negative error value
  57  * @retval  #ALARM_ERROR_NONE Successful
  58  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
  59  * @retval  #ALARM_ERROR_INVALID_TIME Triggered time is invalid
  60  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
  61  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
  62  * @see alarm_cancel()
  63  * @see alarm_cancel_all()
  64  * @see alarm_get_scheduled_date()
  65  */
  66 int alarm_schedule_service_once_after_delay(app_control_h app_control, int delay, int *alarm_id);
  67
  68 /**
  69  * @brief Sets an alarm to be triggered at a specific time.
  70  * @details The @a date describes the time of the first occurrence.
  71  *          To cancel the alarm, call alarm_cancel() with @a alarm_id.
  72  * @since_tizen 3.0
  73  * @privlevel   public
  74  * @privilege   %http://tizen.org/privilege/alarm.set
  75  * @remarks This API only allows service application which has Background Category to set an exact alarm.
  76  *                      If application is uninstalled after setting an alarm, the alarm is cancelled automatically.
  77  *          If the operation of @a app_control is not specified, #APP_CONTROL_OPERATION_DEFAULT is used for the launch request.
  78  *          If the operation of @a app_control is #APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
  79  *          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.
  80  *          The @a app_control only supports service application which has Background Category with this api.
  81  *
  82  * @param[in]   app_control The destination app_control to perform specific work when the alarm is triggered
  83  * @param[in]   date    The first active alarm time
  84  * @param[out]  alarm_id        The alarm ID that uniquely identifies an alarm
  85  * @return      @c 0 on success,
  86  *          otherwise a negative error value
  87  * @retval  #ALARM_ERROR_NONE   Successful
  88  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
  89  * @retval  #ALARM_ERROR_INVALID_DATE Triggered date is invalid
  90  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
  91  * @retval  #ALARM_ERROR_PERMISSION_DENIED Permission denied
  92  * @see alarm_cancel()
  93  * @see alarm_cancel_all()
  94  * @see alarm_get_scheduled_date()
  95  */
  96 int alarm_schedule_service_once_at_date(app_control_h app_control, struct tm *date, int *alarm_id);
  97
  98 /**
  99  * @brief Changes the system time which tranferred by other module
 100  * @since_tizen 3.0
 101  * @privlevel  platform
 102  * @privilege  %http://tizen.org/privilege/systemsettings.admin
 103  *
 104  * @param[in]  new_time epoch time to be set
 105  * @return     @c 0 on success,
 106  *          otherwise a negative error value
 107  * @retval  #ALARM_ERROR_NONE   Successful
 108  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 109  */
 110 int alarm_set_systime(int new_time);
 111
 112 /**
 113  * @brief Changes the system time and compensates the time using propagation delay
 114  * @since_tizen 3.0
 115  * @privlevel  platform
 116  * @privilege  %http://tizen.org/privilege/systemsettings.admin
 117  *
 118  * @param[in]  new_time system time to be set (seconds, nanoseconds)
 119  * @param[in]  req_time time to request to change the system time (seconds, nanoseconds)
 120  * @return     @c 0 on success,
 121  *          otherwise a negative error value
 122  * @retval  #ALARM_ERROR_NONE   Successful
 123  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 124  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 125  */
 126 int alarm_set_systime_with_propagation_delay(struct timespec new_time, struct timespec req_time);
 127
 128 /**
 129  * @brief Changes the timezone which tranferred by other module
 130  * @since_tizen 3.0
 131  * @privlevel  platform
 132  * @privilege  %http://tizen.org/privilege/systemsettings.admin
 133  *
 134  * @param[in]  tzpath_str the path to timezone definition file
 135  * @return     @c 0 on success,
 136  *          otherwise a negative error value
 137  * @retval  #ALARM_ERROR_NONE   Successful
 138  * @retval  #ALARM_ERROR_INVALID_PARAMETER  Invalid parameter
 139  * @retval  #ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server
 140  */
 141 int alarm_set_timezone(char *tzpath_str);
 142
 143 /**
 144  * @}
 145  */
 146
 147 #ifdef __cplusplus
 148 }
 149 #endif
 150
 151 #endif /* __TIZEN_APPFW_ALARM_EXTENSION_H */