summaryrefslogtreecommitdiffstats
path: root/comm/calendar/base/public/calIChangeLog.idl
diff options
context:
space:
mode:
Diffstat (limited to 'comm/calendar/base/public/calIChangeLog.idl')
-rw-r--r--comm/calendar/base/public/calIChangeLog.idl151
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);
+};