Alarm instance generation support for the Wombat.

2000-12-18  Federico Mena Quintero  <federico@helixcode.com>

	Alarm instance generation support for the Wombat.

	* idl/evolution-calendar.idl (Cal::CalAlarmInstance): Changed to
	have an alarm UID, the trigger time, and the actual occurrence
	time.
	(Cal::CalComponentAlarms): New structure to hold a pair of a
	component and its alarms that trigger in a particular range of
	time.
	(Cal::getAlarmsInRange): Changed to return a CalComponentAlarmsSeq.

	* cal-util/cal-component.h (CalAlarmInstance): New C-side
	structure to match the one on the IDL.
	(CalComponentAlarms): Ditto.
	(CalAlarmAction): Renamed from CalComponentAlarmAction.
	(CalAlarmTriggerType): Renamed from CalComponentAlarmTriggerType.
	Encoded the START and END parameters for the RELATED parameter in
	this enum, too.  Added a NONE value for invalid or missing trigger
	specifications.
	(CalComponentAlarmTriggerRelated): Removed.
	(CalAlarmTrigger): Renamed from CalComponentAlarmTrigger.  Renamed
	the duration/time fields to rel_duration/abs_time, respectively.

	* cal-util/cal-component.c (cal_component_alarm_get_trigger):
	Changed to use the new trigger structure.
	(cal_component_alarm_set_trigger): Likewise.
	(cal_component_alarm_free_trigger): Removed function.
	(cal_component_has_alarms): Count the elements in the
	alarm_uid_hash instead of trying to fetch the first alarm subcomponent.
	(cal_component_alarms_free): New function to free a
	CalComponentAlarms structure.
	(CalComponentAlarmPrivate): Added an uid property pointer.
	(scan_alarm_property): Scan for the our extension UID property.
	(cal_component_alarm_get_uid): New function.

	* pcs/cal-backend.h (CalBackendClass): Changed the signatures of
	the ::get_alarms_in_range() and ::get_alarms_for_object() methods.

	* pcs/cal-backend.c (cal_backend_get_alarms_in_range): Changed
	signature; use the new method.
	(cal_backend_get_alarms_for_object): Likewise.

	* pcs/cal-backend-file.c (compute_alarm_range): New spiffy
	function to compute a range of time for alarm occurrences.
	(add_alarm_occurrences_cb): New function to add alarms for a
	particular occurrence of the component.
	(generate_absolute_triggers): New function to add the absolute
	alarm triggers.
	(generate_alarms_for_comp): New function to generate all the alarm
	instances for a component.
	(cal_backend_file_get_alarms_in_range): Implemented.

	* pcs/cal.c (Cal_get_alarms_in_range): Use the new CalBackend API.
	(Cal_get_alarms_for_object): Likewise.
	(build_alarm_instance_seq): Removed old function.

	* cal-util/cal-util.c (cal_alarm_instance_list_free): Removed
	function.

	* cal-client/cal-client.c (build_component_alarms_list): New
	function to demarshal the component alarms sequence.
	(build_alarm_instance_list): New function to demarshal the alarm
	instances sequence.
	(cal_client_get_alarms_in_range): Updated for the new API.
	(cal_client_get_alarms_for_object): Updated for the new API.

	* gui/gnome-cal.c: Temporary #ifdef-ing out of alarm-related stuff
	to make it build.

svn path=/trunk/; revision=7076

5 files changed, 69 insertions, 0 deletions

diff --git a/doc/devel/ChangeLog b/doc/devel/ChangeLog
index f536dde88d..85b7341bf0 100644
--- a/doc/devel/ChangeLog
+++ b/doc/devel/ChangeLog
@@ -1,3 +1,15 @@
+2000-12-18  Federico Mena Quintero  <federico@helixcode.com>
+
+	* calendar/alarm-generation.sgml: New file with a description of
+	the algorithm used to generate alarm instances.
+
+	* evolution-devel-guide.sgml: Added an entity for the above
+	chapter.
+
+	* calendar/evolution-calendar.sgml: Reference the entity here.
+
+	* calendar/Makefile.am (EXTRA_DIST): Added alarm-generation.sgml.
+
 2000-12-13  Larry Ewing  <lewing@helixcode.com>
 
 	* calendar/Makefile.am (EXTRA_DIST): make it public-reference.sgml
diff --git a/doc/devel/calendar/Makefile.am b/doc/devel/calendar/Makefile.am
index 66c3436d59..207672f303 100644
--- a/doc/devel/calendar/Makefile.am
+++ b/doc/devel/calendar/Makefile.am
@@ -1,6 +1,7 @@
 SUBDIRS = cal-client cal-util
 
 EXTRA_DIST =				\
+	alarm-generation.sgml		\
 	architecture.sgml		\
 	evolution-calendar.sgml		\
 	public-reference.sgml
diff --git a/doc/devel/calendar/alarm-generation.sgml b/doc/devel/calendar/alarm-generation.sgml
new file mode 100644
index 0000000000..60bc78343e
--- /dev/null
+++ b/doc/devel/calendar/alarm-generation.sgml
@@ -0,0 +1,54 @@
+  <chapter id="calendar-alarm-generation">
+    <title>How the Wombat generates alarm instances</title>
+
+    <para>
+      This chapter describes the algorithm that the &Wombat; uses
+      internally to generate instances of a calendar component's
+      alarms.  You do not need to read this chapter if you are simply
+      using the client-side functions.
+    </para>
+
+    <sect1 id="what-makes-up-an-alarm-trigger">
+      <title>What makes up an alarm trigger</title>
+
+      <para>
+	VTODO and VEVENT calendar components can have any number of
+	alarms defined for them.  Each alarm has a trigger
+	specification, an alarm type (display, audio, email, or
+	procedure), and data corresponding to the alarm type.  The
+	Wombat side of things is interested only in the trigger
+	specification, since this is all that the Wombat needs to
+	produce alarm instances.
+      </para>
+
+      <para>
+	An alarm trigger can be relative or absolute.  Relative
+	triggers occur a certain time before or after the start or end
+	of a calendar component's occurrence.  For example, you could
+	configure a trigger to notify you 15 minutes before an
+	appointment starts, so that you can get to its location on
+	time; or another one to notify you 5 minutes after another
+	person's meeting has ended, so that you can call that person
+	on the phone after the meeting and not disturb him while
+	there.  Absolute triggers occur at a specific point in time;
+	you can configure an alarm to trigger exactly at a particular
+	date and time that has no relation to the component's
+	occurrences at all.
+      </para>
+    </sect1>
+
+    <sect1 id="generating-trigger-instances">
+      <title>Generating trigger instances</title>
+
+      <para>
+	
+      </para>
+    </sect1>
+  </chapter>
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../evolution-devel-guide.sgml" "book" "part" "")
+End:
+-->
diff --git a/doc/devel/calendar/evolution-calendar.sgml b/doc/devel/calendar/evolution-calendar.sgml
index 82015689ec..019fef9ea4 100644
--- a/doc/devel/calendar/evolution-calendar.sgml
+++ b/doc/devel/calendar/evolution-calendar.sgml
@@ -41,6 +41,7 @@
     </partintro>
 
     &calendar-architecture;
+    &calendar-alarm-generation;
   </part>
 
 <!--
diff --git a/doc/devel/evolution-devel-guide.sgml b/doc/devel/evolution-devel-guide.sgml
index d0988eb1aa..0798375c98 100644
--- a/doc/devel/evolution-devel-guide.sgml
+++ b/doc/devel/evolution-devel-guide.sgml
@@ -5,6 +5,7 @@
 
 <!ENTITY evolution-calendar SYSTEM "calendar/evolution-calendar.sgml">
 <!ENTITY calendar-architecture SYSTEM "calendar/architecture.sgml">
+<!ENTITY calendar-alarm-generation SYSTEM "calendar/alarm-generation.sgml">
 <!ENTITY calendar-public-reference SYSTEM "calendar/public-reference.sgml">
 <!ENTITY CalClient SYSTEM "calendar/cal-client/sgml/cal-client.sgml">
 <!ENTITY CalComponent SYSTEM "calendar/cal-util/sgml/cal-component.sgml">