Editing Documentation/Maemo 5 Developer Guide/Using Generic Platform Components/Alarm Framework

Warning: You are not logged in. Your IP address will be recorded in this page's edit history.
The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
Latest revision Your text
Line 1: Line 1:
-
The Maemo alarm framework provides an easy way to manage timed events in the device. It is powerful, and not restricted only to wake up alarms.
+
=Alarm Framework=
-
 
+
The maemo alarm framework provides an easy way to manage timed events in the device. It is powerful, and not restricted only to wake up alarms. The framework provides many other features, including:
-
== Alarm framework features ==
+
-
 
+
-
The framework provides many other features, including:
+
* Setting multiple alarm events
* Setting multiple alarm events
Line 16: Line 13:
* Choosing to postpone the alarm if it is missed
* Choosing to postpone the alarm if it is missed
* Executing a given file (e.g. a program or a script)
* Executing a given file (e.g. a program or a script)
-
* Sending a message to a [[Documentation/Maemo 5 Developer Guide/DBus/DBus Basics|D-Bus message bus]]
+
* Sending a message to a D-Bus message bus
* Querying for existing alarm events in a given period of time
* Querying for existing alarm events in a given period of time
* Deleting an existing alarm event
* Deleting an existing alarm event
* Configuring the snooze time for the event
* Configuring the snooze time for the event
* Configuring the default snooze time for all alarm events
* Configuring the default snooze time for all alarm events
 +
This topic shows how to use the alarm interface, describes its main functions and gives examples of use cases.
This topic shows how to use the alarm interface, describes its main functions and gives examples of use cases.
Line 30: Line 28:
A single event may be set to repeat itself over and over again, at regular intervals or based on time and date. The alarmd daemon will remember these events over system shutdowns too.
A single event may be set to repeat itself over and over again, at regular intervals or based on time and date. The alarmd daemon will remember these events over system shutdowns too.
-
The alarmd daemon can also be asked to start the system up for an event, even when powered off. These events may also be set to run in a hidden power-on mode, where the display stays off, but the device is on. The alarm daemon also supports the use of <code>osso-systemui-alarm</code> to show an alarm dialog for the event, which can be followed by a power up device confirmation dialog, if the device is in the hidden power-up mode.
+
The alarmd daemon can also be asked to start the system up for an event, even when powered off. These events may also be set to run in a hidden power-on mode, where the display stays off, but the device is on. The alarm daemon also supports the use of osso-systemui-alarm to show an alarm dialog for the event, which can be followed by a power up device confirmation dialog, if the device is in the hidden power-up mode.
Communication with the alarmd daemon is performed through D-Bus. It listens to both system and session buses. The easiest way is to use the C client API library, which offers straightforward API to modify the queue.
Communication with the alarmd daemon is performed through D-Bus. It listens to both system and session buses. The easiest way is to use the C client API library, which offers straightforward API to modify the queue.
-
The alarm queue used by the alarmd daemon is stored in file <code>alarm_queue.ini</code>, located in <code>/var/cache/alarmd</code> directory.
+
The alarm queue used by the alarmd daemon is stored in file alarm_queue.ini, located in /var/cache/alarmd directory.
-
== Alarm Events ==
 
-
Alarm events and the functions to manage them are defined in the <code>libalarm.h</code> header file located in <code>/usr/include/alarmd</code>. It is a part of the [http://maemo.org/packages/view/libalarm-dev/ libalarm-dev] Debian package.
+
== Alarm Events==
 +
Alarm events and the functions to manage them are defined in libalarm.h header file located in /usr/include/alarmd. It is a part of the libalarm-dev debian package.
Alarm event structures contains basic information about the alarm such as:
Alarm event structures contains basic information about the alarm such as:
Line 51: Line 49:
Once added to the queue, each alarm event is identified by a unique key, also known as a "cookie". The cookies can be used for deleting events, or retrieving information about a specific event.
Once added to the queue, each alarm event is identified by a unique key, also known as a "cookie". The cookies can be used for deleting events, or retrieving information about a specific event.
 +
==Managing Alarm Events==
==Managing Alarm Events==
===Adding Alarm Event to Queue===
===Adding Alarm Event to Queue===
 +
To add a new alarm event in to the queue, you need to set up a client side alarm event structure and send it to alarmd using alarmd_event_add() function.
-
To add a new alarm event in to the queue, you need to set up a client side alarm event structure and send it to alarmd using the <code>alarmd_event_add()</code> function, which will perform sanity checking for the alarm event before sending it over to alarmd. If inconsistencies are noted, warnings and errors will be written to stderr. Any errors will make the alarm rejected before it is sent over to alarmd.
+
The ''alarmd_event_add()'' will perform sanity checking for the alarm event before sending it over to alarmd. If inconsistencies are noted, warnings and errors will be written to stderr. Any errors will make the alarm rejected before it is sent over to alarmd.
All alarms must have an non-empty application identifier string and at least one alarm action item.
All alarms must have an non-empty application identifier string and at least one alarm action item.
-
For recurring alarms there must be either simple recurrency period or the <code>alarm_recur_t</code> items must be valid.
+
For recurring alarms there must be either simple recurrency period or the ''alarm_recur_t' items must be valid.
For non-recurring alarms the triggering time must evaluate to a time in the future.
For non-recurring alarms the triggering time must evaluate to a time in the future.
-
Addional checks include things like having all necessary D-Bus parameters filled in if D-Bus action is requested.
+
Addional checks include things like having all necessary dbus parameters filled in if dbus action is requested.
'''Example: Adding simple two button dialog 10 seconds from now'''
'''Example: Adding simple two button dialog 10 seconds from now'''
-
<source lang="c">
 
-
#include <alarmd/libalarm.h>
 
-
#define APPID "example-apps"
 
-
static cookie_t add_two_button_alarm(void)
+
#include <alarmd/libalarm.h>
-
{
+
#define APPID "example-apps"
-
  cookie_t cookie = 0;
+
-
  alarm_event_t *eve = 0;
+
static cookie_t add_two_button_alarm(void)
-
  alarm_action_t *act = 0;
+
{
 +
cookie_t cookie = 0;
 +
alarm_event_t *eve = 0;
 +
alarm_action_t *act = 0;
-
  /* Create alarm event structure, set application
+
/* Create alarm event structure, set application
-
  * identifier and dialog message */
+
  * identifier and dialog message */
-
  eve = alarm_event_create();
+
eve = alarm_event_create();
-
  alarm_event_set_alarm_appid(eve, APPID);
+
alarm_event_set_alarm_appid(eve, APPID);
-
  alarm_event_set_message(eve, "Example Message");
+
alarm_event_set_message(eve, "Example Message");
-
  /* Use absolute time triggering, show dialog
+
/* Use absolute time triggering, show dialog
-
  * ten seconds from now */
+
* ten seconds from now */
-
  eve->alarm_time = time(0) + 10;
+
eve->alarm_time = time(0) + 10;
-
 
+
-
  /* Add stop button action */
+
/* Add stop button action */
-
  act = alarm_event_add_actions(eve, 1);
+
act = alarm_event_add_actions(eve, 1);
-
  alarm_action_set_label(act, "Stop");
+
alarm_action_set_label(act, "Stop");
-
  act->flags |= ALARM_ACTION_WHEN_RESPONDED;
+
act->flags |= ALARM_ACTION_WHEN_RESPONDED;
-
  act->flags |= ALARM_ACTION_TYPE_NOP;
+
act->flags |= ALARM_ACTION_TYPE_NOP;
-
 
+
-
  /* Add snooze button action */
+
/* Add snooze button action */
-
  act = alarm_event_add_actions(eve, 1);
+
act = alarm_event_add_actions(eve, 1);
-
  alarm_action_set_label(act, "Snooze");
+
alarm_action_set_label(act, "Snooze");
-
  act->flags |= ALARM_ACTION_WHEN_RESPONDED;
+
act->flags |= ALARM_ACTION_WHEN_RESPONDED;
-
  act->flags |= ALARM_ACTION_TYPE_SNOOZE;
+
act->flags |= ALARM_ACTION_TYPE_SNOOZE;
-
 
+
-
  /* Send the alarm to alarmd */
+
/* Send the alarm to alarmd */
-
  cookie = alarmd_event_add(eve);
+
cookie = alarmd_event_add(eve);
-
 
+
-
  /* Free all dynamic memory associated with the
+
/* Free all dynamic memory associated with the
-
  * alarm event */
+
* alarm event */
-
  alarm_event_delete(eve);
+
alarm_event_delete(eve);
-
 
+
-
  return cookie;
+
return cookie;
-
}
+
}
-
</source>
+
-
 
+
-
{{ambox|text=Use of absolute time triggering, i.e., <code>alarm_time</code> field of the alarm event, allows 1-second precision. Alarms that use broken-down time, i.e., the <code>alarm_tm</code> field, trigger alarms at the start of the next full minute from the alarm. The two fields should not be set simultaneously. Alarm_time-set alarms do not take timezone changes into account.}}
+
===Fetching Details of Alarm Event===
===Fetching Details of Alarm Event===
-
 
+
Having set an alarm event, it is not possible to edit its details anymore, but it is possible to fetch the alarm details using the alarmd_event_get() function, passing the event cookie as parameter.
-
Having set an alarm event, it is not possible to edit its details anymore, but it is possible to fetch the alarm details using the <code>alarmd_event_get()</code> function, passing the event cookie as parameter.
+
'''Example: Showing some alarm event details'''
'''Example: Showing some alarm event details'''
-
<source lang="c">
 
-
static void show_alarm_details(cookie_t cookie)
 
-
{
 
-
  alarm_event_t *eve = 0;
 
-
  alarm_action_t *act = 0;
 
-
  time_t tmo = time(0);
 
-
  if( (eve = alarmd_event_get(cookie)) == 0 )
+
static void show_alarm_details(cookie_t cookie)
-
  {
+
{
-
    printf("unable to get details for cookie=%ld\n", (long)cookie);
+
alarm_event_t *eve = 0;
-
    goto cleanup;
+
alarm_action_t *act = 0;
-
  }
+
time_t tmo = time(0);
 +
 +
if( (eve = alarmd_event_get(cookie)) == 0 )
 +
{
 +
printf("unable to get details for cookie=%ld\n", (long)cookie);
 +
goto cleanup;
 +
}
 +
 +
printf("cookie %ld:\n", (long)cookie);
 +
 +
tmo -= eve->trigger;
 +
printf("appid = %s\n", alarm_event_get_alarm_appid(eve));
 +
printf("trigger = T%+ld, %s", (long)tmo, ctime(&eve->trigger));
 +
printf("message = %s\n", alarm_event_get_message(eve));
 +
 +
for( int i = 0; (act = alarm_event_get_action(eve, i)) != 0; ++i )
 +
{
 +
printf("action%d.label = %s\n", i, alarm_action_get_label(act));
 +
}
 +
 +
cleanup:
 +
 +
/* Free all dynamic memory associated with the
 +
* alarm event */
 +
alarm_event_delete(eve);
 +
}
-
  printf("cookie %ld:\n", (long)cookie);
 
-
 
-
  tmo -= eve->trigger;
 
-
  printf("appid = %s\n", alarm_event_get_alarm_appid(eve));
 
-
  printf("trigger = T%+ld, %s", (long)tmo, ctime(&eve->trigger));
 
-
  printf("message = %s\n", alarm_event_get_message(eve));
 
-
 
-
  for( int i = 0; (act = alarm_event_get_action(eve, i)) != 0; ++i )
 
-
  {
 
-
    printf("action%d.label = %s\n", i, alarm_action_get_label(act));
 
-
  }
 
-
 
-
  cleanup:
 
-
 
-
  /* Free all dynamic memory associated with the
 
-
  * alarm event */
 
-
  alarm_event_delete(eve);
 
-
}
 
-
</source>
 
==Deleting Alarm Event==
==Deleting Alarm Event==
 +
To delete an alarm event, the alarmd_event_del() function needs to be called, passing the event cookie as a parameter.
-
To delete an alarm event, the <code>alarmd_event_del()</code> function needs to be called, passing the event cookie as a parameter.
+
static void delete_alarm(cookie_t cookie)
 +
{
 +
if( alarmd_event_del(cookie) == -1 )
 +
{
 +
printf("unable to delete cookie=%ld\n", (long)cookie);
 +
}
 +
else
 +
{
 +
printf("deleted cookie=%ld\n", (long)cookie);
 +
}
 +
}
-
<source lang="c">
 
-
static void delete_alarm(cookie_t cookie)
 
-
{
 
-
  if( alarmd_event_del(cookie) == -1 )
 
-
  {
 
-
    printf("unable to delete cookie=%ld\n", (long)cookie);
 
-
  }
 
-
  else
 
-
  {
 
-
    printf("deleted cookie=%ld\n", (long)cookie);
 
-
  }
 
-
}
 
-
</source>
 
==Querying Multiple Alarm Events==
==Querying Multiple Alarm Events==
 +
The ''alarmd_event_query()'' function can be used for querying alarms in the queue.
-
The <code>alarmd_event_query()</code> function can be used for querying alarms in the queue.
+
static void list_alarms()
 +
{
 +
cookie_t *list = 0;
 +
cookie_t cookie = 0;
 +
alarm_event_t *eve = 0;
 +
 +
if( (list = alarmd_event_query(0,0, 0,0, APPID)) == 0 )
 +
{
 +
printf("query failed\n");
 +
goto cleanup;
 +
}
 +
 +
for( int i = 0; (cookie = list[i]) != 0; ++i )
 +
{
 +
alarm_event_delete(eve);
 +
 +
if( (eve = alarmd_event_get(cookie)) == 0 )
 +
{
 +
printf("unable to get details for cookie=%ld\n", (long)cookie);
 +
continue;
 +
}
 +
 +
printf("cookie: %ld, %s", cookie, ctime(&eve->trigger));
 +
}
 +
 +
cleanup:
 +
free(list);
 +
alarm_event_delete(eve);
 +
}
-
<source lang="c">
 
-
static void list_alarms()
 
-
{
 
-
  cookie_t *list = 0;
 
-
  cookie_t cookie = 0;
 
-
  alarm_event_t *eve = 0;
 
-
  if( (list = alarmd_event_query(0,0, 0,0, APPID)) == 0 )
+
==Modifying an Existing Alarm Event==
-
  {
+
If details of some already queued event need to be modified, this can be done by deleting the existing alarm and then adding new modified alarm.
-
    printf("query failed\n");
+
-
    goto cleanup;
+
-
  }
+
-
  for( int i = 0; (cookie = list[i]) != 0; ++i )
+
This process can be made faster and safer by using the alarmd_event_update() function, which does the delete old and new alarm in one D-Bus transaction.
-
  {
+
-
    alarm_event_delete(eve);
+
-
    if( (eve = alarmd_event_get(cookie)) == 0 )
+
static cookie_t update_alarm(cookie_t cookie)
-
    {
+
{
-
      printf("unable to get details for cookie=%ld\n", (long)cookie);
+
cookie_t result = -1;
-
      continue;
+
alarm_event_t *eve = 0;
-
    }
+
-
 
+
-
    printf("cookie: %ld, %s", cookie, ctime(&eve->trigger));
+
-
  }
+
   
   
-
  cleanup:
+
if( (eve = alarmd_event_get(cookie)) == 0 )
-
    free(list);
+
{
-
    alarm_event_delete(eve);
+
printf("unable to get details for cookie=%ld\n", (long)cookie);
-
}
+
goto cleanup;
-
</source>
+
}
 +
 +
alarm_event_set_message(eve, "Updated Message");
 +
eve->alarm_time = time(0) + 20;
 +
 +
result = alarmd_event_update(eve);
 +
 +
cleanup:
 +
 +
alarm_event_delete(eve);
 +
 +
return result;
 +
}
-
==Modifying an Existing Alarm Event==
+
==Handling Dynamic Memory==
 +
To make client software forward compatible all alarm events and associated action, recurrence and attribute items should be allocated using functions provided by libalarm.
-
If details of some already queued event need to be modified, this can be done by deleting the existing alarm and then adding new modified alarm.
+
Dynamically allocated member data should be accessed using the set/get functions provided by libalarm.
-
This process can be made faster and safer by using the <code>alarmd_event_update()</code> function, which does the delete old and new alarm in one D-Bus transaction.
+
Dynamically allocated structures should be released using the delete functions provided by libalarm.
-
<source lang="c">
+
Please note that alarm_event_delete() will assume that the above rules are followed and will try release all dynamic data associated with the alarm event structure.
-
static cookie_t update_alarm(cookie_t cookie)
+
-
{
+
-
  cookie_t result = -1;
+
-
  alarm_event_t *eve = 0;
+
-
  if( (eve = alarmd_event_get(cookie)) == 0 )
+
Thus avoid writing client code that:
-
  {
+
-
    printf("unable to get details for cookie=%ld\n", (long)cookie);
+
-
    goto cleanup;
+
-
  }
+
-
  alarm_event_set_message(eve, "Updated Message");
+
*Evaluates the size of libalarm structs at compile time
-
  eve->alarm_time = time(0) + 20;
+
-
  result = alarmd_event_update(eve);
+
alarm_event_t eve;
-
   
+
  alarm_event_t *eve = calloc(1, sizeof *eve);
-
  cleanup:
+
-
    alarm_event_delete(eve);
+
-
    return result;
+
-
}
+
-
</source>
+
-
==Handling Dynamic Memory==
+
*Direcly sets dynamic member data
-
To make client software forward compatible all alarm events and associated action, recurrence and attribute items should be allocated using functions provided by libalarm.
+
eve = alarm_event_create();
 +
self->alarm_appid = (char *)"myapp";
-
Dynamically allocated member data should be accessed using the set/get functions provided by libalarm. Dynamically allocated structures should be released using the delete functions provided by libalarm.
+
*Might leak memory, might corrupt heap.
-
Please note that <code>alarm_event_delete()</code> will assume that the above rules are followed and will try release all dynamic data associated with the alarm event structure.
+
eve = alarm_event_create();
 +
self->alarm_appid = strdup("myapp");
-
Thus avoid writing client code that:
 
-
 
-
* Evaluates the size of libalarm structs at compile time
 
-
<source lang="c">
 
-
  alarm_event_t eve;
 
-
  alarm_event_t *eve = calloc(1, sizeof *eve);
 
-
</source>
 
-
* Direcly sets dynamic member data
 
-
<source lang="c">
 
-
  eve = alarm_event_create();
 
-
  self->alarm_appid = (char *)"myapp";
 
-
</source>
 
-
* Might leak memory, might corrupt heap.
 
-
<source lang="c">
 
-
  eve = alarm_event_create();
 
-
  self->alarm_appid = strdup("myapp");
 
-
</source>
 
==Localized Strings==
==Localized Strings==
-
 
By default systemui dialog service will try to translate all text strings using gettext() API in hildon libraries textdomain.
By default systemui dialog service will try to translate all text strings using gettext() API in hildon libraries textdomain.
Line 266: Line 257:
'''Example: two button alarm dialog with textdomain specified'''
'''Example: two button alarm dialog with textdomain specified'''
-
<source lang="c">
 
-
#define TEXTDOMAIN "mydomain"
 
-
#define MESSAGE_KEY "translatable message text"
 
-
#define STOP_BUTTON_KEY "translatable stop text"
 
-
#define SNOOZE_BUTTON_KEY "translatable snooze text"
 
-
static cookie_t add_two_button_alarm_with_textdomain(void)
+
#define TEXTDOMAIN "mydomain"
-
{
+
#define MESSAGE_KEY "translatable message text"
-
  alarm_event_t *eve = 0;
+
#define STOP_BUTTON_KEY "translatable stop text"
-
  alarm_action_t *act = 0;
+
#define SNOOZE_BUTTON_KEY "translatable snooze text"
-
  cookie_t cookie = 0;
+
 +
static cookie_t add_two_button_alarm_with_textdomain(void)
 +
{
 +
alarm_event_t *eve = 0;
 +
alarm_action_t *act = 0;
 +
cookie_t cookie = 0;
 +
 +
/* Create alarm event structure, set application
 +
* identifier and dialog message */
 +
eve = alarm_event_create();
 +
alarm_event_set_alarm_appid(eve, APPID);
 +
alarm_event_set_message(eve, MESSAGE_KEY);
-
  /* Create alarm event structure, set application
+
/* Set the textdomain to be used while making
-
  * identifier and dialog message */
+
* translation lookups */
-
  eve = alarm_event_create();
+
-
  alarm_event_set_alarm_appid(eve, APPID);
+
alarm_event_set_attr_string(eve, "textdomain", TEXTDOMAIN);
-
  alarm_event_set_message(eve, MESSAGE_KEY);
+
 +
/* Use absolute time triggering, show dialog
 +
* ten seconds from now */
 +
eve->alarm_time = time(0) + 10;
 +
 +
/* Add stop button action */
 +
act = alarm_event_add_actions(eve, 1);
 +
alarm_action_set_label(act, STOP_BUTTON_KEY);
 +
act->flags |= ALARM_ACTION_WHEN_RESPONDED;
 +
act->flags |= ALARM_ACTION_TYPE_NOP;
 +
 +
/* Add snooze button action */
 +
act = alarm_event_add_actions(eve, 1);
 +
alarm_action_set_label(act, SNOOZE_BUTTON_KEY);
 +
act->flags |= ALARM_ACTION_WHEN_RESPONDED;
 +
act->flags |= ALARM_ACTION_TYPE_SNOOZE;
 +
 +
/* Send the alarm to alarmd */
 +
cookie = alarmd_event_add(eve);
 +
 +
/* Free all dynamic memory associated with the
 +
* alarm event */
 +
alarm_event_delete(eve);
 +
 +
return cookie;
 +
}
-
  /* Set the textdomain to be used while making
 
-
  * translation lookups */
 
-
 
-
  alarm_event_set_attr_string(eve, "textdomain", TEXTDOMAIN);
 
-
 
-
  /* Use absolute time triggering, show dialog
 
-
  * ten seconds from now */
 
-
  eve->alarm_time = time(0) + 10;
 
-
 
-
  /* Add stop button action */
 
-
  act = alarm_event_add_actions(eve, 1);
 
-
  alarm_action_set_label(act, STOP_BUTTON_KEY);
 
-
  act->flags |= ALARM_ACTION_WHEN_RESPONDED;
 
-
  act->flags |= ALARM_ACTION_TYPE_NOP;
 
-
 
-
  /* Add snooze button action */
 
-
  act = alarm_event_add_actions(eve, 1);
 
-
  alarm_action_set_label(act, SNOOZE_BUTTON_KEY);
 
-
  act->flags |= ALARM_ACTION_WHEN_RESPONDED;
 
-
  act->flags |= ALARM_ACTION_TYPE_SNOOZE;
 
-
 
-
  /* Send the alarm to alarmd */
 
-
  cookie = alarmd_event_add(eve);
 
-
 
-
  /* Free all dynamic memory associated with the
 
-
  * alarm event */
 
-
  alarm_event_delete(eve);
 
-
 
-
  return cookie;
 
-
}
 
-
</source>
 
-
 
-
==Alarm Event Demo/examples==
 
-
 
-
Documentation is great, but for many people seeing some real world examples of how to actually do things with alarmD is best. Here are some common tasks broken down and commented as best I can.
 
-
 
-
===Executing a command===
 
-
 
-
One of the most common uses for alarmD is to act like cron, and trigger a script/app to run at certain times. Here's an example of how to do that:
 
-
 
-
'''test function to try and set an alarm'''
 
-
<source lang="c">
 
-
int testSetAlarm()
 
-
{
 
-
  alarm_event_t *newEvent = 0;
 
-
  alarm_action_t *act = 0;
 
-
 
-
  /* AlarmD will return a unique "alarm cookie" if successful; you can use this
 
-
  * later to identify and manipulate your alarm, or just ignore it. */
 
-
  cookie_t resultCookie;
 
-
 
-
  /* Create a new alarm event object. */
 
-
  newEvent = alarm_event_create();
 
-
 
-
  /* Set the application ID. */
 
-
  alarm_event_set_alarm_appid(newEvent, "MYAPP");
 
-
 
-
  /* Set the title of the alarm. */
 
-
  alarm_event_set_title(newEvent, "testAlarm");
 
-
 
-
  /* If you are dealing with re-curring alarms, there are two ways to do this.
 
-
  * The "old way" is to simply set how many times you want to recur, and how
 
-
  * many seconds between each. I use this way because it's easier for simple
 
-
  * recurrence.
 
-
  *
 
-
  * "Old" way
 
-
  * Set the # of seconds between recurrences. Let's say once an hour for
 
-
  * example (60 seconds * 60 minutes = 1 hour): */
 
-
  newEvent->recur_secs = 60 * 60;
 
-
 
-
  /* How many times should the event occur? If you set this to -1, it will
 
-
  * reoccur infinitely. */
 
-
  newEvent->recur_count = -1;
 
-
 
-
  /* When will the event occur for the very first time? After this point it
 
-
  * will occur every 3600 seconds...
 
-
  * For this demo I will make the first alarm happen 1 hour from the current
 
-
  * time. This "time" is in standard UNIX time format, so you need # of
 
-
  * seconds since Unix Epoch. In C you do this by calling time(NULL); I then
 
-
  * add 3600 to make the time 1 hour ahead of current time. */
 
-
  newEvent->alarm_time = (time_t) time(NULL) + 3600;
 
-
 
-
  /* You can also use the "new way" of setting up timing on events, which
 
-
  * allows you to use a time structure instead of just a fixed # of seconds.
 
-
  * So you can make an alarm happen every Monday, for example, or every Monday
 
-
  * and Thursday. See the information earlier in the Wiki entry for details on
 
-
  * this. */
 
-
 
-
  /* Now that our event is setup, we need to add an action to it so that the
 
-
  * alarm actually "does" something. */
 
-
 
-
  /* Add 1 action to our alarm event, and assign it to the "act" variable. */
 
-
  act = alarm_event_add_actions(newEvent, 1);
 
-
 
-
  /* Now setup that action to do something. To do this we have to set the
 
-
  * action "flags". You can find all of them with explanations in the
 
-
  * documentation, here: http://maemo.org/api_refs/5.0/5.0-final/libalarm/libalarm_8h.html#cc8e6f439d134448001132132476683c910f7626ec85a4170659b53fa2f0abc7
 
-
  * Setup this action to be an "Execute command" one. */
 
-
  act->flags = ALARM_ACTION_WHEN_TRIGGERED | ALARM_ACTION_TYPE_EXEC;
 
-
 
-
  /* Now all you have to do is tell the action which command you want to
 
-
  * "execute". */
 
-
  alarm_action_set_exec_command(act, "/usr/sbin/myAwesomeCommand.sh");
 
-
 
-
  /* Finally with everything setup, try to add your event to the alarm queue. */
 
-
  resultCookie = alarmd_event_add(newEvent);
 
-
}
 
-
</source>
 
-
 
-
=== Triggering D-Bus actions ===
 
-
 
-
Triggering D-Bus actions is very similar to executing a command as above; the main difference is how you setup the <code>alarm_event_action</code>. Here is a simple D-Bus example:
 
-
 
-
'''test function to try and setup an alarm with a D-Bus action'''
 
-
<source lang="c">
 
-
int testSetAlarm()
 
-
{  alarm_event_t *newEvent = 0;
 
-
  alarm_action_t *act = 0;
 
-
 
-
  /* AlarmD will return a unique "alarm cookie" if successful; you can use this
 
-
  * later to identify and manipulate your alarm, or just ignore it. */
 
-
  cookie_t resultCookie;
 
-
 
-
  /* Create a new alarm event object. */
 
-
  newEvent = alarm_event_create();
 
-
 
-
  /* Set the application ID. */
 
-
  alarm_event_set_alarm_appid(newEvent, "MYAPP");
 
-
 
-
  /* Set the title of the alarm. */
 
-
  alarm_event_set_title(newEvent, "testAlarm");
 
-
 
-
  /* If you are dealing with re-curring alarms, there are two ways to do this.
 
-
  * The "old way" is to simply set how many times you want to recur, and how
 
-
  * many seconds between each. I use this way because it's easier for simple
 
-
  * recurrence.
 
-
  *
 
-
  * "Old" way
 
-
  * Set the # of seconds between recurrences. Let's say once an hour for
 
-
  * example (60 seconds * 60 minutes = 1 hour): */
 
-
  newEvent->recur_secs = 60 * 60;
 
-
 
-
  /* How many times should the event occur? If you set this to -1, it will
 
-
  * reoccur infinitely. */
 
-
  newEvent->recur_count = -1;
 
-
 
-
  /* When will the event occur for the very first time? After this point it
 
-
  * will occur every 3600 seconds...
 
-
  * For this demo I will make the first alarm happen 1 hour from the current
 
-
  * time. This "time" is in standard UNIX time format, so you need # of
 
-
  * seconds since Unix Epoch. In C you do this by calling time(NULL); I then
 
-
  * add 3600 to make the time 1 hour ahead of current time. */
 
-
  newEvent->alarm_time = (time_t) time(NULL) + 3600;
 
-
 
-
  /* Setup the event to boot the device if it's not powered on. */
 
-
  newEvent->flags = ALARM_EVENT_BOOT;
 
-
 
-
  /* Now that our event is setup, we need to add an action to it so that the
 
-
  * alarm actually "does" something. */
 
-
 
-
  /* Add 1 action to our alarm event, and assign it to the "act" variable. */
 
-
  act = alarm_event_add_actions(newEvent, 1);
 
-
 
-
  /* Now setup that action to do something. To do this we have to set the
 
-
  * action "flags". You can find all of them with explanations in the
 
-
  * documentation, here: http://maemo.org/api_refs/5.0/5.0-final/libalarm/libalarm_8h.html#cc8e6f439d134448001132132476683c910f7626ec85a4170659b53fa2f0abc7
 
-
  * Setup this action to be an "DBus command" one; also set it up to use D-Bus
 
-
  * auto-activation. */
 
-
  act->flags = ALARM_ACTION_WHEN_TRIGGERED | ALARM_ACTION_DBUS_USE_ACTIVATION | ALARM_ACTION_TYPE_DBUS;
 
-
 
-
  /* Setup the DBus params for this action. */
 
-
  alarm_action_set_dbus_interface(act, "org.maemo.testApp");
 
-
  alarm_action_set_dbus_service(act, "org.maemo.testApp");
 
-
  alarm_action_set_dbus_path(act, "/org/maemo/testApp");
 
-
  alarm_action_set_dbus_name(act, "triggerAlarm");
 
-
 
-
  /* Finally with everything setup, try to add your event to the alarm queue. */
 
-
  resultCookie = alarmd_event_add(newEvent);
 
-
}
 
-
</source>
 
==Obtaining more information==
==Obtaining more information==
-
For more information, see [http://maemo.org/api_refs/5.0/5.0-final/libalarm/ libalarm API documentation].
+
For more information, see [http://maemo.org/api_refs/5.0/beta/libalarm/ libalarm API documentation].
-
 
+
-
[[Category:Development]]
+
-
[[Category:Documentation]]
+
-
[[Category:Fremantle]]
+

Learn more about Contributing to the wiki.


Please note that all contributions to maemo.org wiki may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see maemo.org wiki:Copyrights for details). Do not submit copyrighted work without permission!


Cancel | Editing help (opens in new window)

Templates used on this page:

Retrieved from "http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Using_Generic_Platform_Components/Alarm_Framework"