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.

3 files changed, 38 insertions, 8 deletions

diff --git a/calendar/libecal/e-cal-util.h b/calendar/libecal/e-cal-util.h
index 02e0660c5..539e7b799 100644
--- a/calendar/libecal/e-cal-util.h
+++ b/calendar/libecal/e-cal-util.h
@@ -47,6 +47,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;
 
@@ -111,6 +112,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 da18f591e..f2cab9270 100644
--- a/calendar/libecal/e-cal.c
+++ b/calendar/libecal/e-cal.c
@@ -3642,6 +3642,8 @@ e_cal_create_object (ECal *ecal, icalcomponent *icalcomp, gchar **uid, GError **
  * or a specific set of instances (CALOBJ_MOD_THISNADPRIOR and
  * CALOBJ_MOD_THISANDFUTURE).
  *
+ * CALOBJ_MOD_ONLY_THIS is not supported in this call.
+ *
  * Returns: TRUE if the operation was successful, FALSE otherwise.
  */
 gboolean
@@ -3674,19 +3676,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 8264719fb..514c99d9b 100644
--- a/calendar/libedata-cal/e-cal-backend-sync.c
+++ b/calendar/libedata-cal/e-cal-backend-sync.c
@@ -670,7 +670,7 @@ _e_cal_backend_remove_object (ECalBackend *backend, EDataCal *cal, EServerMethod
 		ECalComponentId *id = g_new0 (ECalComponentId, 1);
 		id->uid = g_strdup (uid);
 
-		if (mod == CALOBJ_MOD_THIS)
+		if (mod == CALOBJ_MOD_THIS || mod == CALOBJ_MOD_ONLY_THIS)
 			id->rid = g_strdup (rid);
 
 		if (!object)