diff options
Diffstat (limited to 'comm/calendar/base/public/calIRecurrenceInfo.idl')
| -rw-r--r-- | comm/calendar/base/public/calIRecurrenceInfo.idl | 184 |
1 files changed, 184 insertions, 0 deletions
diff --git a/comm/calendar/base/public/calIRecurrenceInfo.idl b/comm/calendar/base/public/calIRecurrenceInfo.idl new file mode 100644 index 0000000000..0e21298c47 --- /dev/null +++ b/comm/calendar/base/public/calIRecurrenceInfo.idl @@ -0,0 +1,184 @@ +/* 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" + +interface calIItemBase; +interface calIDateTime; + +interface calIRecurrenceItem; + +interface calIIcalProperty; + +[scriptable, uuid(8ca5db89-2583-4f0c-b845-4a6d2f229efd)] +interface calIRecurrenceInfo : nsISupports +{ + // returns true if this thing is able to be modified; + // if the item is not mutable, attempts to modify + // any data will throw CAL_ERROR_ITEM_IS_IMMUTABLE + readonly attribute boolean isMutable; + + // makes this item immutable + void makeImmutable(); + + // clone always returns a mutable event + calIRecurrenceInfo clone(); + + // initialize this with the item for which this recurrence + // applies, so that the start date can be tracked + attribute calIItemBase item; + + /** + * The start date of an item is directly referenced by parts of calIRecurrenceInfo, + * thus changing the former without adjusting the latter would break the internal structure. + * This method provides the necessary functionality. There's no need to call it manually + * after writing to the start date of an item, since it's called automatically in the + * appropriate setter of an item. + */ + void onStartDateChange(in calIDateTime aNewStartTime, in calIDateTime aOldStartTime); + + /** + * If the base item's UID changes, this implicitly has to change all overridden items' UID, too. + * + * @param id new UID + */ + void onIdChange(in AUTF8String aNewId); + + /** + * The end point of the last occurrence, to avoid calculating occurrences for + * items that have finished recurring. If the object is mutable, or the + * recurrence is not finite, this value is the maximum possible PRTime. + */ + readonly attribute PRTime recurrenceEndDate; + + Array<calIRecurrenceItem> getRecurrenceItems(); + /** + * Set of recurrence items; the order of these matters. + */ + void setRecurrenceItems(in Array<calIRecurrenceItem> aItems); + + unsigned long countRecurrenceItems(); + void clearRecurrenceItems(); + void appendRecurrenceItem(in calIRecurrenceItem aItem); + + calIRecurrenceItem getRecurrenceItemAt(in unsigned long aIndex); + void deleteRecurrenceItemAt(in unsigned long aIndex); + void deleteRecurrenceItem(in calIRecurrenceItem aItem); + // inserts the item at the given index, pushing the item that was previously there forward + void insertRecurrenceItemAt(in calIRecurrenceItem aItem, in unsigned long aIndex); + + /** + * isFinite is true if the recurrence items specify a finite number + * of occurrences. This is useful for UI and for possibly other users. + */ + readonly attribute boolean isFinite; + + /** + * This is a shortcut to appending or removing a single negative date + * assertion. aRecurrenceId needs to be a normal recurrence id, it may not be + * RDATE. + */ + void removeOccurrenceAt(in calIDateTime aRecurrenceId); + void restoreOccurrenceAt(in calIDateTime aRecurrenceId); + + /* + * exceptions + */ + + /** + * Modify an a particular occurrence with the given exception proxy + * item. If the recurrenceId isn't an already existing exception item, + * a new exception is added. Otherwise, the existing exception + * is modified. + * + * The item's parentItem must be equal to this RecurrenceInfo's + * item. <-- XXX check this, compare by calendar/id only + * + * @param anItem exceptional/overridden item + * @param aTakeOverOwnership whether the recurrence info object can take over + * the item or needs to clone it + */ + void modifyException(in calIItemBase anItem, in boolean aTakeOverOwnership); + + /** + * Return an existing exception item for the given recurrence ID. + * If an exception does not exist, null is returned. + */ + calIItemBase getExceptionFor(in calIDateTime aRecurrenceId); + + /** + * Removes an exception item for the given recurrence ID, if + * any exist. + */ + void removeExceptionFor(in calIDateTime aRecurrenceId); + + /** + * Returns a list of all recurrence ids that have exceptions. + */ + Array<calIDateTime> getExceptionIds(); + + /* + * Recurrence calculation + */ + + /* + * Get the occurrence at the given recurrence ID; if there is no + * exception, then create a new proxy object with the normal occurrence. + * Otherwise, return the exception. + * + * @param aRecurrenceId The recurrence ID to get the occurrence for. + * @return The occurrence or exception corresponding to the id + */ + calIItemBase getOccurrenceFor(in calIDateTime aRecurrenceId); + + /** + * Return the chronologically next occurrence after aTime. This takes + * exceptions and EXDATE/RDATEs into account. + * + * @param aTime The (exclusive) date to start searching. + * @return The next occurrence, or null if there is none. + */ + calIItemBase getNextOccurrence(in calIDateTime aTime); + + /** + * Return the chronologically previous occurrence after aTime. This takes + * exceptions and EXDATE/RDATEs into account. + * + * @param aTime The (exclusive) date to start searching. + * @return The previous occurrence, or null if there is none. + */ + calIItemBase getPreviousOccurrence(in calIDateTime aTime); + + /** + * Return an array of calIDateTime representing all start times of this event + * between start (inclusive) and end (non-inclusive). Exceptions are taken + * into account. + * + * @param aRangeStart The (inclusive) date to start searching. + * @param aRangeEnd The (exclusive) date to end searching. + * @param aMaxCount The maximum number of dates to return + * + * @param aCount The number of dates returned. + * @return The array of dates. + */ + Array<calIDateTime> getOccurrenceDates(in calIDateTime aRangeStart, + in calIDateTime aRangeEnd, + in unsigned long aMaxCount); + + /** + * Return an array of calIItemBase representing all occurrences of this event + * between start (inclusive) and end (non-inclusive). Exceptions are taken + * into account. + * + * @param aRangeStart The (inclusive) date to start searching. + * @param aRangeEnd The (exclusive) date to end searching. + * @param aMaxCount The maximum number of occurrences to return + * + * @param aCount The number of occurrences returned. + * @return The array of occurrences. + */ + Array<calIItemBase> getOccurrences(in calIDateTime aRangeStart, + in calIDateTime aRangeEnd, + in unsigned long aMaxCount); +}; |