1 files changed, 232 insertions, 0 deletions
diff --git a/calendar/base/public/calIDateTime.idl b/calendar/base/public/calIDateTime.idl
new file mode 100644
index 000000000..d6c94052b
--- /dev/null
+++ b/calendar/base/public/calIDateTime.idl
@@ -0,0 +1,232 @@
+/* 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);
+};