OpieAlarms

= Technical: How Alarms work in Opie =

Any application can schedule an alarm. Two applications that currently use this system are the Clock and the Calendar. Automatically resuming before the alarm is handled and applications receive notifications when alarms trigger in the form of a QCop message.

The process of scheduling an alarm and having it triggered is as follows:
 * 1) An application that wants to schedule an alarm calls
 * 2) *  is the time for the alarm to trigger
 * 3) *  is the name of the QCop channel for your application (usually   - if you use the application channel then your application will be started automatically if it is not already running).
 * 4) *  is the QCop message to use eg.   (note that the parameters must always be  )
 * 5) *  (optional) is some special number to be passed along with the message if you need it.
 * 6)   will write to its alarm file, and the closest alarm date will be written as a Unix   (number of seconds since 1970) to the file.
 * 7) At some point in the future the device is suspended (eg.   is run)
 * 8) As part of the suspend process   runs a script
 * 9) The script will run  . This does the following:
 * 10) * Sets the RTC alarm to wake up the device 5 seconds before the time specified in
 * 11) * Checks if the difference between system and hardware time is more than 3 seconds, and if it is the hardware clock will be synchronised with the system clock (otherwise alarms won't work reliably).
 * 12) *  also forks a child process into the background and stays "running" while the device is suspended.
 * 13) The device is then suspended for some period of time. When the device wakes up,   will call   again which runs  . This terminates the running   process. (There is also some code in   to handle resuming on AC power connection, see the code for details).
 * 14) At the scheduled time,   will sent the registered QCop message to the specified channel.

Parts of the process

 * is a simple standalone program written in C. You can find the source in core/opiealarm
 * is defined in library/alarmserver.h and implemented in library/alarmserver.cpp. See also the AlarmServer API reference.
 * There is code to do a lot of this using  and   instead of , however it is not usually used.

Troubleshooting
If your device is not waking up as expected, it may be because:
 * a) The RTC alarm couldn't be written to, or another process wrote some other time into it (eg. atd)
 * b) The  value is generated with a wrong time because you don't have all timezone files installed
 * c) The appropriate rtc driver is not either loaded as a module or built into the kernel

If you want to investigate you can schedule your alarm as normal, run  manually and then peek at what value has actually been written for the RTC alarm. On handhelds-2.6 kernels this is available in.