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, 605 insertions, 0 deletions

diff --git a/comm/calendar/base/public/calICalendar.idl b/comm/calendar/base/public/calICalendar.idl
new file mode 100644
index 0000000000..8366dbaf38
--- /dev/null
+++ b/comm/calendar/base/public/calICalendar.idl
@@ -0,0 +1,605 @@
+/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* 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 "nsISupports.idl"
+
+// decls for stuff from other files
+interface nsIURI;
+interface calIItemBase;
+interface nsIVariant;
+
+// forward decls for this file
+interface calICalendarACLManager;
+interface calICalendarACLEntry;
+interface calIObserver;
+interface calIOperationListener;
+interface calIRange;
+interface calISchedulingSupport;
+interface calIDateTime;
+interface calIOperation;
+interface calIStatusObserver;
+interface nsIDOMChromeWindow;
+
+
+[scriptable, uuid(b18782c0-6557-4e8e-931d-4bf052f0a31e)]
+interface calICalendar : nsISupports
+{
+  /**
+   * Unique ID of this calendar. Only the calendar manager is allowed to set
+   * this attribute. For everybody else, it should be considered to be
+   * read-only.
+   * The id is null for unregistered calendars.
+   */
+  attribute AUTF8String id;
+
+  /**
+   * Name of the calendar
+   * Notes: Can only be set after the calendar is registered with the calendar manager.
+   */
+  attribute AUTF8String name;
+
+  /**
+   * Type of the calendar
+   *   'memory', 'storage', 'caldav', etc
+   */
+  readonly attribute AUTF8String type;
+
+  /**
+   * If this calendar is provided by an extension, this attribute should return
+   * the extension's id, otherwise null.
+   */
+  readonly attribute AString providerID;
+
+  /**
+   * Returns the acl manager for the calendar, based on the "aclManagerClass"
+   * property. If this property is not defined, the default manager is used
+   */
+  readonly attribute calICalendarACLManager aclManager;
+
+  /**
+   * Returns the acl entry associated to the calendar.
+   */
+  readonly attribute calICalendarACLEntry aclEntry;
+
+  /**
+   * Multiple calendar instances may be composited, logically acting as a
+   * single calendar, e.g. for caching puorposing.
+   * This attribute determines the topmost calendar that returned items should
+   * belong to. If the current instance is the topmost calendar, then it should
+   * be returned directly.
+   *
+   * @see calIItemBase::calendar
+   */
+  attribute calICalendar superCalendar;
+
+  /**
+   * Setting this URI causes the calendar to be (re)loaded.
+   * This is not an unique identifier! It is also not unchangeable. Don't
+   * use it to identify a calendar, use the id attribute for that purpose.
+   */
+  attribute nsIURI uri;
+
+  /**
+   * Is this calendar read-only?  Used by the UI to decide whether or not
+   * widgetry should allow editing.
+   */
+  attribute boolean readOnly;
+
+  /**
+   * Whether or not it makes sense to call refresh() on this calendar.
+   */
+  readonly attribute boolean canRefresh;
+
+  /**
+   * Setting this attribute to true will prevent the calendar to make calendar properties
+   * persistent, which is useful if you would like to set properties on unregistered
+   * calendar instances.
+   */
+  attribute boolean transientProperties;
+
+  /**
+   * Gets a calendar property.
+   * The call returns null in case the property is not known;
+   * callers should use a sensible default in that case.
+   *
+   * It's up to the provider where to store properties,
+   * e.g. on the server or in local prefs.
+   *
+   * Currently known properties are:
+   *   [boolean]  disabled
+   *   [boolean]  auto-enabled       If true, the calendar will be enabled on next startup.
+   *   [boolean]  force-disabled     If true, the calendar cannot be enabled (transient).
+   *   [boolean]  calendar-main-in-composite
+   *   [string]   name
+   *   [boolean]  readOnly
+   *   [boolean]  requiresNetwork    If false, the calendar does not require
+   *                                   network access at all. This is mainy used
+   *                                   as a UI hint.
+   *   [boolean]  suppressAlarms     If true, alarms of this calendar are not minded.
+   *   [boolean]  cache.supported    If true, the calendar should to be cached,
+   *                                   e.g. this generally applies to network calendars;
+   *                                   default is true (if not present).
+   *   [boolean]  cache.enabled      If true, the calendar is cached; default is false.
+   *   [boolean]  cache.always       If true, the cache will always be enabled
+   *                                   and the user cannot turn it off. For
+   *                                   backward compatibility, return true for
+   *                                   cache.enabled too.
+   *
+   *   [nsresult] currentStatus      The current error status of the calendar (transient).
+   *
+   *   [calIItipTransport] itip.transport    If the provider implements a custom calIItipTransport (transient)
+   *                                           If null, then Email Scheduling will effectively be
+   *                                           disabled. This means for example, the calendar will
+   *                                           not show up in the list of calendars to store an
+   *                                           invitation in.
+   *   [boolean] itip.disableRevisionChecks  If true, the iTIP handling code disables revision checks
+   *                                            against SEQUENCE and DTSTAMP, and will never reject an
+   *                                            iTIP message as outdated
+   *   [nsIMsgIdentity] imip.identity        If provided, this is the email identity used for
+   *                                           scheduling purposes
+   *   [boolean] imip.identity.disabled      If true, this calendar doesn't support switching imip
+   *                                           identities. This for example means that the
+   *                                           dropdown of identities will not be shown in the
+   *                                           calendar properties dialog. (transient)
+   *                                           scheduling purposes
+   *   [nsIMsgAccount] imip.account          If provided, this is the email account used for
+   *                                           scheduling purposes
+   *   [string] imip.identity.key            If provided, this is the email internal identity key used to
+   *                                           get the above
+   *
+   *   [string]   organizerId        If provided, this is the preset organizer id on creating
+   *                                   scheduling appointments (transient)
+   *   [string]   organizerCN        If provided, this is the preset organizer common name on creating
+   *                                   scheduling appointments (transient)
+   *
+   * The following calendar capabilities can be used to inform the UI or backend
+   * that certain features are not supported. If not otherwise mentioned, not
+   * specifying these capabilities assumes a default value of true
+   *   capabilities.alarms.popup.supported              Supports popup alarms
+   *   capabilities.alarms.oninviations.supported       Supports alarms on inviations.
+   *   capabilities.alarms.maxCount                     Maximum number of alarms supported per event
+   *   capabilities.attachments.supported               Supports attachments
+   *   capabilities.categories.maxCount                 Maximum number of supported categories.
+   *                                                      -1 means infinite, 0 means disabled.
+   *   capabilities.privacy.supported                   Supports a privacy state
+   *   capabilities.priority.supported                  Supports the priority field
+   *   capabilities.events.supported                    Supports tasks
+   *   capabilities.tasks.supported                     Supports events
+   *   capabilities.timezones.floating.supported        Supports local time
+   *   capabilities.timezones.UTC.supported             Supports UTC/GMT timezone
+   *   capabilities.autoschedule.supported              Supports caldav schedule properties in
+   *                                                      icalendar (SCHEDULE-AGENT, SCHEDULE-STATUS...)
+   *
+   * The following capabilities are used to restrict the values for specific
+   * fields. An array should be specified with the values, the default
+   * values are specified here. Extensions using this need to take care of
+   * adding any UI elements needed in an overlay. To make sure the correct
+   * elements are shown, those elements should additionally specify an attribute
+   * "provider", with the type of the provider.
+   *
+   *   capabilities.privacy.values = ["PUBLIC", "CONFIDENTIAL", "PRIVATE"];
+   *
+   * The following special capability disables rewriting the WWW-Authenticate
+   * header on HTTP requests to include the calendar name. The default value
+   * is false, i.e rewriting is NOT disabled.
+   *
+   *   capabilities.realmrewrite.disabled = false
+   *
+   * The following capability describes if the calendar can be permanently
+   * deleted, or just unsubscribed. If this property is not specified, then
+   * only unsubscribing is allowed. If an empty array is specified, neither
+   * deleting nor unsubscribing is presented in the UI.
+   *
+   *   capabilities.removeModes = ["delete", "unsubscribe"]
+   *
+   * @param aName property name
+   * @return value (string, integer and boolean values are supported),
+   *               else null
+   */
+  nsIVariant getProperty(in AUTF8String aName);
+
+  /**
+   * Sets a calendar property.
+   * This will (only) cause a notification onPropertyChanged() in case
+   * the value has changed.
+   *
+   * It's up to the provider where to store properties,
+   * e.g. on the server or in local prefs.
+   *
+   * @param aName property name
+   * @param aValue value
+   *               (string, integer and boolean values are supported)
+   */
+  void setProperty(in AUTF8String aName, in nsIVariant aValue);
+
+  /**
+   * Deletes a calendar property.
+   *
+   * It's up to the provider where to store properties,
+   * e.g. on the server or in local prefs.
+   *
+   * @param aName property name
+   */
+  void deleteProperty(in AUTF8String aName);
+
+  /**
+   * In combination with the other parameters to getItems(), these
+   * constants provide for a very basic filtering mechanisms for use
+   * in getting and observing items.  At some point fairly soon, we're
+   * going to need to generalize this mechanism significantly (so we
+   * can allow boolean logic, categories, etc.).
+   *
+   * When adding item filters (bits which, when not set to 1, reduce the
+   * scope of the results), use bit positions <= 15, so that
+   * ITEM_FILTER_ALL_ITEMS remains compatible for components that have the
+   * constant compiled in.
+   *
+   * XXX the naming here is questionable; adding a filter (setting a bit, in
+   * this case) usually _reduces_ the set of items that pass the set of
+   * filters, rather than adding to it.
+   */
+  const unsigned long ITEM_FILTER_COMPLETED_YES = 1 << 0;
+  const unsigned long ITEM_FILTER_COMPLETED_NO = 1 << 1;
+  const unsigned long ITEM_FILTER_COMPLETED_ALL = (ITEM_FILTER_COMPLETED_YES |
+                                                   ITEM_FILTER_COMPLETED_NO);
+
+  const unsigned long ITEM_FILTER_TYPE_TODO = 1 << 2;
+  const unsigned long ITEM_FILTER_TYPE_EVENT = 1 << 3;
+  const unsigned long ITEM_FILTER_TYPE_JOURNAL = 1 << 4;
+  const unsigned long ITEM_FILTER_TYPE_ALL = (ITEM_FILTER_TYPE_TODO |
+                                              ITEM_FILTER_TYPE_EVENT |
+                                              ITEM_FILTER_TYPE_JOURNAL);
+
+  const unsigned long ITEM_FILTER_ALL_ITEMS = 0xFFFF;
+
+  /**
+   * If set, return calIItemBase occurrences for all the appropriate instances,
+   * as determined by an item's recurrenceInfo.  All of these occurrences will
+   * have their parentItem set to the recurrence parent.  If not set, will
+   * return only calIItemBase parent items.
+   */
+  const unsigned long ITEM_FILTER_CLASS_OCCURRENCES = 1 << 16;
+
+  /**
+   * Scope: Attendee
+   * Filter items that correspond to an invitation from another
+   * user and the current user has not replied to it yet.
+   */
+  const unsigned long ITEM_FILTER_REQUEST_NEEDS_ACTION = 1 << 17;
+
+  /**
+   * Flags for items that have been created, modified or deleted while
+   * offline.
+   * ITEM_FILTER_OFFLINE_DELETED is a particular case in that elements *must*
+   * be excluded from searches when not specified in the filter mask.
+   */
+  const unsigned long ITEM_FILTER_OFFLINE_CREATED = 1 << 29;
+  const unsigned long ITEM_FILTER_OFFLINE_MODIFIED = 1 << 30;
+  const unsigned long ITEM_FILTER_OFFLINE_DELETED = 1 << 31;
+
+  void addObserver( in calIObserver observer );
+  void removeObserver( in calIObserver observer );
+
+  /**
+   * supportsScheduling indicates whether the calendar implements the
+   * calISchedulingSupport interface.
+   */
+  readonly attribute boolean supportsScheduling;
+
+  /**
+   * getSchedulingSupport provides a calISchedulingSupport implementation for
+   * calendars that support it.
+   */
+  calISchedulingSupport getSchedulingSupport();
+
+  /**
+   * addItem adds the given calIItemBase to the calendar.
+   *
+   * @param aItem       item to add
+   * @return            optional operation handle to track the operation
+   *
+   * - If aItem already has an ID, that ID is used when adding.
+   * - If aItem is mutable and has no ID, the calendar is expected
+   *   to generate an ID for the item.
+   * - If aItem is immutable and has no ID, an error is thrown.
+   *
+   * The result of the operation is the calIItemBase corresponding to the
+   * immutable version of the newly added item.
+   *
+   * If an item with a given ID already exists in the calendar, the Promise is
+   * rejected with a NS_ERROR_XXXXX error.
+   *
+   * @return {Promise<calIItemBase>}
+   */
+  Promise addItem(in calIItemBase aItem);
+
+  /**
+   * adoptItem adds the given calIItemBase to the calendar, but doesn't
+   * clone it. It adopts the item as-is. This is generally for use in
+   * performance-critical situations where there is no danger of the caller
+   * using the item after making the call.
+   *
+   * @see addItem
+   *
+   * @return {Promise<calIItemBase>}
+   */
+  Promise adoptItem(in calIItemBase aItem);
+
+  /**
+   * modifyItem takes a modified item and modifies the
+   * calendar's internal version of the item to match. The item is expected to
+   * be mutable and have an ID that already exists in the calendar. If it does
+   * not, the Promise is rejected with NS_ERROR_XXXXX.
+   *
+   * If the generation of the given aNewItem does not match the generation
+   * of the internal item (indicating that someone else modified the
+   * item), the Promise is rejected with NS_ERROR_XXXXX.
+   *
+   * If you would like to disable revision checks, pass null as aOldItem. This
+   * will overwrite the item on the server.
+   *
+   * @param aNewItem    new version to replace the old one
+   * @param aOldItem    caller's view of the item to be changed, as it is now
+   * @return {Promise<calIItemBase>} the newly-updated immutable version of
+   *                                 the modified item.
+   *
+   */
+  Promise modifyItem(in calIItemBase aNewItem, in calIItemBase aOldItem);
+
+  /**
+   * Deletes an item. The item is expected to have an ID that already exists in
+   * the calendar.
+   *
+   * @param aItem            item to delete
+   * @return {Promise<void>} optional operation handle to track the operation
+   */
+  Promise deleteItem(in calIItemBase aItem);
+
+  /**
+   * Get a single event.  The event will be typed as one of the subclasses
+   * of calIItemBase (whichever concrete type is most appropriate).
+   *
+   * @param aId                           UID of the event
+   * @return {Promise<calIItemBase|null>} A Promise that is resolved with the item if found.
+   */
+  Promise getItem(in string aId);
+
+  /**
+   * XXX As mentioned above, this method isn't suitably general.  It's just
+   * placeholder until it gets supplanted by something more SQL or RDF-like.
+   *
+   *   Ordering: This method is currently guaranteed to return lists ordered
+   *   as follows to make for the least amount of pain when
+   *   migrating existing frontend code:
+   *
+   *     The events are sorted based on the order of their next occurrence
+   *     if they recur in the future or their last occurrence in the past
+   *     otherwise.  Here's a presentation of the sort criteria using the
+   *     time axis:
+   *
+   *     -----(Last occurrence of Event1)---(Last occurrence of Event2)----(Now)----(Next occurrence of Event3)---->
+   *
+   *     (Note that Event1 and Event2 will not recur in the future.)
+   *
+   *   We should probably be able get rid of this ordering constraint
+   *   at some point in the future.
+   *
+   * Note that the range is intended to act as a mask on the
+   * occurrences, not just the initial recurring items.  So if a
+   * getItems() call without ITEM_FILTER_CLASS_occurrenceS is made, all
+   * events and todos which have occurrences inside the range should
+   * be returned, even if some of those events or todos themselves
+   * live outside the range.
+   *
+   * @param aItemFilter ITEM_FILTER flags, or-ed together
+   * @param aCount      Maximum number of items to return, or 0 for
+   *                    an unbounded query.
+   * @param aRangeStart Items starting at this time or after should be
+   *                    returned.  If invalid, assume "since the beginning
+   *                    of time".
+   * @param aRangeEndEx Items starting before (not including) aRangeEndEx should be
+   *                    returned.  If null, assume "until the end of time".
+   * @return {ReadableStream<calIItemBase>}
+   */
+   jsval getItems(in unsigned long aItemFilter,
+                  in unsigned long aCount,
+                  in calIDateTime aRangeStart,
+                  in calIDateTime aRangeEndEx);
+
+  /**
+   * Similar to getItems() but returns all results in a single array.
+   * @param aItemFilter ITEM_FILTER flags, or-ed together
+   * @param aCount      Maximum number of items to return, or 0 for
+   *                    an unbounded query.
+   * @param aRangeStart Items starting at this time or after should be
+   *                    returned.  If invalid, assume "since the beginning
+   *                    of time".
+   * @param aRangeEndEx Items starting before (not including) aRangeEndEx should be
+   *                    returned.  If null, assume "until the end of time".
+   * @return {Promise<calIItemBase[]>}
+   */
+  Promise getItemsAsArray(in unsigned long aItemFilter,
+                          in unsigned long aCount,
+                          in calIDateTime aRangeStart,
+                          in calIDateTime aRangeEndEx);
+
+  /**
+   * Refresh the datasource, and call the observers for any changes found.
+   * If the provider doesn't know the details of the changes it must call
+   * onLoad on its observers.
+   *
+   * @return            optional operation handle to track the operation
+   */
+  calIOperation refresh();
+
+  /**
+   * Turn on batch mode. Observers will get a notification of this.
+   * They will still get notified for every individual change, but they are
+   * free to ignore those notifications.
+   * Use this when a lot of changes are about to happen, and it would be
+   * useless to refresh the display (or the backend store) for every change.
+   * Caller must make sure to also call endBatchMode. Make sure all errors
+   * are caught!
+   */
+  void startBatch();
+
+  /**
+   * Turn off batch mode.
+   */
+  void endBatch();
+};
+
+/**
+ * Used to allow multiple calendars (eg work and home) to be easily queried
+ * and displayed as a single unit. All calendars are referenced by ID, i.e.
+ * calendars need to have an ID when being added.
+ */
+[scriptable, uuid(6748fa00-79b5-4728-84f3-20dd47e0b031)]
+interface calICompositeCalendar : calICalendar
+{
+  /**
+   * Adds a calendar to the composite, if not already part of it.
+   *
+   * @param aCalendar the calendar to be added
+   */
+  void addCalendar(in calICalendar aCalendar);
+
+  /**
+   * Remove a calendar from the composite
+   *
+   * @param aCalendar the calendar to be removed
+   */
+  void removeCalendar(in calICalendar aCalendar);
+
+  /**
+   * If a calendar for the given ID exists in the CompositeCalendar,
+   * return it; otherwise return null.
+   *
+   * @param aId id of calendar
+   * @return calendar, or null if none
+   */
+  calICalendar getCalendarById(in AUTF8String aId);
+
+  /* return a list of all calendars currently registered */
+  Array<calICalendar> getCalendars();
+
+  /**
+   * In order for addItem() to be called on this object, it is first necessary
+   * to set this attribute to specify which underlying calendar the item is
+   * to be added to.
+   */
+  attribute calICalendar defaultCalendar;
+
+  /**
+   * If set, the composite will initialize itself from calICalendarManager
+   * prefs keyed off of the provided prefPrefix, and update those prefs to
+   * track changes in calendar membership and default calendar.
+   */
+  attribute ACString prefPrefix;
+
+  /**
+   * If returns true there is a process running that needs to displayed
+   * by the statusObserver
+   */
+  readonly attribute boolean statusDisplayed;
+
+  /**
+   * Sets a statusobserver for status notifications like startMeteors() and StopMeteors().
+   */
+  void setStatusObserver(in calIStatusObserver aStatusObserver, in nsIDOMChromeWindow aWindow);
+};
+
+/**
+ * Make a more general nsIObserverService2 and friends to support
+ * nsISupports data and use that instead?
+ *
+ * NOTE: When adding methods here, please also add them in calUtils.jsm's
+ * createAdapter() method.
+ */
+[scriptable, uuid(2953c9b2-2c73-11d9-80b6-00045ace3b8d)]
+interface calIObserver : nsISupports
+{
+  void onStartBatch(in calICalendar aCalendar);
+  void onEndBatch(in calICalendar aCalendar);
+  void onLoad( in calICalendar aCalendar );
+  void onAddItem( in calIItemBase aItem );
+  void onModifyItem( in calIItemBase aNewItem, in calIItemBase aOldItem );
+  void onDeleteItem( in calIItemBase aDeletedItem );
+  void onError( in calICalendar aCalendar, in nsresult aErrNo, in AUTF8String aMessage );
+
+  /// Called after a property is changed.
+  void onPropertyChanged(in calICalendar aCalendar,
+                         in AUTF8String aName,
+                         in nsIVariant aValue,
+                         in nsIVariant aOldValue);
+
+  /// Called before the property is deleted.
+  void onPropertyDeleting(in calICalendar aCalendar,
+                          in AUTF8String aName);
+};
+
+/**
+ * calICompositeObserver interface adds things to observe changes to
+ * a calICompositeCalendar
+ */
+[scriptable, uuid(a3584c92-b8eb-4aa8-a638-e46a2e11d6a9)]
+interface calICompositeObserver : calIObserver
+{
+  void onCalendarAdded( in calICalendar aCalendar );
+  void onCalendarRemoved( in calICalendar aCalendar );
+  void onDefaultCalendarChanged( in calICalendar aNewDefaultCalendar );
+};
+
+/**
+ * Async operations are called back via this interface.  If you know that your
+ * object is not going to get called back for either of these methods, having
+ * them return NS_ERROR_NOT_IMPLEMENTED is reasonable.
+ *
+ * NOTE: When adding methods here, please also add them in calUtils.jsm's
+ * createAdapter() method.
+ */
+[scriptable, uuid(ed3d87d8-2c77-11d9-8f5f-00045ace3b8d)]
+interface calIOperationListener : nsISupports
+{
+  /**
+   * For add, modify, and delete.
+   *
+   * @param aCalendar       the calICalendar on which the operation took place
+   * @param aStatus         status code summarizing what happened
+   * @param aOperationType  type of operation that was completed
+   * @param aId             UUID of element that was changed
+   * @param aDetail         not yet fully specified.  If aStatus is an error
+   *                        result, this will probably be an extended error
+   *                        string (eg one returned by a server).
+   */
+  void onOperationComplete(in calICalendar aCalendar,
+                           in nsresult aStatus,
+                           in unsigned long aOperationType,
+                           in string aId,
+                           in nsIVariant aDetail);
+  const unsigned long ADD = 1;
+  const unsigned long MODIFY = 2;
+  const unsigned long DELETE = 3;
+  const unsigned long GET = 4;
+
+  /**
+   * For getItem and getItems.
+   *
+   * @param aStatus   status code summarizing what happened.
+   * @param aItemType type of interface returned in the array (@see
+   *                  calICalendar::GetItems).
+   * @param aDetail   not yet fully specified.  If aStatus is an error
+   *                  result, this will probably be an extended error
+   *                  string (eg one returned by a server).
+   * @param aItems    array of immutable items
+   *
+   * Multiple onGetResults might be called
+   */
+  void onGetResult(in calICalendar aCalendar,
+                   in nsresult aStatus,
+                   in nsIIDRef aItemType,
+                   in nsIVariant aDetail,
+                   [iid_is(aItemType)] in Array<nsQIResult> aItems);
+};