Tizen Native API
5.5
|
The Alarm API allows setting an "alarm clock" for the delivery of a notification at some point in the future.
Required Header
#include <app_alarm.h>
Overview
Mobile devices typically give constant access to information from various sources. Some of this information is best delivered through alarms - the most obvious case is a calendar scheduling application which lets you know when a meeting is about to start. Alarms are certainly better than actively waiting in a loop. They are also better than putting an interface to sleep because they do not block your main UI thread. Use of alarms helps build smooth user experiences and implements unattended data synchronization tasks. If an application is installed after setting the alarm, your alarm is canceled automatically.
When the alarm is expired, Alarm Manager will turn on the LCD to prohibit background jobs. If you want to use alarm API without turning on the LCD, you can use alarm_schedule_after_delay(). There are 3 ways to set an alarm.
FUNCTION | DESCRIPTION |
---|---|
alarm_schedule_once_after_delay() | Sets an alarm to be triggered at specific time once |
alarm_schedule_once_at_date() | Sets an alarm to be triggered after specific delay once |
alarm_schedule_with_recurrence_week_flag() | Sets an alarm to be triggered at specific time with recurrent days of the week(can repeat on days of the week) |
alarm_schedule_after_delay() | Sets an alarm to be triggered after specific time(Since 3.0, this api does not support exact period and delay for minimizing the wakeups of the device. The system can adjust when the alarm expires.) |
Functions | |
int | alarm_schedule_after_delay (app_control_h app_control, int delay, int period, int *alarm_id) |
Sets an alarm to be triggered after a specific time. | |
int | alarm_schedule_at_date (app_control_h app_control, struct tm *date, int period, int *alarm_id) TIZEN_DEPRECATED_API |
Sets an alarm to be triggered at a specific time. | |
int | alarm_schedule_once_after_delay (app_control_h app_control, int delay, int *alarm_id) |
Sets an alarm to be triggered after a specific time. | |
int | alarm_schedule_once_at_date (app_control_h app_control, struct tm *date, int *alarm_id) |
Sets an alarm to be triggered at a specific time. | |
int | alarm_schedule_with_recurrence_week_flag (app_control_h app_control, struct tm *date, int week_flag, int *alarm_id) |
Sets an alarm to be triggered periodically, starting at a specific time. | |
int | alarm_get_scheduled_recurrence_week_flag (int alarm_id, int *week_flag) |
Gets the recurrence days of the week. | |
int | alarm_cancel (int alarm_id) |
Cancels the alarm with the specific alarm ID. | |
int | alarm_cancel_all (void) |
Cancels all scheduled alarms that are registered by the application that calls this API. | |
int | alarm_foreach_registered_alarm (alarm_registered_alarm_cb callback, void *user_data) |
Retrieves the IDs of all registered alarms by invoking a callback once for each scheduled alarm. | |
int | alarm_get_scheduled_date (int alarm_id, struct tm *date) |
Gets the scheduled time from the given alarm ID in C standard time struct. | |
int | alarm_get_scheduled_period (int alarm_id, int *period) |
Gets the period of time between the recurrent alarms. | |
int | alarm_get_current_time (struct tm *date) |
Gets the current system time using C standard time struct. | |
int | alarm_get_app_control (int alarm_id, app_control_h *app_control) |
Gets the app_control to be invoked when the alarm is triggered. | |
int | alarm_set_global (int alarm_id, bool global) |
Sets global flag in the alarm. | |
int | alarm_get_global (int alarm_id, bool *global) |
Gets whether the alarm will launch global application or not. | |
int | alarm_schedule_noti_once_at_date (notification_h noti, struct tm *date, int *alarm_id) |
Sets a notification alarm to be triggered at a specific time. | |
int | alarm_schedule_noti_after_delay (notification_h noti, int delay, int period, int *alarm_id) |
Sets a notification alarm to be triggered after a specific delay. | |
int | alarm_schedule_noti_once_after_delay (notification_h noti, int delay, int *alarm_id) |
Sets a notification alarm to be triggered after a specific delay. | |
int | alarm_schedule_noti_with_recurrence_week_flag (notification_h noti, struct tm *date, int week_flag, int *alarm_id) |
Sets a notification to be triggered periodically, starting at a specific time. | |
int | alarm_get_notification (int alarm_id, notification_h *noti) |
Gets the notification to be posted when an alarm is triggered. | |
int | alarm_update_delay (int alarm_id, int delay) |
Updates the delay of the registered alarm. | |
int | alarm_update_date (int alarm_id, struct tm *date) |
Updates the date of the registered alarm. | |
int | alarm_update_period (int alarm_id, int period) |
Updates the period of the registered alarm. | |
int | alarm_update_week_flag (int alarm_id, int week_flag) |
Updates the week recurrence flag of the registered alarm. | |
Typedefs | |
typedef bool(* | alarm_registered_alarm_cb )(int alarm_id, void *user_data) |
Called once for each scheduled alarm to get the alarm ID. | |
Defines | |
#define | APP_CONTROL_DATA_ALARM_ID "http://tizen.org/appcontrol/data/alarm_id" |
Definition to app_control extra data : the ID of the alarm registered. |
Define Documentation
#define APP_CONTROL_DATA_ALARM_ID "http://tizen.org/appcontrol/data/alarm_id" |
Definition to app_control extra data : the ID of the alarm registered.
- Since :
- 2.3.1
Typedef Documentation
typedef bool(* alarm_registered_alarm_cb)(int alarm_id, void *user_data) |
Called once for each scheduled alarm to get the alarm ID.
- Since :
- 2.3.1
- Parameters:
-
[in] alarm_id The alarm ID returned when the alarm is scheduled [in] user_data The user data passed from the foreach function
- Returns:
true
to continue with the next iteration of the loop, otherwisefalse
to break out of the loop
- Precondition:
- alarm_foreach_registered_alarm() will invoke this callback to get all the registered alarm IDs.
- See also:
- alarm_foreach_registered_alarm()
Enumeration Type Documentation
enum alarm_error_e |
Enumeration for Alarm Error.
- Since :
- 2.3.1
- Enumerator:
enum alarm_week_flag_e |
Enumeration for Alarm Week Flag, the days of the week.
- Since :
- 2.3.1
Function Documentation
int alarm_cancel | ( | int | alarm_id | ) |
Cancels the alarm with the specific alarm ID.
- Since :
- 2.3.1
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.set
- Parameters:
-
[in] alarm_id The alarm ID that is cancelled
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server ALARM_ERROR_PERMISSION_DENIED Permission denied
int alarm_cancel_all | ( | void | ) |
Cancels all scheduled alarms that are registered by the application that calls this API.
- Since :
- 2.3.1
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.set
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server ALARM_ERROR_PERMISSION_DENIED Permission denied
int alarm_foreach_registered_alarm | ( | alarm_registered_alarm_cb | callback, |
void * | user_data | ||
) |
Retrieves the IDs of all registered alarms by invoking a callback once for each scheduled alarm.
- Since :
- 2.3.1
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.get
- Parameters:
-
[in] callback The callback function to invoke [in] user_data The user data to be passed to the callback function
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server ALARM_ERROR_PERMISSION_DENIED Permission denied
- Postcondition:
- This function invokes alarm_registered_alarm_cb() repeatedly for each registered alarm.
- See also:
- alarm_registered_alarm_cb()
int alarm_get_app_control | ( | int | alarm_id, |
app_control_h * | app_control | ||
) |
Gets the app_control to be invoked when the alarm is triggered.
- Since :
- 2.3.1
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.get
- Remarks:
- The app_control must be released using app_control_destroy().
- Parameters:
-
[in] alarm_id The alarm ID uniquely identifies an alarm [out] app_control The app_control handle to launch when the alarm is triggered
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_OUT_OF_MEMORY Out of memory ALARM_ERROR_PERMISSION_DENIED Permission denied
int alarm_get_current_time | ( | struct tm * | date | ) |
Gets the current system time using C standard time struct.
- Since :
- 2.3.1
- Parameters:
-
[out] date The current system time
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_PERMISSION_DENIED Permission denied
int alarm_get_global | ( | int | alarm_id, |
bool * | global | ||
) |
Gets whether the alarm will launch global application or not.
- Since :
- 3.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.get
- Parameters:
-
[in] alarm_id The alarm ID uniquely identifies an alarm [out] global Whether the alarm will launch global application or not
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_PERMISSION_DENIED Permission denied
- See also:
- alarm_set_global()
int alarm_get_notification | ( | int | alarm_id, |
notification_h * | noti | ||
) |
Gets the notification to be posted when an alarm is triggered.
- Since :
- 3.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.get
- Remarks:
- noti must be released using notification_free().
- Parameters:
-
[in] alarm_id The ID which uniquely identifies a scheduled alarm [out] noti The notification to be posted when the alarm is triggered
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_OUT_OF_MEMORY Out of memory ALARM_ERROR_PERMISSION_DENIED Permission denied
int alarm_get_scheduled_date | ( | int | alarm_id, |
struct tm * | date | ||
) |
Gets the scheduled time from the given alarm ID in C standard time struct.
- Since :
- 2.3.1
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.get
- Remarks:
- date is not needed by the function after the call.
- Parameters:
-
[in] alarm_id The alarm ID returned when the alarm is scheduled [out] date The time value of the next alarm event
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server ALARM_ERROR_PERMISSION_DENIED Permission denied
int alarm_get_scheduled_period | ( | int | alarm_id, |
int * | period | ||
) |
Gets the period of time between the recurrent alarms.
- Since :
- 2.3.1
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.get
- Remarks:
- If the given alarm_id is not obtained by using the alarm_schedule_once_at_date() or alarm_schedule_after_delay() function, an error (error code ALARM_ERROR_INVALID_PARAMETER) will occur.
- Parameters:
-
[in] alarm_id The alarm ID returned when the alarm is scheduled [out] period The period of time between recurrent alarms in seconds
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server ALARM_ERROR_PERMISSION_DENIED Permission denied
int alarm_get_scheduled_recurrence_week_flag | ( | int | alarm_id, |
int * | week_flag | ||
) |
Gets the recurrence days of the week.
- Since :
- 2.3.1
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.get
- Remarks:
- If the given alarm_id is not obtained by using the alarm_schedule_with_recurrence_week_flag() function, an error (error code ALARM_ERROR_INVALID_PARAMETER) will occur because this alarm is scheduled with no recurrence. If the operation of app_control is not specified, APP_CONTROL_OPERATION_DEFAULT is used for the launch request. If the operation of app_control is APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
- Parameters:
-
[in] alarm_id The alarm ID returned when the alarm is scheduled [out] week_flag The recurrence days of the week, week_flag may be a combination of days, like ALARM_WEEK_FLAG_TUESDAY | ALARM_WEEK_FLAG_FRIDAY
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_PERMISSION_DENIED Permission denied
int alarm_schedule_after_delay | ( | app_control_h | app_control, |
int | delay, | ||
int | period, | ||
int * | alarm_id | ||
) |
Sets an alarm to be triggered after a specific time.
The alarm will first go off delay seconds later and then will go off every certain amount of time defined using period seconds. To cancel the alarm, call alarm_cancel() with alarm_id.
- Since :
- 2.3.1
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.set
- Privilege:
- http://tizen.org/privilege/appmanager.launch
- Remarks:
- If the application is uninstalled after setting an alarm, the alarm is cancelled automatically. If the operation of app_control is not specified, APP_CONTROL_OPERATION_DEFAULT is used for the launch request. If the operation of app_control is APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application. Since 3.0, this api does not support exact period and delay for minimizing the wakeups of the device. The system can adjust when the alarm expires. If you want to trigger an alarm exactly, see
- See also:
- alarm_schedule_once_after_delay() Since 3.0If app_control is specified with service-application, the application is only allowed to run on which has Background Category. Since 3.0If the appid of app_control is not specified, this api is not allowed. In other words, the explicit app_control is only allowed. Since 4.0, http://tizen.org/privilege/appmanager.launch privilege is additionally required.
- Parameters:
-
[in] app_control The destination app_control to perform a specific task when the alarm is triggered [in] delay The amount of time before the first execution (in seconds). Since 3.0, Although this is inexact, the alarm will not fire before this time [in] period The amount of time between subsequent alarms (in seconds). Since 3.0, This value does not guarantee the accuracy. The actual interval is calculated by the OS. The minimum value is 600sec [out] alarm_id The alarm ID that uniquely identifies an alarm
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_INVALID_TIME Triggered time is invalid ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server ALARM_ERROR_PERMISSION_DENIED Permission denied ALARM_ERROR_NOT_PERMITTED_APP app_control is not permitted
int alarm_schedule_at_date | ( | app_control_h | app_control, |
struct tm * | date, | ||
int | period, | ||
int * | alarm_id | ||
) |
Sets an alarm to be triggered at a specific time.
- Deprecated:
- Deprecated since 3.0. [Use alarm_schedule_once_at_date() instead]
The date describes the time of the first occurrence. If period is bigger than 0
, the alarm will be scheduled after the period time. If period is set to 0
, the alarm will go off just once without repetition. To cancel the alarm, call alarm_cancel() with alarm_id.
- Since :
- 2.3.1
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.set
- Remarks:
- If application is uninstalled after setting an alarm, the alarm is cancelled automatically. If the operation of app_control is not specified, APP_CONTROL_OPERATION_DEFAULT is used for the launch request. If the operation of app_control is APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application.
- Parameters:
-
[in] app_control The destination app_control to perform specific work when the alarm is triggered [in] date The first active alarm time [in] period The amount of time between subsequent alarms(in second) [out] alarm_id The alarm ID that uniquely identifies an alarm
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_INVALID_DATE Triggered date is invalid ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server ALARM_ERROR_PERMISSION_DENIED Permission denied
int alarm_schedule_noti_after_delay | ( | notification_h | noti, |
int | delay, | ||
int | period, | ||
int * | alarm_id | ||
) |
Sets a notification alarm to be triggered after a specific delay.
The alarm will first go off after delay seconds. The alarm will then go off every period seconds until canceled. To cancel the alarm, call alarm_cancel() with alarm_id.
- Since :
- 3.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.set
- Privilege:
- http://tizen.org/privilege/notification
- Remarks:
- If the application is uninstalled after setting an alarm, the alarm is cancelled automatically. This function is a minimally intrusive way to trigger alarms when precision is not important. The system will adjust the delay and period requests to suit internal needs; the requests will be treated as minimum values. Note that period cannot be less than 600 seconds, if a smaller request is supplied it will be silently adjusted to a request of 600. When the alarm goes off, Alarm Manager will turn on LCD to prohibit background jobs.
- Parameters:
-
[in] noti The notification to be posted when the alarm is triggered [in] delay The amount of time before the first execution (in seconds). [in] period The amount of time between subsequent alarms (in seconds). [out] alarm_id The ID which uniquely identifies the scheduled alarm
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_INVALID_TIME Triggered time is invalid ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server ALARM_ERROR_PERMISSION_DENIED Permission denied
int alarm_schedule_noti_once_after_delay | ( | notification_h | noti, |
int | delay, | ||
int * | alarm_id | ||
) |
Sets a notification alarm to be triggered after a specific delay.
The alarm will go off delay seconds later. To cancel the alarm, call alarm_cancel() with alarm_id.
- Since :
- 3.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.set
- Privilege:
- http://tizen.org/privilege/notification
- Remarks:
- If the application is uninstalled after setting an alarm, the alarm is cancelled automatically. When the alarm goes off, Alarm Manager will turn on LCD to prohibit background jobs.
- Parameters:
-
[in] noti The notification to be posted when the alarm is triggered [in] delay The amount of time before the execution (in seconds) [out] alarm_id The ID which uniquely identifies the scheduled alarm
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_INVALID_TIME Triggered time is invalid ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server ALARM_ERROR_PERMISSION_DENIED Permission denied
int alarm_schedule_noti_once_at_date | ( | notification_h | noti, |
struct tm * | date, | ||
int * | alarm_id | ||
) |
Sets a notification alarm to be triggered at a specific time.
The date describes the time of the alarm occurrence. To cancel the alarm, call alarm_cancel() with alarm_id.
- Since :
- 3.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.set
- Privilege:
- http://tizen.org/privilege/notification
- Remarks:
- If application is uninstalled after setting an alarm, the alarm is cancelled automatically. When the alarm goes off, Alarm Manager will turn on LCD to prohibit background jobs.
- Parameters:
-
[in] noti The notification to be posted when the alarm is triggered [in] date The active alarm time [out] alarm_id The ID which uniquely identifies the scheduled alarm
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_INVALID_DATE Triggered date is invalid ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server ALARM_ERROR_PERMISSION_DENIED Permission denied
int alarm_schedule_noti_with_recurrence_week_flag | ( | notification_h | noti, |
struct tm * | date, | ||
int | week_flag, | ||
int * | alarm_id | ||
) |
Sets a notification to be triggered periodically, starting at a specific time.
The date describes the time of the first occurrence. week_flag describes the day(s) of the week when the notification recurs. If week_flag is ALARM_WEEK_FLAG_TUESDAY, the alarm will repeat every Tuesday at a specific time. If week_flag is less than or equal to zero, the alarm is not repeated. To cancel the alarm, call alarm_cancel() with alarm_id.
- Since :
- 3.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.set
- Privilege:
- http://tizen.org/privilege/notification
- Remarks:
- If the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
- Parameters:
-
[in] noti The notification to be posted when the alarm is triggered [in] date The first active alarm time [in] week_flag The day of the week the notification recurs. week_flag may be a combination of days, like ALARM_WEEK_FLAG_TUESDAY | ALARM_WEEK_FLAG_FRIDAY [out] alarm_id The ID which uniquely identifies the scheduled alarm
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_INVALID_DATE Triggered date is invalid ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server ALARM_ERROR_PERMISSION_DENIED Permission denied
int alarm_schedule_once_after_delay | ( | app_control_h | app_control, |
int | delay, | ||
int * | alarm_id | ||
) |
Sets an alarm to be triggered after a specific time.
The alarm will go off delay seconds later. To cancel the alarm, call alarm_cancel() with alarm_id.
- Since :
- 3.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.set
- Privilege:
- http://tizen.org/privilege/appmanager.launch
- Remarks:
- If the application is uninstalled after setting an alarm, the alarm is cancelled automatically. If the operation of app_control is not specified, APP_CONTROL_OPERATION_DEFAULT is used for the launch request. If the operation of app_control is APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application. If the appid of app_control is not specified, this api is not allowed. In other words, the explicit app_control is only allowed. The app_control only supports UI application with this api. If app_control is not UI application, ALARM_ERROR_NOT_PERMITTED_APP returned. When the alarm is expired, Alarm Manager will turn on LCD to prohibit background jobs. Since 4.0, http://tizen.org/privilege/appmanager.launch privilege is additionally required.
- Parameters:
-
[in] app_control The destination app_control to perform a specific task when the alarm is triggered [in] delay The amount of time before the execution (in seconds) [out] alarm_id The alarm ID that uniquely identifies an alarm
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_INVALID_TIME Triggered time is invalid ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server ALARM_ERROR_PERMISSION_DENIED Permission denied ALARM_ERROR_NOT_PERMITTED_APP app_control is not permitted. app_control for UI application is only permitted.
int alarm_schedule_once_at_date | ( | app_control_h | app_control, |
struct tm * | date, | ||
int * | alarm_id | ||
) |
Sets an alarm to be triggered at a specific time.
The date describes the time of the first occurrence. To cancel the alarm, call alarm_cancel() with alarm_id.
- Since :
- 3.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.set
- Privilege:
- http://tizen.org/privilege/appmanager.launch
- Remarks:
- If application is uninstalled after setting an alarm, the alarm is cancelled automatically. If the operation of app_control is not specified, APP_CONTROL_OPERATION_DEFAULT is used for the launch request. If the operation of app_control is APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application. If the appid of app_control is not specified, this api is not allowed. In other words, the explicit app_control is only allowed. The app_control only supports UI application with this api. If app_control is not UI application, ALARM_ERROR_NOT_PERMITTED_APP returned. When the alarm is expired, Alarm Manager will turn on LCD to prohibit background jobs. Since 4.0, http://tizen.org/privilege/appmanager.launch privilege is additionally required.
- Parameters:
-
[in] app_control The destination app_control to perform specific work when the alarm is triggered [in] date The first active alarm time [out] alarm_id The alarm ID that uniquely identifies an alarm
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_INVALID_DATE Triggered date is invalid ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server ALARM_ERROR_PERMISSION_DENIED Permission denied ALARM_ERROR_NOT_PERMITTED_APP app_control is not permitted. app_control for UI application is only permitted.
int alarm_schedule_with_recurrence_week_flag | ( | app_control_h | app_control, |
struct tm * | date, | ||
int | week_flag, | ||
int * | alarm_id | ||
) |
Sets an alarm to be triggered periodically, starting at a specific time.
The date describes the time of the first occurrence. week_flag is the repeat value of the days of the week. If week_flag is ALARM_WEEK_FLAG_TUESDAY, the alarm will repeat every Tuesday at a specific time. To cancel the alarm, call alarm_cancel() with alarm_id.
- Since :
- 2.3.1
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.set
- Privilege:
- http://tizen.org/privilege/appmanager.launch
- Remarks:
- If the application is uninstalled after setting an alarm, the alarm is cancelled automatically. If the operation of app_control is not specified, APP_CONTROL_OPERATION_DEFAULT is used for the launch request. If the operation of app_control is APP_CONTROL_OPERATION_DEFAULT, the package information is mandatory to explicitly launch the application. Since 3.0, The app_control only supports UI application with this api. If app_control is not UI application, ALARM_ERROR_NOT_PERMITTED_APP returned. When the alarm is expired, Alarm Manager will turn on LCD to prohibit background jobs. Since 3.0, If the appid of app_control is not specified, this api is not allowed. In other words, the explicit app_control is only allowed. Since 4.0, http://tizen.org/privilege/appmanager.launch privilege is additionally required.
- Parameters:
-
[in] app_control The destination app_control to perform specific work when the alarm is triggered [in] date The first active alarm time [in] week_flag The day of the week, week_flag may be a combination of days, like ALARM_WEEK_FLAG_TUESDAY | ALARM_WEEK_FLAG_FRIDAY [out] alarm_id The alarm ID that uniquely identifies an alarm
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_INVALID_DATE Triggered date is invalid ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server ALARM_ERROR_PERMISSION_DENIED Permission denied ALARM_ERROR_NOT_PERMITTED_APP app_control is not permitted. app_control for UI application is only permitted.
int alarm_set_global | ( | int | alarm_id, |
bool | global | ||
) |
Sets global flag in the alarm.
Sets global flag to set/unset alarm globally.
- Since :
- 3.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.set
- Remarks:
- The alarm_id must be id of alarm which will launch global application. The function returns an error (error code ALARM_ERROR_NOT_PERMITTED_APP) if it is not. Note that the application which is launched by global alarm runs in the user session that is logged in currently. It doesn't run in the session for the user who registers the global alarm. 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. Therefore, We recommend to contain all the data for the alarm to the app_control handle for the global alarm. Then, the launched application would be able to use the data to show proper alarm UX to the user.
- Parameters:
-
[in] alarm_id The alarm ID uniquely identifies an alarm [in] global The global flag to set/unset alarm globally
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_NOT_PERMITTED_APP alarm_id is not permitted ALARM_ERROR_PERMISSION_DENIED Permission denied
int alarm_update_date | ( | int | alarm_id, |
struct tm * | date | ||
) |
Updates the date of the registered alarm.
The date describes the date on which the alarm is set off for the first time. This function can be called for any alarm. If the date was set before, it will be overwritten. If it was not, it will be set.
- Since :
- 4.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.set
- Remarks:
- This function can be called only for alarms whose app control launches an UI application. If this condition is not met, ALARM_ERROR_NOT_PERMITTED_APP is returned.
- Parameters:
-
[in] alarm_id The ID which uniquely identifies the scheduled alarm [in] date The time value of the next alarm event
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_INVALID_TIME Triggered time is invalid ALARM_ERROR_INVALID_DATE Triggered time is invalid ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server ALARM_ERROR_OUT_OF_MEMORY Out of memory ALARM_ERROR_PERMISSION_DENIED Permission denied ALARM_ERROR_NOT_PERMITTED_APP App control does not launch an UI application
int alarm_update_delay | ( | int | alarm_id, |
int | delay | ||
) |
Updates the delay of the registered alarm.
The delay is the time (in seconds) before the alarm's first setting off. The delay is an exact value, see alarm_schedule_once_after_delay() for details. This function can be called for any alarm. If the delay was set before, it will be overwritten. If it was not, it will be set.
- Since :
- 4.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.set
- Remarks:
- This function can be called only for alarms whose app control launches an UI application. If this condition is not met, ALARM_ERROR_NOT_PERMITTED_APP is returned.
- Parameters:
-
[in] alarm_id The ID which uniquely identifies the scheduled alarm [in] delay The amount of time before the first execution (in seconds).
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server ALARM_ERROR_OUT_OF_MEMORY Out of memory ALARM_ERROR_PERMISSION_DENIED Permission denied ALARM_ERROR_NOT_PERMITTED_APP App control does not launch an UI application
int alarm_update_period | ( | int | alarm_id, |
int | period | ||
) |
Updates the period of the registered alarm.
The alarm will then go off every period seconds until canceled. This function can be called for any alarm. If the week recurrence flag was set before, it will be removed and the period will be set. If the period was set before, it will be overwritten. If it was not, it will be set. If the period argument is 0 and the period was previously set, the period attribute will be cleared and the alarm will be changed to one-time. If the period argument is 0 and the period was not set, or the week recurrence flag was set, the alarm will be unchanged.
- Since :
- 4.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.set
- Parameters:
-
[in] alarm_id The ID which uniquely identifies the scheduled alarm [in] period The amount of time between subsequent alarms (in seconds). Since 3.0, this value does not guarantee the accuracy. The actual interval is calculated by the OS. The minimum value is 600sec.
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server ALARM_ERROR_OUT_OF_MEMORY Out of memory ALARM_ERROR_PERMISSION_DENIED Permission denied
int alarm_update_week_flag | ( | int | alarm_id, |
int | week_flag | ||
) |
Updates the week recurrence flag of the registered alarm.
week_flag is the repeat value of the days of the week. For example, if week_flag is ALARM_WEEK_FLAG_TUESDAY, the alarm will repeat every Tuesday at a specific time. This function can be called for any alarm. If the period was set before, it will be removed and the week recurrence flag will be set. If the week recurrence flag was set before, it will be overwritten. If it was not, it will be set. If the week_flag argument is 0 and the flag was previously set, the flag attribute will be cleared and the alarm will be changed to one-time. If the week_flag argument is 0 and the flag was not set, or the period was set, the alarm will be unchanged.
- Since :
- 4.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/alarm.set
- Remarks:
- This function can be called only for alarms whose app control launches an UI application. If this condition is not met, ALARM_ERROR_NOT_PERMITTED_APP is returned.
- Parameters:
-
[in] alarm_id The ID which uniquely identifies the scheduled alarm [in] week_flag The day of the week, week_flag may be a combination of days, like ALARM_WEEK_FLAG_TUESDAY | ALARM_WEEK_FLAG_FRIDAY
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
ALARM_ERROR_NONE Successful ALARM_ERROR_INVALID_PARAMETER Invalid parameter ALARM_ERROR_CONNECTION_FAIL Failed to connect to an alarm server ALARM_ERROR_OUT_OF_MEMORY Out of memory ALARM_ERROR_PERMISSION_DENIED Permission denied ALARM_ERROR_NOT_PERMITTED_APP App control does not launch an UI application