[evolution-data-server] libecal: added CALOBJ_MOD_ONLY_THIS

[Patrick Ohly <pohly src gnome org>]

commit c54220339d9fda38d537e1f8cac3637403b362ab
Author: Patrick Ohly <patrick ohly intel com>
Date:   Thu May 12 09:29:16 2011 +0200

    libecal: added CALOBJ_MOD_ONLY_THIS
    
    The goal is to have an orthogonal API where each operation also
    has an inverse operation. Adding a detached recurrence was
    possible with e_cal_modify_object(), but removing it again
    wasn't without modifying the parent appointment.
    
    CALOBJ_MOD_ONLY_THIS in e_cal_remove_object_with_mod() provides
    that inverse operation by avoiding the modifications to the
    parent.
    
    The semantic in e_cal_modify_object(), the other call taking a
    CalObjModType, is unchanged. CALOBJ_MOD_ONLY_THIS is not valid there.
    
    Because not all backends reject CALOBJ_MOD_ONLY_THIS when they don't
    support it, a static capability CAL_STATIC_CAPABILITY_REMOVE_ONLY_THIS
    is added that must be checked first before using CALOBJ_MOD_ONLY_THIS.

 calendar/libecal/e-cal-util.h              |    2 +
 calendar/libecal/e-cal.c                   |   42 +++++++++++++++++++++++----
 calendar/libedata-cal/e-cal-backend-sync.c |    2 +-
 3 files changed, 38 insertions(+), 8 deletions(-)
---
diff --git a/calendar/libecal/e-cal-util.h b/calendar/libecal/e-cal-util.h
index 8abf0ad..79dfed5 100644
--- a/calendar/libecal/e-cal-util.h
+++ b/calendar/libecal/e-cal-util.h
@@ -46,6 +46,7 @@ typedef enum {
 	CALOBJ_MOD_THIS          = 1 << 0,
 	CALOBJ_MOD_THISANDPRIOR  = 1 << 1,
 	CALOBJ_MOD_THISANDFUTURE = 1 << 2,
+	CALOBJ_MOD_ONLY_THIS     = 1 << 3,
 	CALOBJ_MOD_ALL           = 0x07
 } CalObjModType;
 
@@ -110,6 +111,7 @@ gboolean e_cal_util_event_dates_match (icalcomponent *icalcomp1, icalcomponent *
 #define CAL_STATIC_CAPABILITY_NO_THISANDFUTURE            "no-thisandfuture"
 #define CAL_STATIC_CAPABILITY_NO_THISANDPRIOR             "no-thisandprior"
 #define CAL_STATIC_CAPABILITY_NO_TRANSPARENCY             "no-transparency"
+#define CAL_STATIC_CAPABILITY_REMOVE_ONLY_THIS            "remove-only-this"
 #define CAL_STATIC_CAPABILITY_ONE_ALARM_ONLY              "one-alarm-only"
 #define CAL_STATIC_CAPABILITY_ORGANIZER_MUST_ATTEND       "organizer-must-attend"
 #define CAL_STATIC_CAPABILITY_ORGANIZER_NOT_EMAIL_ADDRESS "organizer-not-email-address"
diff --git a/calendar/libecal/e-cal.c b/calendar/libecal/e-cal.c
index be2bcc3..b4e64ff 100644
--- a/calendar/libecal/e-cal.c
+++ b/calendar/libecal/e-cal.c
@@ -3587,6 +3587,8 @@ e_cal_get_alarms_for_object (ECal *ecal, const ECalComponentId *id,
  * update internal information about the alarm be discarded, or, like
  * the file backend does, ignore the operation.
  *
+ * CALOBJ_MOD_ONLY_THIS is not supported in this call.
+ *
  * Returns: TRUE if the operation was successful, FALSE otherwise.
  *
  * Deprecated: 3.2: Use e_cal_client_discard_alarm_sync() instead.
@@ -3889,19 +3891,45 @@ e_cal_modify_object (ECal *ecal, icalcomponent *icalcomp, CalObjModType mod, GEr
 /**
  * e_cal_remove_object_with_mod:
  * @ecal: A calendar client.
- * @uid: UID og the object to remove.
+ * @uid: UID of the object to remove.
  * @rid: Recurrence ID of the specific recurrence to remove.
  * @mod: Type of removal.
  * @error: Placeholder for error information.
  *
  * This function allows the removal of instances of a recurrent
- * appointment. By using a combination of the @uid, @rid and @mod
- * arguments, you can remove specific instances. If what you want
- * is to remove all instances, use e_cal_remove_object instead.
+ * appointment. If what you want is to remove all instances, use
+ * e_cal_remove_object instead.
+ *
+ * By using a combination of the @uid, @rid and @mod arguments, you
+ * can remove specific instances. @uid is mandatory.  Empty or NULL
+ * @rid selects the parent appointment (the one with the recurrence
+ * rule). A non-empty @rid selects the recurrence at the time specified
+ * in @rid, using the same time zone as the parent appointment's start
+ * time.
  *
- * If not all instances are removed, the client will get a "obj_modified"
- * signal, while it will get a "obj_removed" signal when all instances
- * are removed.
+ * The exact semantic then depends on @mod. CALOBJ_MOD_THIS,
+ * CALOBJ_MOD_THISANDPRIOR, CALOBJ_MOD_THISANDFUTURE and
+ * CALOBJ_MOD_ALL ensure that the event does not recur at the selected
+ * instance(s). This is done by removing any detached recurrence
+ * matching the selection criteria and modifying the parent
+ * appointment (adding EXDATE, adjusting recurrence rules, etc.).  It
+ * is not an error if @uid+ rid do not match an existing instance.
+ *
+ * If not all instances are removed, the client will get a
+ * "obj_modified" signal for the parent appointment, while it will get
+ * an "obj_removed" signal when all instances are removed.
+ *
+ * CALOBJ_MOD_ONLY_THIS changes the semantic of CALOBJ_MOD_THIS: @uid
+ * and @rid must select an existing instance. That instance is
+ * removed without modifying the parent appointment. In other words,
+ * e_cal_remove_object_with_mod(CALOBJ_MOD_ONLY_THIS) is the inverse
+ * operation for adding a detached recurrence. The client is
+ * always sent an "obj_removed" signal.
+ *
+ * Note that not all backends support CALOBJ_MOD_ONLY_THIS. Check for
+ * the CAL_STATIC_CAPABILITY_REMOVE_ONLY_THIS capability before using
+ * it. Previous releases did not check consistently for unknown
+ * @mod values, using it with them may have had unexpected results.
  *
  * Returns: TRUE if the operation was successful, FALSE otherwise.
  *
diff --git a/calendar/libedata-cal/e-cal-backend-sync.c b/calendar/libedata-cal/e-cal-backend-sync.c
index 5c06864..baf2602 100644
--- a/calendar/libedata-cal/e-cal-backend-sync.c
+++ b/calendar/libedata-cal/e-cal-backend-sync.c
@@ -629,7 +629,7 @@ cal_backend_remove_object (ECalBackend *backend, EDataCal *cal, guint32 opid, GC
 	ECalComponentId compid;
 
 	compid.uid = (gchar *) uid;
-	compid.rid = (gchar *) (mod == CALOBJ_MOD_THIS ? rid : NULL);
+	compid.rid = (gchar *) ((mod == CALOBJ_MOD_THIS || mod == CALOBJ_MOD_ONLY_THIS) ? rid : NULL);
 
 	e_cal_backend_sync_remove_object (E_CAL_BACKEND_SYNC (backend), cal, cancellable, uid, rid, mod, &old_object, &new_object, &error);