thunderbird-dev 1:52.8.0-1~deb8u1 / usr / share / idl / thunderbird / calICalendar.idl

/* -*- 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;
interface nsISimpleEnumerator;

// forward decls for this file
interface calICalendarACLManager;
interface calICalendarACLEntry;
interface calIObserver;
interface calIOperationListener;
interface calIRange;
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 );

  /**
   * The following five "Item" functions are all asynchronous, and return
   * their results to a calIOperationListener object.
   *
   */

  /**
   * addItem adds the given calIItemBase to the calendar.
   *
   * @param aItem       item to add
   * @param aListener   where to call back the results
   * @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 results of the operation are reported through an
   * onOperationComplete call on the listener, with the following
   * parameters:
   *
   * - aOperationType: calIOperationListener::ADD
   * - aId: the ID of the newly added item
   * - aDetail: the calIItemBase corresponding to the immutable
   *            version of the newly added item
   *
   * If an item with a given ID already exists in the calendar,
   * onOperationComplete is called with an aStatus of NS_ERROR_XXXXX,
   * and aDetail set with the calIItemBase of the internal already
   * existing item.
   */
  calIOperation addItem(in calIItemBase aItem,
                        in calIOperationListener aListener);

  /**
   * 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
   */
  calIOperation adoptItem(in calIItemBase aItem,
                          in calIOperationListener aListener);

  /**
   * modifyItem takes a modified item and modifies the
   * calendar's internal version of the item to match.  The item is
   * expected to have an ID that already exists in the calendar; if it
   * doesn't, or there is no id, onOperationComplete is called with a
   * status of NS_ERROR_XXXXX.  If the item is immutable,
   * onOperationComplete is called with a status of 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), onOperationComplete is called with a status of NS_ERROR_XXXXX
   * and aDetail is set to the latest-version internal immutable item.
   *
   * 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
   * @param aListener   where to call back the results
   * @return            optional operation handle to track the operation
   *
   * The results of the operation are reported through an
   * onOperationComplete call on the listener, with the following
   * parameters:
   *
   * - aOperationType: calIOperationListener::MODIFY
   * - aId: the ID of the modified item
   * - aDetail: the calIItemBase corresponding to the newly-updated
   *            immutable version of the modified item
   */
  calIOperation modifyItem(in calIItemBase aNewItem,
                           in calIItemBase aOldItem,
                           in calIOperationListener aListener);

  /**
   * deleteItem takes an item that is to be deleted.  The item is
   * expected to have an ID that already exists in the calendar; if it
   * doesn't, or there is no id, onOperationComplete is called with
   * a status of NS_ERROR_XXXXX.
   *
   * @param aItem       item to delete
   * @param aListener   where to call back the results
   * @return            optional operation handle to track the operation
   *
   * The results of the operation are reported through an
   * onOperationComplete call on the listener, with the following
   * parameters:
   *
   * - aOperationType: calIOperationListener::DELETE
   * - aId: the ID of the deleted item
   * - aDetail: the calIItemBase corresponding to the immutable version
   *            of the deleted item
   */
  calIOperation deleteItem(in calIItemBase aItem,
                           in calIOperationListener aListener);

  /**
   * 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
   * @param aListener  listener to which this event will be called back.
   * @return           optional operation handle to track the operation
   *
   * The results of the operation are reported through the listener,
   * via zero or one onGetResult calls (with aCount set to 1)
   * followed by an onOperationComplete.
   *
   * The parameters to onOperationComplete will be:
   *
   * - aOperationType: calIOperationListener::GET
   * - aId: the ID of the requested item
   * - aDetail: null (? we can also pass the item back here as well,..)
   */
  calIOperation getItem(in string aId, in calIOperationListener aListener);

  /**
   * 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".
   * @param aListener   The results will be called back through this interface.
   * @return            optional operation handle to track the operation
   *
   *
   * The results of the operation are reported through the listener,
   * via zero or more onGetResult calls followed by an onOperationComplete.
   *
   * The parameters to onOperationComplete will be:
   *
   * - aOperationType: calIOperationListener::GET
   * - aId: null
   * - aDetail: null
   */
  calIOperation getItems(in unsigned long aItemFilter,
                         in unsigned long aCount,
                         in calIDateTime aRangeStart,
                         in calIDateTime aRangeEndEx,
                         in calIOperationListener aListener);

  /**
   * 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 */
  void getCalendars(out uint32_t count,
                    [array, size_is(count), retval] out calICalendar aCalendars);

  /**
   * 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();
  void onEndBatch();
  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 aCount    size of array returned, in items
   * @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,
                    in uint32_t aCount, 
                    [array, size_is(aCount), iid_is(aItemType)]  in nsQIResult aItems );
};