[evolution-data-server/pohly-gnome-2-32: 4/10] libecal: added CALOBJ_MOD_ONLY_THIS

[Patrick Ohly <pohly src gnome org>]

commit 7680b8e1ce0370c1b2f183c87024e51d0d5d7cb2
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.
    
    merge: MOD_ONLY_THIS

 calendar/libecal/e-cal-util.h |    2 +
 calendar/libecal/e-cal.c      |   42 ++++++++++++++++++++++++++++++++++------
 2 files changed, 37 insertions(+), 7 deletions(-)
---
diff --git a/calendar/libecal/e-cal-util.h b/calendar/libecal/e-cal-util.h
index 02e0660..539e7b7 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 da18f59..f2cab92 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.
  */