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

interface calIItemACLEntry;
interface calIAlarm;
interface calIAttachment;
interface calIAttendee;
interface calICalendar;
interface calIDateTime;
interface calIDuration;
interface calIIcalComponent;
interface calIRecurrenceInfo;
interface calIRelation;

//
// calIItemBase
//
// Base for Events, Todos, Journals, etc.
//

[scriptable, uuid(9c988b8d-af45-4046-b05e-34417bba9058)]
interface calIItemBase : 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
  calIItemBase clone();

  /**
   * Returns true if this item is an instance of calIEvent.
   */
  boolean isEvent();

  /**
   * Returns true if this item is an instance of calITodo.
   */
  boolean isTodo();

  /**
   * Hash Id that incorporates the item's UID, RECURRENCE-ID and calendar.id
   * to be used for lookup of items that come from different calendars.
   * Setting either id, recurrenceId or the calendar attribute leads to
   * a recomputation of hashId.
   *
   * @attention Individual implementors of calIItemBase must stick to the
   *            same algorithm that base/src/CalItemBase.sys.mjs uses.
   */
  readonly attribute AUTF8String hashId;

  /**
   * Checks whether the argument object refers the same calendar item as
   * this one, by testing both the id and recurrenceId property.  This
   *
   * @arg aItem     the item to compare against this one
   *
   * @return        true if both ids match, false otherwise
   */
  boolean hasSameIds(in calIItemBase aItem);

  /**
   * Returns the acl entry associated to the item.
   */
  readonly attribute calIItemACLEntry aclEntry;

  //
  // the generation number of this item
  //
  attribute uint32_t generation;

  // the time when this item was created
  readonly attribute calIDateTime creationDate;

  // last time any attribute was modified on this item, in UTC
  readonly attribute calIDateTime lastModifiedTime;

  // last time a "significant change" was made to this item
  readonly attribute calIDateTime stampTime;

  // the calICalendar to which this event belongs
  attribute calICalendar calendar;

  // the ID of this event
  attribute AUTF8String id;

  // event title
  attribute AUTF8String title;

  /**
   * The event's description in plain text.
   *
   * Setting this will reset descriptionHTML.
   */
  attribute AUTF8String descriptionText;

  /**
   * The event's description, as HTML.
   *
   * The text content MUST match descriptionText but the HTML can contain
   * formatting, links etc.
   *
   * Getter: If HTML was not set, the plain text will be upconverted to HTML.
   *
   * Setter: Setting HTML data will set descriptionText to the
   * downconverted pretty-printed plain text.
   */
  attribute AUTF8String descriptionHTML;

  // event priority
  attribute short priority;
  attribute AUTF8String privacy;

  // status of the event
  attribute AUTF8String status;

  // ical interop; writing this means parsing
  // the ical string into this event
  attribute AUTF8String icalString;

  // an icalComponent for this item, suitable for serialization.
  // the icalComponent returned is not live: changes in it or this
  // item will not be reflected in the other.
  attribute calIIcalComponent icalComponent;

  //
  // alarms
  //

  /**
   * Get all alarms assigned to this item
   *
   * @param aAlarms     The array of calIAlarms
   */
  Array<calIAlarm> getAlarms();

   /**
   * Add an alarm to the item
   *
   * @param aAlarm      The calIAlarm to add
   */
  void addAlarm(in calIAlarm aAlarm);

  /**
   * Delete an alarm from the item
   *
   * @param aAlarm      The calIAlarm to delete
   */
  void deleteAlarm(in calIAlarm aAlarm);

  /**
   * Clear all alarms from the item
   */
  void clearAlarms();

  // The last time this alarm was fired and acknowledged by the user; coerced to UTC.
  attribute calIDateTime alarmLastAck;

  //
  // recurrence
  //
  attribute calIRecurrenceInfo recurrenceInfo;
  readonly attribute calIDateTime recurrenceStartDate;

  //
  // All event properties are stored in a property bag;
  // some number of these are "promoted" to top-level
  // accessor attributes.  For example, "SUMMARY" is
  // promoted to the top-level "title" attribute.
  //
  // If you use the has/get/set/deleteProperty
  // methods, property names are case-insensitive.
  //
  // For purposes of ICS serialization, all property names in
  // the hashbag are in uppercase.
  //
  // The isPropertyPromoted() attribute can will indicate
  // if a particular property is promoted or not, for
  // serialization purposes.
  //

  // Note that if this item is a proxy, then any requests for
  // non-existent properties will be forward to the parent item.

  // some other properties that may exist:
  //
  // 'description' - description (string)
  // 'location' - location (string)
  // 'categories' - categories (string)
  // 'syncId' - sync id (string)
  // 'inviteEmailAddress' - string
  // alarmLength/alarmUnits/alarmEmailAddress/lastAlarmAck
  // recurInterval/recurCount/recurWeekdays/recurWeeknumber

  // these forward to an internal property bag; implemented here, so we can
  // do access control on set/delete to have control over mutability.
  // Each inner array has two elements: a string and a nsIVariant.
  readonly attribute Array<Array<jsval> > properties;
  boolean hasProperty(in AString name);

  /**
   * Gets a particular property.
   * Objects passed back are still owned by the item, e.g. if callers need to
   * store or modify a calIDateTime they must clone it.
   */
  nsIVariant getProperty(in AString name);

  /**
   * Sets a particular property.
   * Ownership of objects gets passed to the item, e.g. callers must not
   * modify a calIDateTime after it's been passed to an item.
   *
   * @warning this reflects the current implementation
   *          xxx todo: rethink whether it's more sensible to store
   *                    clones in calItemBase.
   */
  void setProperty(in AString name, in nsIVariant value);

  // will not throw an error if you delete a property that doesn't exist
  void deleteProperty(in AString name);

  // returns true if the given property is promoted to some
  // top-level attribute (e.g. id or title)
  boolean isPropertyPromoted(in AString name);

  /**
   * Returns a particular parameter value for a property, or null if the
   * parameter does not exist.  If the property does not exist, throws.
   *
   * @param aPropertyName  the name of the property
   * @param aParameterName the name of the parameter on the property
   */
  AString getPropertyParameter(in AString aPropertyName,
                               in AString aParameterName);

  /**
   * Checks if the given property has the given parameter.
   *
   * @param aPropertyName   The name of the property.
   * @param aParameterName  The name of the parameter on the property.
   * @return                True, if the parameter exists on the property
   */
  boolean hasPropertyParameter(in AString aPropertyName,
                              in AString aParameterName);

  /**
   * Sets a particular parameter value for a property, or unsets if null is
   * passed. If the property does not exist, throws.
   *
   * @param aPropertyName   The name of the property
   * @param aParameterName  The name of the parameter on the property
   * @param aParameterValue The value of the parameter to set
   */
  void setPropertyParameter(in AString aPropertyName,
                            in AString aParameterName,
                            in AUTF8String aParameterValue);

  /**
   * Returns the names of all the parameters set on the given property.
   *
   * @param aPropertyName {AString} The name of the property.
   * @return {Array<AString}        The parameter names.
   */
  Array<AString> getParameterNames(in AString aPropertyName);

  /**
   * The organizer (originator) of the item.  We will likely not
   * honour or preserve all fields in the calIAttendee passed around here.
   * A base class like calIPerson might be more appropriate here, if we ever
   * grow one.
   */
  attribute calIAttendee organizer;

  //
  // Attendees
  //

  // The array returned here is not live; it will not reflect calls to
  // removeAttendee/addAttendee that follow the call to getAttendees.
  Array<calIAttendee> getAttendees();

  /**
   * getAttendeeById's matching is done in a case-insensitive manner to handle
   * places where "MAILTO:" or similar properties are capitalized arbitrarily
   * by different calendar clients.
   */
  calIAttendee getAttendeeById(in AUTF8String id);
  void addAttendee(in calIAttendee attendee);
  void removeAttendee(in calIAttendee attendee);
  void removeAllAttendees();

  //
  // Attachments
  //
  Array<calIAttachment> getAttachments();
  void addAttachment(in calIAttachment attachment);
  void removeAttachment(in calIAttachment attachment);
  void removeAllAttachments();

  //
  // Categories
  //

  /**
   * Gets the array of categories this item belongs to.
   */
  Array<AString> getCategories();

  /**
   * Sets the array of categories this item belongs to.
   */
  void setCategories(in Array<AString> aCategories);

  //
  // Relations
  //

  /**
   * This gives back every relation where the item is neither the owner of the
   * relation nor the referred relation
   */
  Array<calIRelation> getRelations();

  /**
   * Adds a relation to the item
   */
  void addRelation(in calIRelation relation);

  /**
   * Removes the relation for this item and the referred item
   */
  void removeRelation(in calIRelation relation);

  /**
   * Removes every relation for this item (in this items and also where it is referred
   */
  void removeAllRelations();

  // Occurrence querying
  //

  /**
   * Return a list of occurrences of this item between the given dates.  The items
   * returned are the same type as this one, as proxies.
   */
  Array<calIItemBase> getOccurrencesBetween(in calIDateTime aStartDate, in calIDateTime aEndDate);

  /**
   * If this item is a proxy or overridden item, parentItem will point upwards
   * to our parent.  Otherwise, it will point to this.
   * parentItem can thus always be used for modifyItem() calls
   * to providers.
   */
  attribute calIItemBase parentItem;

  /**
   * The recurrence ID, a.k.a. DTSTART-of-calculated-occurrence,
   * or null if this isn't an occurrence.
   * Be conservative about setting this. It isn't marked as such, but
   * consider it as readonly.
   */
  attribute calIDateTime recurrenceId;
};