pjs/calendar/base/public/calICalendar.idl

593 строки
24 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>
* Philipp Kewisch <mozilla@kewis.ch>
*
* 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;
interface calIOperation;
interface calIStatusObserver;
interface nsIDOMChromeWindow;
[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;
/**
* 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;
/**
* 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] 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.
*
* [nsresult] currentStatus The current error status of the calendar (transient).
*
* [calIItipTransport] itip.transport If the provider implements a custom calIItipTransport (transient)
* [nsIMsgIdentity] imip.identity If provided, this is the email identity used for
* 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.attachments.supported Supports attachments
* 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.alarms.popup.supported Supports popup alarms
*
* 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"];
*
* @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;
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.
*
* @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.
*/
[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 );
/* return a list of all calendars currently registered */
void getCalendars(out PRUint32 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?
*/
[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.
*/
[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 );
};