Documentation/Maemo 5 Developer Guide/Using Generic Platform Components/Alarm Framework - Revision history

amigadave: /* Alarm framework features */ link

2010-11-12T10:09:05Z

Alarm framework features: link

← Older revision		Revision as of 10:09, 12 November 2010
Line 16:		Line 16:
	* 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 D-Bus message bus	+	* Sending a message to a [[Documentation/Maemo 5 Developer Guide/DBus/DBus Basics\|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
Line 30:		Line 30:
	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 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.	+	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.

	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.

amigadave: use `, add maemo.org/packages link`


2010-08-17T14:07:09Z
use <code>, add maemo.org/packages link

		
		
		
		
		
		
		← Older revision
		Revision as of 14:07, 17 August 2010
		
		Line 34:
Line 34:
 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 alarm_queue.ini, located in <code>/var/cache/alarmd</code> directory. + 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.
  
 == Alarm Events ==  == Alarm Events ==
  
- Alarm events and the functions to manage them are defined in libalarm.h header file located in <code>/usr/include/alarmd</code>. It is a part of the <code>libalarm-dev</code> Debian package. + 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 event structures contains basic information about the alarm such as:  Alarm event structures contains basic information about the alarm such as:
Line 109:
Line 109:
 }  }
 </source>  </source>
- {{ambox|text=Use of absolute time triggering, i.e., alarm_time field of the alarm event, allows 1-second precision. Alarms that use broken-down time, i.e., alarm_tm 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.}} +  
  + {{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===
Line 152:
Line 153:
  
 To delete an alarm event, the <code>alarmd_event_del()</code> 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.
  + 
 <source lang="c">  <source lang="c">
 static void delete_alarm(cookie_t cookie)  static void delete_alarm(cookie_t cookie)
Line 169:
Line 171:
  
 The <code>alarmd_event_query()</code> 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.
  + 
 <source lang="c">  <source lang="c">
 static void list_alarms()  static void list_alarms()



amigadave: use  and , tidy

2010-06-28T15:20:17Z
use <source> and <code>, tidy
Show changes


78.243.249.125: recur_count should be -1 to reoccur infinitely (not 0)
2010-06-27T08:52:08Z
recur_count should be -1 to reoccur infinitely (not 0)

		
		
		
		
		
		
		← Older revision
		Revision as of 08:52, 27 June 2010
		
		Line 357:
Line 357:
   	newEvent->recur_secs = 60 * 60;    	newEvent->recur_secs = 60 * 60;
   	    	
-   	//How many times should the event occur? If you set this to 0, it will reoccur infinitely. +   	//How many times should the event occur? If you set this to -1, it will reoccur infinitely.
-   	newEvent->recur_count =0; +   	newEvent->recur_count = -1;
   	    	
   	//When will the event occur for the very first time? After this point  it will occur every 3600 seconds...    	//When will the event occur for the very first time? After this point  it will occur every 3600 seconds...
Line 386:
Line 386:
 	  	
   }    }
-  
  
 === Triggering DBus actions ===  === Triggering DBus actions ===




78.243.249.125: recur_count should be -1 to reoccur infinitely (not 0)
2010-06-27T08:51:16Z
recur_count should be -1 to reoccur infinitely (not 0)

		
		
		
		
		
		
		← Older revision
		Revision as of 08:51, 27 June 2010
		
		Line 435:
Line 435:
   	newEvent->recur_secs = 60 * 60;    	newEvent->recur_secs = 60 * 60;
 	  	
-   	//How many times should the event occur? If you set this to 0, it will reoccur infinitely. +   	//How many times should the event occur? If you set this to -1, it will reoccur infinitely.
-   	newEvent->recur_count =0; +   	newEvent->recur_count = -1;
 	  	
   	//When will the event occur for the very first time? After this point it will occur every 3600 seconds...    	//When will the event occur for the very first time? After this point it will occur every 3600 seconds...
Line 468:
Line 468:
   	    	
   }    }
-  
-  
  
 ==Obtaining more information==  ==Obtaining more information==




amigadave: /* Obtaining more information */ update libalarm API reference
2010-03-31T09:40:03Z
Obtaining more information:  update libalarm API reference

		
		
		
		
		
		
		← Older revision
		Revision as of 09:40, 31 March 2010
		
		Line 473:
Line 473:
 ==Obtaining more information==  ==Obtaining more information==
  
- For more information, see [http://maemo.org/api_refs/5.0/beta/libalarm/ libalarm API documentation]. + For more information, see [http://maemo.org/api_refs/5.0/5.0-final/libalarm/ libalarm API documentation].
  
 [[Category:Development]]  [[Category:Development]]
 [[Category:Documentation]]  [[Category:Documentation]]
 [[Category:Fremantle]]  [[Category:Fremantle]]




amigadave: categorise
2010-02-12T12:54:53Z
categorise

		
		
		
		
		
		
		← Older revision
		Revision as of 12:54, 12 February 2010
		
		Line 474:
Line 474:
  
 For more information, see [http://maemo.org/api_refs/5.0/beta/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]]




tapio: added a note about alarm_time and alarm_tm fields.
2010-01-07T11:52:46Z
added a note about alarm_time and alarm_tm fields.

		
		
		
		
		
		
		← Older revision
		Revision as of 11:52, 7 January 2010
		
		Line 108:
Line 108:
   return cookie;    return cookie;
   }    }
  + {{ambox|text=N.B. Use of absolute time triggering, i.e., alarm_time field of the alarm event, allows 1-second precision. Alarms that use broken-down time, i.e., alarm_tm 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===




jolouis: /* Alarm Framework */
2009-11-17T15:45:10Z
Alarm Framework
Show changes


jolouis: /* Alarm Framework */
2009-11-17T15:26:44Z
Alarm Framework

		
		
		
		
		
		
		← Older revision
		Revision as of 15:26, 17 November 2009
		
		Line 305:
Line 305:
   return cookie;    return cookie;
   }    }
  + 
  + 
  + ==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:
  + 
  + 
  + /************************************************
  + * testSetAlarm()
  + * 
  + * Test function to try and set an alarm
  + ************************************************/
  + 
  + int testSetAlarm() {
  + 	//In C you have to declare the things you're using first...
  + 	
  + 	//This is the "alarm event" structure/object I'll use. It's empty right now.
  + 	alarm_event_t *newEvent = 0;
  + 	
  + 	//This is the "alarm event action" structure/object that I'll use. It's empty right now.
  + 	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;
  + 	
  + 	
  + 	//Actual code begins here...
  + 	
  + 	//This is step 1: create a new alarm event object.
  + 	newEvent = alarm_event_create();	//Create the default alarm struct.
  + 	
  + 	//This is step 2:Set the APP ID
  + 	alarm_event_set_alarm_appid(newEvent, "MYAPP");
  + 	
  + 	//This is step 3: Set the title
  + 	alarm_event_set_title(newEvent, "testAlarm");
  + 
  + 	//Now for the tricky part, step 4: timing.
  + 	/* If you're 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 recurr, 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 0, it will reoccur infinitely.
  + 	newEvent->recur_count =0;
  + 	
  + 	//When will the event occur for the very first time? After this point it will occur every 3600 seconds...
  + 	//For this demo I'll 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 docs, 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);
  + 	
  + }
  + 
  + 
  + === Triggering DBus actions ===
  + 
  + Triggering Dbus actions is very similar to executing a command as above; the main difference is how you setup the alarm_event_action. Here's a simple DBus example:
  + 
  + 
  + 
  + /************************************************
  + * testSetAlarm()
  + * 
  + * Test function to try and set an alarm
  + ************************************************/
  + 
  + int testSetAlarm() {
  + 	//In C you have to declare the things you're using first...
  + 	
  + 	//This is the "alarm event" structure/object I'll use. It's empty right now.
  + 	alarm_event_t *newEvent = 0;
  + 	
  + 	//This is the "alarm event action" structure/object that I'll use. It's empty right now.
  + 	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;
  + 	
  + 	
  + 	//Actual code begins here...
  + 	
  + 	//This is step 1: create a new alarm event object.
  + 	newEvent = alarm_event_create();	//Create the default alarm struct.
  + 	
  + 	//This is step 2:Set the APP ID
  + 	alarm_event_set_alarm_appid(newEvent, "MYAPP");
  + 	
  + 	//This is step 3: Set the title
  + 	alarm_event_set_title(newEvent, "testAlarm");
  + 
  + 	//Now for the tricky part, step 4: timing.
  + 	/* If you're 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 recurr, and how many seconds between each. I use this way because it's easier
  + 	for basic tasks
  + 	*/
  + 	//"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 0, it will reoccur infinitely.
  + 	newEvent->recur_count =0;
  + 	
  + 	//When will the event occur for the very first time? After this point it will occur every 3600 seconds...
  + 	//For this demo I'll 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 docs, 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 DBUS 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);
  + 	
  + }

← Older revision		Revision as of 14:07, 17 August 2010
Line 34:		Line 34:
	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 alarm_queue.ini, located in <code>/var/cache/alarmd</code> directory.	+	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.

	== Alarm Events ==		== Alarm Events ==

-	Alarm events and the functions to manage them are defined in libalarm.h header file located in <code>/usr/include/alarmd</code>. It is a part of the ~~<code>~~libalarm-dev</~~code>~~ Debian package.	+	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 event structures contains basic information about the alarm such as:		Alarm event structures contains basic information about the alarm such as:
Line 109:		Line 109:
	}		}
	</source>		</source>
-	{{ambox\|text=Use of absolute time triggering, i.e., alarm_time field of the alarm event, allows 1-second precision. Alarms that use broken-down time, i.e., alarm_tm 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.}}	+
		+	{{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===
Line 152:		Line 153:

	To delete an alarm event, the <code>alarmd_event_del()</code> 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.
		+
	<source lang="c">		<source lang="c">
	static void delete_alarm(cookie_t cookie)		static void delete_alarm(cookie_t cookie)
Line 169:		Line 171:

	The <code>alarmd_event_query()</code> 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.
		+
	<source lang="c">		<source lang="c">
	static void list_alarms()		static void list_alarms()

← Older revision		Revision as of 08:52, 27 June 2010
Line 357:		Line 357:
	newEvent->recur_secs = 60 * 60;		newEvent->recur_secs = 60 * 60;

-	//How many times should the event occur? If you set this to 0, it will reoccur infinitely.	+	//How many times should the event occur? If you set this to -1, it will reoccur infinitely.
-	newEvent->recur_count =0;	+	newEvent->recur_count = -1;

	//When will the event occur for the very first time? After this point it will occur every 3600 seconds...		//When will the event occur for the very first time? After this point it will occur every 3600 seconds...
Line 386:		Line 386:

	}		}
-

	=== Triggering DBus actions ===		=== Triggering DBus actions ===

← Older revision		Revision as of 08:51, 27 June 2010
Line 435:		Line 435:
	newEvent->recur_secs = 60 * 60;		newEvent->recur_secs = 60 * 60;

-	//How many times should the event occur? If you set this to 0, it will reoccur infinitely.	+	//How many times should the event occur? If you set this to -1, it will reoccur infinitely.
-	newEvent->recur_count =0;	+	newEvent->recur_count = -1;

	//When will the event occur for the very first time? After this point it will occur every 3600 seconds...		//When will the event occur for the very first time? After this point it will occur every 3600 seconds...
Line 468:		Line 468:

	}		}
-
-

	==Obtaining more information==		==Obtaining more information==

← Older revision		Revision as of 09:40, 31 March 2010
Line 473:		Line 473:
	==Obtaining more information==		==Obtaining more information==

-	For more information, see [http://maemo.org/api_refs/5.0/~~beta~~/libalarm/ libalarm API documentation].	+	For more information, see [http://maemo.org/api_refs/5.0/5.0-final/libalarm/ libalarm API documentation].

	[[Category:Development]]		[[Category:Development]]
	[[Category:Documentation]]		[[Category:Documentation]]
	[[Category:Fremantle]]		[[Category:Fremantle]]

← Older revision		Revision as of 12:54, 12 February 2010
Line 474:		Line 474:

	For more information, see [http://maemo.org/api_refs/5.0/beta/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]]

← Older revision		Revision as of 11:52, 7 January 2010
Line 108:		Line 108:
	return cookie;		return cookie;
	}		}
		+	{{ambox\|text=N.B. Use of absolute time triggering, i.e., alarm_time field of the alarm event, allows 1-second precision. Alarms that use broken-down time, i.e., alarm_tm 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===

← Older revision		Revision as of 15:26, 17 November 2009
Line 305:		Line 305:
	return cookie;		return cookie;
	}		}
		+
		+
		+	==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:
		+
		+
		+	/************************************************
		+	* testSetAlarm()
		+	*
		+	* Test function to try and set an alarm
		+	************************************************/
		+
		+	int testSetAlarm() {
		+	//In C you have to declare the things you're using first...
		+
		+	//This is the "alarm event" structure/object I'll use. It's empty right now.
		+	alarm_event_t *newEvent = 0;
		+
		+	//This is the "alarm event action" structure/object that I'll use. It's empty right now.
		+	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;
		+
		+
		+	//Actual code begins here...
		+
		+	//This is step 1: create a new alarm event object.
		+	newEvent = alarm_event_create(); //Create the default alarm struct.
		+
		+	//This is step 2:Set the APP ID
		+	alarm_event_set_alarm_appid(newEvent, "MYAPP");
		+
		+	//This is step 3: Set the title
		+	alarm_event_set_title(newEvent, "testAlarm");
		+
		+	//Now for the tricky part, step 4: timing.
		+	/* If you're 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 recurr, 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 0, it will reoccur infinitely.
		+	newEvent->recur_count =0;
		+
		+	//When will the event occur for the very first time? After this point it will occur every 3600 seconds...
		+	//For this demo I'll 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 docs, 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);
		+
		+	}
		+
		+
		+	=== Triggering DBus actions ===
		+
		+	Triggering Dbus actions is very similar to executing a command as above; the main difference is how you setup the alarm_event_action. Here's a simple DBus example:
		+
		+
		+
		+	/************************************************
		+	* testSetAlarm()
		+	*
		+	* Test function to try and set an alarm
		+	************************************************/
		+
		+	int testSetAlarm() {
		+	//In C you have to declare the things you're using first...
		+
		+	//This is the "alarm event" structure/object I'll use. It's empty right now.
		+	alarm_event_t *newEvent = 0;
		+
		+	//This is the "alarm event action" structure/object that I'll use. It's empty right now.
		+	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;
		+
		+
		+	//Actual code begins here...
		+
		+	//This is step 1: create a new alarm event object.
		+	newEvent = alarm_event_create(); //Create the default alarm struct.
		+
		+	//This is step 2:Set the APP ID
		+	alarm_event_set_alarm_appid(newEvent, "MYAPP");
		+
		+	//This is step 3: Set the title
		+	alarm_event_set_title(newEvent, "testAlarm");
		+
		+	//Now for the tricky part, step 4: timing.
		+	/* If you're 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 recurr, and how many seconds between each. I use this way because it's easier
		+	for basic tasks
		+	*/
		+	//"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 0, it will reoccur infinitely.
		+	newEvent->recur_count =0;
		+
		+	//When will the event occur for the very first time? After this point it will occur every 3600 seconds...
		+	//For this demo I'll 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 docs, 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 DBUS 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);
		+
		+	}

Documentation/Maemo 5 Developer Guide/Using Generic Platform Components/Alarm Framework - Revision history

amigadave: /* Alarm framework features */ link

amigadave: use , add maemo.org/packages link

amigadave: use and , tidy

78.243.249.125: recur_count should be -1 to reoccur infinitely (not 0)

78.243.249.125: recur_count should be -1 to reoccur infinitely (not 0)

amigadave: /* Obtaining more information */ update libalarm API reference

amigadave: categorise

tapio: added a note about alarm_time and alarm_tm fields.

jolouis: /* Alarm Framework */

jolouis: /* Alarm Framework */

amigadave: use `, add maemo.org/packages link`

amigadave: use and `, tidy`