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

1 files changed, 64 insertions, 31 deletions

diff --git a/calendar/cal-util/cal-component.h b/calendar/cal-util/cal-component.h
index f59bb33a7b..893e066f52 100644
--- a/calendar/cal-util/cal-component.h
+++ b/calendar/cal-util/cal-component.h
@@ -51,7 +51,9 @@ typedef enum {
 	CAL_COMPONENT_TIMEZONE
 } CalComponentVType;
 
-/* Field identifiers for a calendar component */
+/* Field identifiers for a calendar component; these are used by the data model
+ * for ETable.
+ */
 typedef enum {
 	CAL_COMPONENT_FIELD_CATEGORIES,		/* concatenation of the categories list */
 	CAL_COMPONENT_FIELD_CLASSIFICATION,
@@ -74,8 +76,9 @@ typedef enum {
 	CAL_COMPONENT_FIELD_NUM_FIELDS
 } CalComponentField;
 
-/* Structures to return properties and their parameters */
+/* Structures and enumerations to return properties and their parameters */
 
+/* CLASSIFICATION property */
 typedef enum {
 	CAL_COMPONENT_CLASS_NONE,
 	CAL_COMPONENT_CLASS_PUBLIC,
@@ -84,6 +87,7 @@ typedef enum {
 	CAL_COMPONENT_CLASS_UNKNOWN
 } CalComponentClassification;
 
+/* Properties that have time and timezone information */
 typedef struct {
 	/* Actual date/time value */
 	struct icaltimetype *value;
@@ -92,11 +96,13 @@ typedef struct {
 	const char *tzid;
 } CalComponentDateTime;
 
+/* Way in which a period of time is specified */
 typedef enum {
 	CAL_COMPONENT_PERIOD_DATETIME,
 	CAL_COMPONENT_PERIOD_DURATION
 } CalComponentPeriodType;
 
+/* Period of time, can have explicit start/end times or start/duration instead */
 typedef struct {
 	CalComponentPeriodType type;
 
@@ -108,6 +114,7 @@ typedef struct {
 	} u;
 } CalComponentPeriod;
 
+/* Text properties */
 typedef struct {
 	/* Description string */
 	const char *value;
@@ -116,6 +123,7 @@ typedef struct {
 	const char *altrep;
 } CalComponentText;
 
+/* Time transparency */
 typedef enum {
 	CAL_COMPONENT_TRANSP_NONE,
 	CAL_COMPONENT_TRANSP_TRANSPARENT,
@@ -123,7 +131,7 @@ typedef enum {
 	CAL_COMPONENT_TRANSP_UNKNOWN
 } CalComponentTransparency;
 
-typedef struct _CalComponentAlarm CalComponentAlarm;
+/* Main calendar component object */
 
 typedef struct _CalComponent CalComponent;
 typedef struct _CalComponentClass CalComponentClass;
@@ -262,37 +270,58 @@ void cal_component_free_text_list (GSList *text_list);
 
 /* Alarms */
 
-typedef enum {
-	CAL_COMPONENT_ALARM_NONE,
-	CAL_COMPONENT_ALARM_AUDIO,
-	CAL_COMPONENT_ALARM_DISPLAY,
-	CAL_COMPONENT_ALARM_EMAIL,
-	CAL_COMPONENT_ALARM_PROCEDURE,
-	CAL_COMPONENT_ALARM_UNKNOWN
-} CalComponentAlarmAction;
+/* Opaque structure used to represent alarm subcomponents */
+typedef struct _CalComponentAlarm CalComponentAlarm;
 
-typedef enum {
-	CAL_COMPONENT_ALARM_TRIGGER_RELATIVE,
-	CAL_COMPONENT_ALARM_TRIGGER_ABSOLUTE
-} CalComponentAlarmTriggerType;
+/* An alarm occurrence, i.e. a trigger instance */
+typedef struct {
+	/* UID of the alarm that triggered */
+	const char *auid;
+
+	/* Trigger time, i.e. "5 minutes before the appointment" */
+	time_t trigger;
 
+	/* Actual event occurrence to which this trigger corresponds */
+	time_t occur;
+} CalAlarmInstance;
+
+/* Alarm trigger instances for a particular component */
+typedef struct {
+	/* The actual component */
+	CalComponent *comp;
+
+	/* List of CalAlarmInstance structures */
+	GSList *alarms;
+} CalComponentAlarms;
+
+/* Alarm types */
+typedef enum {
+	CAL_ALARM_NONE,
+	CAL_ALARM_AUDIO,
+	CAL_ALARM_DISPLAY,
+	CAL_ALARM_EMAIL,
+	CAL_ALARM_PROCEDURE,
+	CAL_ALARM_UNKNOWN
+} CalAlarmAction;
+
+/* Whether a trigger is relative to the start or end of an event occurrence, or
+ * whether it is specified to occur at an absolute time.
+ */
 typedef enum {
-	CAL_COMPONENT_ALARM_TRIGGER_RELATED_START,
-	CAL_COMPONENT_ALARM_TRIGGER_RELATED_END
-} CalComponentAlarmTriggerRelated;
+	CAL_ALARM_TRIGGER_NONE,
+	CAL_ALARM_TRIGGER_RELATIVE_START,
+	CAL_ALARM_TRIGGER_RELATIVE_END,
+	CAL_ALARM_TRIGGER_ABSOLUTE
+} CalAlarmTriggerType;
 
 typedef struct {
-	CalComponentAlarmTriggerType type;
+	CalAlarmTriggerType type;
 
 	union {
-		struct {
-			struct icaldurationtype duration;
-			CalComponentAlarmTriggerRelated related;
-		} relative;
-
-		struct icaltimetype absolute;
+		struct icaldurationtype rel_duration;
+		struct icaltimetype abs_time;
 	} u;
-} CalComponentAlarmTrigger;
+} CalAlarmTrigger;
 
 gboolean cal_component_has_alarms (CalComponent *comp);
 GList *cal_component_get_alarm_uids (CalComponent *comp);
@@ -300,12 +329,16 @@ CalComponentAlarm *cal_component_get_alarm (CalComponent *comp, const char *auid
 
 void cal_component_alarm_free (CalComponentAlarm *alarm);
 
-void cal_component_alarm_get_action (CalComponentAlarm *alarm, CalComponentAlarmAction *action);
-void cal_component_alarm_set_action (CalComponentAlarm *alarm, CalComponentAlarmAction action);
+void cal_component_alarms_free (CalComponentAlarms *alarms);
+
+const char *cal_component_alarm_get_uid (CalComponentAlarm *alarm);
+
+void cal_component_alarm_get_action (CalComponentAlarm *alarm, CalAlarmAction *action);
+void cal_component_alarm_set_action (CalComponentAlarm *alarm, CalAlarmAction action);
+
+void cal_component_alarm_get_trigger (CalComponentAlarm *alarm, CalAlarmTrigger *trigger);
+void cal_component_alarm_set_trigger (CalComponentAlarm *alarm, CalAlarmTrigger trigger);
 
-void cal_component_alarm_get_trigger (CalComponentAlarm *alarm, CalComponentAlarmTrigger **trigger);
-void cal_component_alarm_set_trigger (CalComponentAlarm *alarm, CalComponentAlarmTrigger *trigger);
-void cal_component_alarm_free_trigger (CalComponentAlarmTrigger *trigger);