Tizen Native API

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 cancelled automatically.
When the alarm is expired, Alarm Manager will turn on LCD to prohibit background jobs. Please make sure background jobs using alarm APIs are not allowed.

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)


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)
 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 the alarm is triggered.

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_idThe alarm ID returned when the alarm is scheduled
[in]user_dataThe user data passed from the foreach function
Returns:
true to continue with the next iteration of the loop, otherwise false 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

Enumeration for Alarm Error.

Since :
2.3.1
Enumerator:
ALARM_ERROR_NONE 

Successful

ALARM_ERROR_INVALID_PARAMETER 

Invalid parameter

ALARM_ERROR_INVALID_TIME 

Invalid time

ALARM_ERROR_INVALID_DATE 

Invalid date

ALARM_ERROR_CONNECTION_FAIL 

The alarm service connection failed

ALARM_ERROR_OUT_OF_MEMORY 

Out of memory

ALARM_ERROR_PERMISSION_DENIED 

Permission denied

Enumeration for Alarm Week Flag, the days of the week.

Since :
2.3.1
Enumerator:
ALARM_WEEK_FLAG_SUNDAY 

Sunday

ALARM_WEEK_FLAG_MONDAY 

Monday

ALARM_WEEK_FLAG_TUESDAY 

Tuesday

ALARM_WEEK_FLAG_WEDNESDAY 

Wednesday

ALARM_WEEK_FLAG_THURSDAY 

Thursday

ALARM_WEEK_FLAG_FRIDAY 

Friday

ALARM_WEEK_FLAG_SATURDAY 

Saturday


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_idThe alarm ID that is cancelled
Returns:
0 on success, otherwise a negative error value
Return values:
ALARM_ERROR_NONESuccessful
ALARM_ERROR_CONNECTION_FAILFailed to connect to an alarm server
ALARM_ERROR_PERMISSION_DENIEDPermission denied
See also:
alarm_schedule_at_date()
alarm_schedule_after_delay()
alarm_schedule_with_recurrence_week_flag()
alarm_cancel_all()
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_NONESuccessful
ALARM_ERROR_CONNECTION_FAILFailed to connect to an alarm server
ALARM_ERROR_PERMISSION_DENIEDPermission denied
See also:
alarm_schedule_at_date()
alarm_schedule_after_delay()
alarm_schedule_with_recurrence_week_flag()
alarm_cancel()
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]callbackThe callback function to invoke
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
ALARM_ERROR_NONESuccessful
ALARM_ERROR_INVALID_PARAMETERInvalid parameter
ALARM_ERROR_CONNECTION_FAILFailed to connect to an alarm server
ALARM_ERROR_PERMISSION_DENIEDPermission 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 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_idThe alarm ID uniquely identifies an alarm
[out]app_controlThe app_control handle to launch when the alarm is triggered
Returns:
0 on success, otherwise a negative error value
Return values:
ALARM_ERROR_NONESuccessful
ALARM_ERROR_INVALID_PARAMETERInvalid parameter
ALARM_ERROR_OUT_OF_MEMORYOut of memory
ALARM_ERROR_PERMISSION_DENIEDPermission denied
See also:
alarm_schedule_at_date()
alarm_schedule_after_delay()
alarm_schedule_with_recurrence_week_flag()
int alarm_get_current_time ( struct tm *  date)

Gets the current system time using C standard time struct.

Since :
2.3.1
Parameters:
[out]dateThe current system time
Returns:
0 on success, otherwise a negative error value
Return values:
ALARM_ERROR_NONESuccessful
ALARM_ERROR_INVALID_PARAMETERInvalid parameter
ALARM_ERROR_PERMISSION_DENIEDPermission 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
Parameters:
[in]alarm_idThe alarm ID returned when the alarm is scheduled
[out]dateThe time value of the next alarm event
Returns:
0 on success, otherwise a negative error value
Return values:
ALARM_ERROR_NONESuccessful
ALARM_ERROR_INVALID_PARAMETERInvalid parameter
ALARM_ERROR_CONNECTION_FAILFailed to connect to an alarm server
ALARM_ERROR_PERMISSION_DENIEDPermission denied
See also:
alarm_schedule_at_date()
alarm_schedule_after_delay()
alarm_schedule_with_recurrence_week_flag()
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_get_scheduled_date() or alarm_schedule_after_delay() function, an error (error code ALARM_ERROR_INVALID_PARAMETER) will occur.
Parameters:
[in]alarm_idThe alarm ID returned when the alarm is scheduled
[out]periodThe period of time between recurrent alarms in seconds
Returns:
0 on success, otherwise a negative error value
Return values:
ALARM_ERROR_NONESuccessful
ALARM_ERROR_INVALID_PARAMETERInvalid parameter
ALARM_ERROR_CONNECTION_FAILFailed to connect to an alarm server
ALARM_ERROR_PERMISSION_DENIEDPermission denied
See also:
alarm_schedule_at_date()
alarm_schedule_after_delay()
alarm_schedule_with_recurrence_week_flag()
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_idThe alarm ID returned when the alarm is scheduled
[out]week_flagThe 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_NONESuccessful
ALARM_ERROR_INVALID_PARAMETERInvalid parameter
ALARM_ERROR_PERMISSION_DENIEDPermission denied
See also:
alarm_schedule_with_recurrence_week_flag()
alarm_week_flag_e
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. 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 the application is uninstalled after setting an alarm, the alarm is cancelled automatically.
Parameters:
[in]app_controlThe destination app_control to perform a specific task when the alarm is triggered
[in]delayThe amount of time before the first execution (in seconds)
[in]periodThe amount of time between subsequent alarms (in seconds)
[out]alarm_idThe alarm ID that uniquely identifies an alarm
Returns:
0 on success, otherwise a negative error value
Return values:
ALARM_ERROR_NONESuccessful
ALARM_ERROR_INVALID_PARAMETERInvalid parameter
ALARM_ERROR_INVALID_TIMETriggered time is invalid
ALARM_ERROR_CONNECTION_FAILFailed to connect to an alarm server
ALARM_ERROR_PERMISSION_DENIEDPermission denied
See also:
alarm_cancel()
alarm_cancel_all()
alarm_get_scheduled_date()
alarm_get_scheduled_period()
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.

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_controlThe destination app_control to perform specific work when the alarm is triggered
[in]dateThe first active alarm time
[in]periodThe amount of time between subsequent alarms(in second)
[out]alarm_idThe alarm ID that uniquely identifies an alarm
Returns:
0 on success, otherwise a negative error value
Return values:
ALARM_ERROR_NONESuccessful
ALARM_ERROR_INVALID_PARAMETERInvalid parameter
ALARM_ERROR_INVALID_DATETriggered date is invalid
ALARM_ERROR_CONNECTION_FAILFailed to connect to an alarm server
ALARM_ERROR_PERMISSION_DENIEDPermission denied
See also:
alarm_cancel()
alarm_cancel_all()
alarm_get_scheduled_date()
alarm_get_scheduled_period()
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
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.
Parameters:
[in]app_controlThe destination app_control to perform specific work when the alarm is triggered
[in]dateThe first active alarm time
[in]week_flagThe day of the week, week_flag may be a combination of days, like ALARM_WEEK_FLAG_TUESDAY | ALARM_WEEK_FLAG_FRIDAY
[out]alarm_idThe alarm ID that uniquely identifies an alarm
Returns:
0 on success, otherwise a negative error value
Return values:
ALARM_ERROR_NONESuccessful
ALARM_ERROR_INVALID_PARAMETERInvalid parameter
ALARM_ERROR_INVALID_DATETriggered date is invalid
ALARM_ERROR_CONNECTION_FAILFailed to connect to an alarm server
ALARM_ERROR_PERMISSION_DENIEDPermission denied
See also:
alarm_cancel()
alarm_cancel_all()
alarm_get_scheduled_recurrence_week_flag()
alarm_get_scheduled_date()
alarm_week_flag_e