зеркало из https://github.com/mozilla/gecko-dev.git
444 строки
17 KiB
Plaintext
444 строки
17 KiB
Plaintext
/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
|
|
/* ***** BEGIN LICENSE BLOCK *****
|
|
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
|
|
*
|
|
* The contents of this file are subject to the Mozilla Public License Version
|
|
* 1.1 (the "License"); you may not use this file except in compliance with
|
|
* the License. You may obtain a copy of the License at
|
|
* http://www.mozilla.org/MPL/
|
|
*
|
|
* Software distributed under the License is distributed on an "AS IS" basis,
|
|
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
|
|
* for the specific language governing rights and limitations under the
|
|
* License.
|
|
*
|
|
* The Original Code is OEone Calendar Code, released October 31st, 2001.
|
|
*
|
|
* The Initial Developer of the Original Code is
|
|
* OEone Corporation.
|
|
* Portions created by the Initial Developer are Copyright (C) 2001
|
|
* the Initial Developer. All Rights Reserved.
|
|
*
|
|
* Contributor(s): Mostafa Hosseini <mostafah@oeone.com>
|
|
* Chris Charabaruk <ccharabaruk@meldstar.com>
|
|
* ArentJan Banck <ajbanck@planet.nl>
|
|
* Dan Mosedale <dan.mosedale@oracle.com>
|
|
* Vladimir Vukicevic <vladimir.vukicevic@oracle.com>
|
|
* Mike Shaver <shaver@off.net>
|
|
*
|
|
* Alternatively, the contents of this file may be used under the terms of
|
|
* either the GNU General Public License Version 2 or later (the "GPL"), or
|
|
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
|
|
* in which case the provisions of the GPL or the LGPL are applicable instead
|
|
* of those above. If you wish to allow use of your version of this file only
|
|
* under the terms of either the GPL or the LGPL, and not to allow others to
|
|
* use your version of this file under the terms of the MPL, indicate your
|
|
* decision by deleting the provisions above and replace them with the notice
|
|
* and other provisions required by the GPL or the LGPL. If you do not delete
|
|
* the provisions above, a recipient may use your version of this file under
|
|
* the terms of any one of the MPL, the GPL or the LGPL.
|
|
*
|
|
* ***** END LICENSE BLOCK ***** */
|
|
|
|
#include "nsISupports.idl"
|
|
|
|
// decls for stuff from other files
|
|
interface nsIURI;
|
|
interface calIItemBase;
|
|
interface nsIVariant;
|
|
interface nsISimpleEnumerator;
|
|
|
|
// forward decls for this file
|
|
interface calIObserver;
|
|
interface calIOperationListener;
|
|
interface calIRange;
|
|
interface calIDateTime;
|
|
|
|
[scriptable, uuid(74e685e4-d863-11d9-88f2-000b7d081f44)]
|
|
interface calICalendar : nsISupports
|
|
{
|
|
/**
|
|
* 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;
|
|
|
|
/**
|
|
* Setting this URI causes the calendar to be (re)loaded.
|
|
*/
|
|
attribute nsIURI uri;
|
|
|
|
/**
|
|
* Is this calendar read-only? Used by the UI to decide whether or not
|
|
* widgetry should allow editing.
|
|
*/
|
|
attribute boolean readOnly;
|
|
|
|
/**
|
|
* 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;
|
|
|
|
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
|
|
*
|
|
* - 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.
|
|
*/
|
|
void 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
|
|
*/
|
|
void adoptItem( in calIItemBase aItem, in calIOperationListener aListener );
|
|
|
|
/**
|
|
* modifyItem takes a modified mutable 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.
|
|
*
|
|
* @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
|
|
*
|
|
* 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
|
|
*/
|
|
void 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
|
|
*
|
|
* 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
|
|
*/
|
|
void 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.
|
|
*
|
|
* 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,..)
|
|
*/
|
|
void 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 occurence
|
|
* if they recur in the future or their last occurence in the past
|
|
* otherwise. Here's a presentation of the sort criteria using the
|
|
* time axis:
|
|
*
|
|
* -----(Last occurence of Event1)---(Last occurence of Event2)----(Now)----(Next occurence 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
|
|
* occurences, not just the initial recurring items. So if a
|
|
* getItems() call without ITEM_FILTER_CLASS_OCCURENCES 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.
|
|
*
|
|
*
|
|
* 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
|
|
*/
|
|
void getItems( in unsigned long aItemFilter, in unsigned long aCount,
|
|
in calIDateTime aRangeStart, in calIDateTime aRangeEndEx,
|
|
in calIOperationListener aListener );
|
|
|
|
/**
|
|
* Whether or not alarms for this calendar should be suppressed.
|
|
*/
|
|
attribute boolean suppressAlarms;
|
|
|
|
|
|
/**
|
|
* Refresh the datasource, and call the observers for any changes found.
|
|
* May call the onLoad function of the observers if the provider doesn't
|
|
* know the details of the changes.
|
|
*/
|
|
void 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.
|
|
*/
|
|
[scriptable, uuid(8285aa0b-594c-4f93-abe3-523df947e0ad)]
|
|
interface calICompositeCalendar : calICalendar
|
|
{
|
|
/**
|
|
* Add an already created calendar to the composite
|
|
*
|
|
* @param aCalendar the calendar to be added
|
|
*/
|
|
void addCalendar( in calICalendar aCalendar );
|
|
/**
|
|
* Remove a calendar from the composite
|
|
*
|
|
* @param aServer URI of the server to be removed
|
|
*/
|
|
void removeCalendar( in nsIURI aServer );
|
|
/**
|
|
* If a calendar for the given URI exists in the CompositeCalendar,
|
|
* return it; otherwise return null.
|
|
*
|
|
* @param aServer URI of the server whose calendar to return
|
|
* @return calendar for aServer, or null if none
|
|
*/
|
|
calICalendar getCalendar( in nsIURI aServer );
|
|
|
|
/**
|
|
* An enumerator of all calICalendars that make up this composite.
|
|
*/
|
|
readonly attribute nsISimpleEnumerator calendars;
|
|
|
|
/**
|
|
* 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;
|
|
};
|
|
|
|
/**
|
|
* Make a more general nsIObserverService2 and friends to support
|
|
* nsISupports data and use that instead?
|
|
*/
|
|
[scriptable, uuid(2953c9b2-2c73-11d9-80b6-00045ace3b8d)]
|
|
interface calIObserver : nsISupports
|
|
{
|
|
void onStartBatch();
|
|
void onEndBatch();
|
|
void onLoad();
|
|
void onAddItem( in calIItemBase aItem );
|
|
void onModifyItem( in calIItemBase aNewItem, in calIItemBase aOldItem );
|
|
void onDeleteItem( in calIItemBase aDeletedItem );
|
|
void onAlarm( in calIItemBase aAlarmItem );
|
|
void onError( in nsresult aErrNo, in AUTF8String aMessage );
|
|
};
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
[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 PRUint32 aCount,
|
|
[array, size_is(aCount), iid_is(aItemType)]
|
|
in nsQIResult aItems );
|
|
};
|