/* 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.
   *
   * @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 array of calIDateTime of the start of all occurrences of
  // this event starting at aStartTime, between rangeStart and an
  // optional rangeEnd
  void getOccurrences (in calIDateTime aStartTime,
                       in calIDateTime aRangeStart,
                       in calIDateTime aRangeEnd,
                       in unsigned long aMaxCount,
                       out unsigned long aCount, [array,size_is(aCount),retval] out calIDateTime aDates);

  attribute calIIcalProperty icalProperty;
  attribute AUTF8String icalString;
};
