/* -*- 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 * Chris Charabaruk * ArentJan Banck * Dan Mosedale * Vladimir Vukicevic * Mike Shaver * * 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 { /** * 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; /** * Setting this URI causes the calendar to be (re)loaded. * This is not an unique indentifier! It is also not unchangeable. Don't * use it to indentify a calandar, 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; /** * 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; /** * Whether or not this provider requires us to send iTIP invitations when * inviting attendees to an event. Some providers (ex: WCAP) handle * invitations internally without the use of iTIP invitations, so those * providers return false here. */ readonly attribute boolean sendItipInvitations; /** * 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( in calICalendar aCalendar ); void onAddItem( in calIItemBase aItem ); void onModifyItem( in calIItemBase aNewItem, in calIItemBase aOldItem ); void onDeleteItem( in calIItemBase aDeletedItem ); 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 ); };