/* 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 calIIcalProperty;

[scriptable, uuid(918a243b-d887-41b0-8b4b-9cd56a9dd55f)]
interface calIRecurrenceItem : 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
  calIRecurrenceItem clone();

  // defaults to false; if true, this item is to be interpreted
  // as a negative rule (e.g. exceptions instead of rdates)
  attribute boolean isNegative;

  // returns whether this item has a finite number of dates
  // or not (e.g. a rule with no end date)
  readonly attribute boolean isFinite;

  /**
   * Search for the next occurrence after aTime and return its recurrence id.
   * aRecurrenceId must be the recurrence id of an occurrence to search after.
   * If this item has an unsupported FREQ value ("SECONDLY" or "MINUTELY"), null
   * is returned.
   *
   * @require               (aTime >= aRecurrenceId)
   * @param aRecurrenceId   The recurrence id to start searching at.
   * @param aTime           The earliest time to find the occurrence after.
   */
  calIDateTime getNextOccurrence(in calIDateTime aRecurrenceId,
                                 in calIDateTime aTime);

  /**
   * Return an array of calIDateTime of the start of all occurrences of
   * this event starting at aStartTime, between rangeStart and an
   * optional rangeEnd. If this item has an unsupported FREQ value ("SECONDLY"
   * or "MINUTELY"), an empty array is returned.
   */
  Array<calIDateTime> getOccurrences(in calIDateTime aStartTime,
                                     in calIDateTime aRangeStart,
                                     in calIDateTime aRangeEnd,
                                     in unsigned long aMaxCount);

  attribute calIIcalProperty icalProperty;
  attribute AUTF8String icalString;
};