From 8d96fe16f15f653d0809603ccaecd677e5708d8d Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Mon, 18 Dec 2000 23:47:52 +0000 Subject: Alarm instance generation support for the Wombat. 2000-12-18 Federico Mena Quintero 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 --- help/devel/ChangeLog | 12 +++++++ help/devel/calendar/Makefile.am | 1 + help/devel/calendar/alarm-generation.sgml | 54 +++++++++++++++++++++++++++++ help/devel/calendar/evolution-calendar.sgml | 1 + help/devel/evolution-devel-guide.sgml | 1 + 5 files changed, 69 insertions(+) create mode 100644 help/devel/calendar/alarm-generation.sgml (limited to 'help') diff --git a/help/devel/ChangeLog b/help/devel/ChangeLog index f536dde88d..85b7341bf0 100644 --- a/help/devel/ChangeLog +++ b/help/devel/ChangeLog @@ -1,3 +1,15 @@ +2000-12-18 Federico Mena Quintero + + * 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 * calendar/Makefile.am (EXTRA_DIST): make it public-reference.sgml diff --git a/help/devel/calendar/Makefile.am b/help/devel/calendar/Makefile.am index 66c3436d59..207672f303 100644 --- a/help/devel/calendar/Makefile.am +++ b/help/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/help/devel/calendar/alarm-generation.sgml b/help/devel/calendar/alarm-generation.sgml new file mode 100644 index 0000000000..60bc78343e --- /dev/null +++ b/help/devel/calendar/alarm-generation.sgml @@ -0,0 +1,54 @@ + + How the Wombat generates alarm instances + + + 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. + + + + What makes up an alarm trigger + + + 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. + + + + 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. + + + + + Generating trigger instances + + + + + + + + diff --git a/help/devel/calendar/evolution-calendar.sgml b/help/devel/calendar/evolution-calendar.sgml index 82015689ec..019fef9ea4 100644 --- a/help/devel/calendar/evolution-calendar.sgml +++ b/help/devel/calendar/evolution-calendar.sgml @@ -41,6 +41,7 @@ &calendar-architecture; + &calendar-alarm-generation;