Adding upstream version 1:115.7.0.upstream/1%115.7.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 151 insertions, 0 deletions

diff --git a/comm/calendar/base/public/calIChangeLog.idl b/comm/calendar/base/public/calIChangeLog.idl
new file mode 100644
index 0000000000..e49e42f61d
--- /dev/null
+++ b/comm/calendar/base/public/calIChangeLog.idl
@@ -0,0 +1,151 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+#include "calICalendar.idl"
+
+interface calIGenericOperationListener;
+interface calIOperation;
+
+/**
+ * Interface for managing offline flags in offline storage
+ * (calStorageCalendar), in particular from calICachedCalendar.
+ */
+[scriptable, uuid(36dc2c93-5851-40d2-9ba9-b1f6e682c75c)]
+interface calIOfflineStorage : calICalendar {
+    /**
+     * Mark the item of which the id is passed as parameter as new.
+     *
+     * @param aItem       the item to add
+     *
+     * @return {Promise<void>}
+     */
+    Promise addOfflineItem(in calIItemBase aItem);
+
+    /**
+     * Mark the item of which the id is passed as parameter as modified.
+     *
+     * @param aItem       the item to modify
+     *
+     * @return {Promise<void>}
+     */
+    Promise modifyOfflineItem(in calIItemBase aItem);
+
+    /**
+     * Mark the item of which the id is passed as parameter as deleted.
+     *
+     * @param aItem       the item to delete
+     * @return {Promise<void>}
+     */
+    Promise deleteOfflineItem(in calIItemBase aItem);
+
+    /**
+     * Retrieves the offline flag for the given item.
+     *
+     * @param aItem       the item to reset
+     * @return {Promise<number>}
+     */
+    Promise getItemOfflineFlag(in calIItemBase aItem);
+
+    /**
+     * Remove any offline flag from the item record.
+     *
+     * @param aItem       the item to reset
+     * @return {Promise<void>}
+     */
+    Promise resetItemOfflineFlag(in calIItemBase aItem);
+};
+
+/**
+ * Interface for synchronously working providers on storing items,
+ * e.g. storage, memory. All modifying commands return after the
+ * modification has been performed.
+ *
+ * @note
+ *   This interface is used in conjunction with changelog-based synchronization
+ *   and additionally offers storing meta-data for items for this purpose.
+ *   The meta data is stored as long as the corresponding items persist in
+ *   the calendar and automatically cleanup up once the item is deleted from
+ *   the calendar, but is not altered when an item is modified (modifyItem).
+ *   Meta data can be fetched/stored per (master) item, i.e. if you need to
+ *   store meta data for individual overridden items, you need to store it
+ *   along with the master item's meta data.
+ *   Finally, keep in mind that the meta data is "calendar local" and not
+ *   automatically transferred when storing the item on another calISyncWriteCalendar.
+ */
+[scriptable, uuid(651e137b-2f3a-4595-af89-da51b6a37f85)]
+interface calISyncWriteCalendar : calICalendar {
+    /**
+     * Adds or replaces meta data of an item.
+     *
+     * @param id    an item id
+     * @param value an arbitrary string
+     */
+    void setMetaData(in AUTF8String id,
+                     in AUTF8String value);
+
+    /**
+     * Deletes meta data of an item.
+     *
+     * @param id    an item id
+     */
+    void deleteMetaData(in AUTF8String id);
+
+    /**
+     * Gets meta data of an item or null if there's none or the item id is invalid.
+     *
+     * @param id    an item id
+     */
+    AUTF8String getMetaData(in AUTF8String id);
+
+    /**
+     * Gets all meta data IDs.
+     */
+    Array<AString> getAllMetaDataIds();
+
+    /**
+     * Gets all meta data values.
+     */
+    Array<AString> getAllMetaDataValues();
+};
+
+/**
+ * Calendar implementing this interface have improved means of replaying their
+ * changelog data. This could for example mean, that the provider can retrieve
+ * changes between now and the last sync.
+ *
+ * Not implementing this interface is perfectly valid for calendars, that need
+ * to do a full sync each time anyway (i.e ics)
+ */
+[scriptable, uuid(0bf4c6a2-b4c7-4cae-993a-4408d8bded3e)]
+interface calIChangeLog : nsISupports {
+
+    // To denote no offline flag, use null
+    const long OFFLINE_FLAG_CREATED_RECORD = 1;
+    const long OFFLINE_FLAG_MODIFIED_RECORD = 2;
+    const long OFFLINE_FLAG_DELETED_RECORD = 4;
+
+    /**
+     * Enable the changelog calendar to retrieve offline data right after instantiation.
+     */
+    attribute calISyncWriteCalendar offlineStorage;
+
+    /**
+     * Resets the changelog. This is used if the cache should be refreshed.
+     */
+    void resetLog();
+
+    /**
+     * Instructs the calendar to replay remote changes into the above offlineStorage
+     * calendar. The calendar itself is responsible for storing anything needed
+     * to keep track of what items need updating.
+     *
+     * TODO: We might reconsider to replay on calICalendar,
+     *       but this complicates implementing this interface
+     *       enormously for providers.
+     *
+     * @param aDestination      The calendar to sync changes into
+     * @param aListener         The listener to notify when the operation completes.
+     */
+    calIOperation replayChangesOn(in calIGenericOperationListener aListener);
+};