Using the alarm interface

Introduction

This document has been reviewed for maemo 3.x release.

The maemo alarm framework provides an easy way to manage timed events in your device. It is powerful and not restricted only to "wake up" alarms. The framework provides many other features, including:

• Set multiple alarm events
• Configure the number of recurrences and the time between each one
• Choose whether the alarm dialog should be shown or not
• Set the title and the message to be shown in the alarm dialog
• Select a custom icon file to be shown in the alarm dialog
• Select a custom sound file to be played while the alarm dialog is shown
• Choose to boot the device if it is turned off
• Choose to run the alarm only if the device is connected
• Choose to run the alarm in the system startup if it is missed
• Choose to postpone the alarm if it is missed
• Execute a given file (e.g., a program or a script)
• Send a message to a D-Bus message bus
• Query for existing alarm events in a given period of time
• Delete an existing alarm event
• Configure the snooze time for the event
• Configure the default snooze time for all alarm events

This document shows how to use the alarm interface describing all its functions and giving examples of use cases.

Alarm events

Alarm events and the functions to manage them are defined in alarm_event.h header file located in /usr/include/alarmd. It is part of libalarm-dev debian package.

Each alarm event is identified by an unique key also known as "cookie". These identifiers are are obtained when a new event is added to the queue. They are used whenever you want to or retrieve information about an specific event or delete it. An alarm event is identified by the alarm_event_t structure, described as follows:

#include <alarmd/alarm_event.h>

/**
 * cookie_t:
 *
 * Unique identifier type for the alarm events.
 **/

typedef long cookie_t;

/**
 * alarm_event_t:
 *
 * Describes an alarm event.
 **/

typedef struct {
	time_t alarm_time;
        uint32_t recurrence;
        int32_t recurrence_count;
        uint32_t snooze;
        char *title;
        char *message;
        char *sound;
        char *icon;
        char *dbus_interface;
        char *dbus_service;
        char *dbus_path;
        char *dbus_name;
        char *exec_name;
        int32_t flags;
        uint32_t snoozed;
} alarm_event_t;

Table 1. Description of structure alarm_event_t fields

The flags field in the alarm_event_t structure above, holds the options of an alarm event. This field is a bitwise of one or more items described in alarmeventflags enumeration:

#include <alarmd/alarm_event.h>

typedef enum {
    ALARM_EVENT_NO_DIALOG = 1 << 0,
    ALARM_EVENT_NO_SNOOZE = 1 << 1,
    ALARM_EVENT_SYSTEM = 1 << 2,
    ALARM_EVENT_BOOT = 1 << 3,
    ALARM_EVENT_ACTDEAD = 1 << 4,
    ALARM_EVENT_SHOW_ICON = 1 << 5,
    ALARM_EVENT_RUN_DELAYED = 1 << 6,
    ALARM_EVENT_CONNECTED = 1 << 7,
    ALARM_EVENT_ACTIVATION = 1 << 8,
    ALARM_EVENT_POSTPONE_DELAYED = 1 << 9,
    ALARM_EVENT_BACK_RESCHEDULE = 1 << 10,
} alarmeventflags;

Table 2. Description of alarmeventflags values

Managing alarm events

#include <alarmd/alarm_event.h>

/**
 * alarm_event_add:
 *
 * Adds an event to the alarm queue.
 **/

cookie_t alarm_event_add(alarm_event_t *event);
        

#include <stdio.h>
#include <string.h>
#include <time.h>

#include <alarmd/alarm_event.h>

int main (int argc, char *argv[])
{
      time_t time_now;
      struct tm *st_time;
      alarm_event_t event;
      cookie_t      cookie;

      /* Zero the event */
      memset (&event, 0, sizeof (alarm_event_t));

      /* Get current time */
      time (&time_now);
      st_time = localtime (&time_now);

      /* Add 10 minutes to tm_min field */
      st_time->tm_min += 10;

      /* Set the time in alarm_event_t structure */
      event.alarm_time = mktime (st_time);

      cookie = alarm_event_add (&event);

      if (cookie == 0) {
          /* Error */
          printf ("Error setting alarm event. Error code: '%d'\n", alarmd_get_error ());
          return 1;
      }

      printf ("Alarm event successfully set to %s. Event cookie: %ld\n", ctime (&event.alarm_time), cookie);
      return 0;
}
        

#include <alarmd/alarm_event.h>

/**
 * alarm_event_get:
 *
 * Finds an alarm with given identifier and returns alarm_event struct describing it.
 **/

alarm_event_t *alarm_event_get(cookie_t event_cookie);
        

#include <alarmd/alarm_event.h>

/**
 * alarm_event_free:
 *
 * Frees given alarm_event struct.
 **/

void alarm_event_free(alarm_event_t *event);
        

#include <alarmd/alarm_event.h>

/**
 * alarm_event_del:
 *
 * Deletes alarm from the alarm queue.
 **/

int alarm_event_del(cookie_t event_cookie);
        

Checking for errors

Whenever an error occurs during a call to any of the functions, a error code is set, which can be obtained with the alarmd_get_error function. It has the following signature:

#include <alarmd/alarm_event.h>

/**
 * alarmd_get_error:
 *
 * Gets the error code for previous action.
 **/

alarm_error_t alarmd_get_error(void);
	

The possible values returned by this function are defined by alarm_error_t enumeration, described below:

#include <alarmd/alarm_event.h>

typedef enum {
    ALARMD_SUCCESS,
    ALARMD_ERROR_DBUS,
    ALARMD_ERROR_CONNECTION,
    ALARMD_ERROR_INTERNAL,
    ALARMD_ERROR_MEMORY,
    ALARMD_ERROR_ARGUMENT
} alarm_error_t;
	

Table 3. Description of alarm_error_t values

Localized Strings

If you need the message in alarm dialog to be in whatever language is used in the device, you can use specially formatted strings. The translations are fetched with dgettext. To get your message translated, you need to specify the package from which to fetch the translation and the message id. The format is as follows:

{message domain,message id}
	

If the translation contains "%s", the the replacements for these can be given too:

 

{message domain,message	id,replacement1,replacement2...}
	

The replacement may be in form {...}, but cannot contain anything else, in the main string the translated part can be embedded. Postitional parameters or any other format options than %s are not supported.

#include <alarmd/alarm_event.h>

/**
 * alarm_escape_string:
 *
 * Escapes a string to be used as alarm dialog message or title.
 **/

char *alarm_escape_string(const char *string);
        

#include <alarmd/alarm_event.h>

/**
 * alarm_unescape_string:
 *
 * Unescapes a string escaped with alarm_escape_string.
 **/

char *alarm_unescape_string(const char *string);
        

#include <alarmd/alarm_event.h>

/**
 * alarm_unescape_string_noalloc:
 *
 * Unescapes a string escaped with alarm_escape_string.
 **/

char *alarm_unescape_string_noalloc(char *string);
        

References

Further information about D-BUS, GConf and GTK+ can be found at their websites:

1. D-BUS site
2. GConf site
3. GTK+ home page

Example Code

A full example code for how to use the alarm API can be found as part of maemo-examples. The required files are example_alarm.c, example_alarm_dbus.xml, Makefile and example_common.h.