thunderbird-dev 1:52.8.0-1~deb8u1 / usr / share / idl / thunderbird / calIDateTime.idl

/* 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 calIDuration;
interface calITimezone;

[scriptable, uuid(fe3e9a58-2938-4b2c-9085-4989d5f7244f)]
interface calIDateTime : nsISupports
{
  /**
   * isMutable is true if this instance is modifiable.
   * If isMutable is false, any attempts to modify
   * the object will throw NS_ERROR_OBJECT_IS_IMMUTABLE.
   */
  readonly attribute boolean isMutable;

  /**
   * Make this calIDateTime instance immutable.
   */
  void makeImmutable();

  /**
   * Clone this calIDateTime instance into a new
   * mutable object.
   */
  calIDateTime clone();

  /**
   * valid is true if this object contains a valid
   * time/date.
   */
  // true if this thing is set/valid
  readonly attribute boolean isValid;

  /**
   * nativeTime contains this instance's PRTime value relative
   * to the UTC epoch, regardless of the timezone that's set
   * on this instance.  If nativeTime is set, the given UTC PRTime
   * value is exploded into year/month/etc, forcing the timezone
   * setting to UTC.
   *
   * @warning: When the timezone is set to 'floating', this will return
   * the nativeTime as-if the timezone was UTC. Take this into account
   * when comparing values.
   *
   * @note on objects that are pinned to a timezone and have isDate set,
   * nativeTime will be 00:00:00 in the timezone of that date, not 00:00:00 in
   * UTC.
   */
  attribute PRTime nativeTime;

  /**
   * Full 4-digit year value (e.g. "1989", "2004")
   */
  attribute short year;

  /**
   * Month, 0-11, 0 = January
   */
  attribute short month;

  /**
   * Day of month, 1-[28,29,30,31]
   */
  attribute short day;

  /**
   * Hour, 0-23
   */
  attribute short hour;

  /**
   * Minute, 0-59
   */
  attribute short minute;

  /**
   * Second, 0-59
   */
  attribute short second;

  /**
   * Gets or sets the timezone of this calIDateTime instance.
   * Setting the timezone does not change the actual date/time components;
   * to convert between timezones, use getInTimezone().
   *
   * @throws NS_ERROR_INVALID_ARG if null is passed in.
   */
  attribute calITimezone timezone;

  /**
   * Resets the datetime object.
   *
   * @param year     full 4-digit year value (e.g. "1989", "2004")
   * @param month    month, 0-11, 0 = January
   * @param day      day of month, 1-[28,29,31]
   * @param hour     hour, 0-23
   * @param minute   minute, 0-59
   * @param second   decond, 0-59
   * @param timezone timezone
   *
   * The passed datetime will be normalized, e.g. a minute value of 60 will
   * increase the hour.
   *
   * @throws NS_ERROR_INVALID_ARG if no timezone is passed in.
   */
  void resetTo(in short year,
               in short month,
               in short day,
               in short hour,
               in short minute,
               in short second,
               in calITimezone timezone);

  /**
   * The offset of the timezone this datetime is in, relative to UTC, in
   * seconds. A positive number means that the timezone is ahead of UTC.
   */
  readonly attribute long timezoneOffset;

  /**
   * isDate indicates that this calIDateTime instance represents a date
   * (a whole day), and not a specific time on that day.  If isDate is set,
   * accessing the hour/minute/second fields will return 0, and and setting
   * them is an illegal operation.
   */
  attribute boolean isDate;

  /*
   * computed values
   */

  /**
   * Day of the week. 0-6, with Sunday = 0.
   */
  readonly attribute short weekday;

  /**
   * Day of the year, 1-[365,366].
   */
  readonly attribute short yearday;

  /*
   * Methods
   */

  /**
   * Resets this instance to Jan 1, 1970 00:00:00 UTC.
   */
  void reset();

  /**
   * Return a string representation of this instance.
   */
  AUTF8String toString();

  /**
   * Return a new calIDateTime instance that's the result of
   * converting this one into the given timezone.  Valid values
   * for aTimezone are the same as the timezone field.  If
   * the "floating" timezone is given, then this object
   * is just cloned, and the timezone is set to floating.
   */
  calIDateTime getInTimezone(in calITimezone aTimezone);

  // add the given calIDateTime, treating it as a duration, to
  // this item.
  // XXX will change
  void addDuration (in calIDuration aDuration);

  // Subtract two dates and return a duration
  // returns duration of this - aOtherDate
  // if aOtherDate is > this the duration will be negative
  calIDuration subtractDate (in calIDateTime aOtherDate);

  /**
   * Compare this calIDateTime instance to aOther.  Returns -1, 0, 1 to
   * indicate if this < aOther, this == aOther, or this > aOther,
   * respectively.
   *
   * This comparison is timezone-aware; the given values are converted
   * to a common timezone before comparing. If either this or aOther is
   * floating, both objects are treated as floating for the comparison.
   *
   * If either this or aOther has isDate set, then only the date portion is
   * compared.
   *
   * @exception calIErrors.INVALID_TIMEZONE  bad timezone on this object
   *                                         (not the argument object)
   */
  long compare (in calIDateTime aOther);

  //
  // Some helper getters for calculating useful ranges
  //

  /**
   * Returns SUNDAY of the given datetime object's week.
   */
  readonly attribute calIDateTime startOfWeek;

  /**
   * Returns SATURDAY of the datetime object's week.
   */
  readonly attribute calIDateTime endOfWeek;

  // the start/end of the current object's month
  readonly attribute calIDateTime startOfMonth;
  readonly attribute calIDateTime endOfMonth;

  // the start/end of the current object's year
  readonly attribute calIDateTime startOfYear;
  readonly attribute calIDateTime endOfYear;

  /**
   * This object as either an iCalendar DATE or DATETIME string, as
   * appropriate and sets the timezone to either UTC or floating.
   */
  attribute ACString icalString;
};

/** Libical specific interfaces */

[ptr] native icaltimetypeptr(struct icaltimetype);
[scriptable, uuid(04139dff-a6f0-446d-9aec-2062df887ef2)]
interface calIDateTimeLibical : calIDateTime
{
  [noscript,notxpcom] void toIcalTime(in icaltimetypeptr itt);
};