Using Maemo’s alarm framework with Qt – The basics

October 15, 2010 by Zoran

Whew, finally found some time to write another post. This time we’ll be using Maemo’s alarm framework to do, well, almost whatever we want at a specific time, or even repeatedly at specific times :) So let’s get to it.

This will actually be a mini-series of posts. I tried to put everything at once but failed miserably :) These are the series’ parts published till now:

  1. The basics (this one)

The heart of the alarm framework is the alarmd daemon which is responsible for doing stuff at specific times. Basically, we can tell it to raise a system alarm, execute a shell command on our behalf or make a D-Bus method invocation. The raising of system alarm entails displaying the standard Maemo system alarm UI with the time of the alarm, some description and a few buttons so the user can aknowledge or snooze the alarm for example. Executing a shell command (this, of course, includes launching a program) is pretty self explanatory. Describing the D-Bus framework is way beyond the scope of this post so I will just refer you to the D-Bus documentation if you want to know more. Or you can also wait and see if I make a post about D-Bus in the future ;)

Now that the big picture is a little clearer lets spend a few moments describing the nitty gritty before jumping in. The alarmd functionality is available using the C API via the libalarm maemo library. You already guess what we are going to do. We’ll just link with this library and use it’s API for playing with the alarms. On to code…

I’m presuming a standard Nokia Qt SDK installation and using Qt Creator as our IDE. Naturally, you’ll also need a test project (or a real one if you prefer :)). First thing we need to do is tell qmake that we want to use the libalarm C library. We do this by adding the following lines into our project file:

maemo5 {
    QT += maemo5
    LIBS += -lalarm

This means that the two lines between the curly braces are taken into consideration only if we are building for the Maemo platform. The first line tells qmake that we want the standard Maemo Qt module (this is needed for every Maemo application we make). With the second line we announce that we want to link the libalarm library which resides on the standard library search path. If this last line contained a lot of gibberish to you fear not, everything will become clearer if you study the gcc linking documentation. If you want to know more about the whole library linking stuff take a look at the TLDP program libraray documentation, especially the shared libraries chapter.

Now we can write some alarm setting code:

// Header stuff...

#if defined(Q_WS_MAEMO_5)

// Other code...

    alarm_event_t * event = 0;
    alarm_action_t * act = 0;

    // Setup
    event = alarm_event_create();
    // The application id field is needed for every alarm you set
    alarm_event_set_alarm_appid(event, "Alarm testing app");
    // Alarm description displayed when the alarm is triggered
    alarm_event_set_message(event, "The alarm message for the system UI");
    // Set the alarm time 30s form now
    event->alarm_time = time(0) + 30;

    // Acknowledge action
    act = alarm_event_add_actions(event, 1);
    alarm_action_set_label(act, "Stop");
    act->flags |= ALARM_ACTION_TYPE_NOP;

    // Snooze action
    act = alarm_event_add_actions(event, 1);
    alarm_action_set_label(act, "Snooze");
    act->flags |= ALARM_ACTION_TYPE_SNOOZE;

    // Pass the structure to the alarmd daemon
    // Cleanup
    act = 0;
    event = 0;

// More other code...

This is the most basic of the alarm examples. It simply sets an alarm to trigger 30 seconds from the time it was set. The standard Maemo alarm system UI will display the set message and will give the user two buttons, one to aknowledge the alarm (“Stop”) and the other to snooze the alarm by the standard specified system snooze time (“Snooze”) which is by default set to 10 minutes.

I think my time for this post is at the end so I’ll bid you a fond farewell. Next time we’ll complicate things up a little bit by setting our own snooze interval and executing custom commands when the alarm is triggered. So stay tuned.

Here’s the series TOC till now for your convenience:

  1. The basics (this one)