1/* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
4
5#include "nsISupports.idl"
6
7interface calIDuration;
8interface calITimezone;
9
10[scriptable, uuid(fe3e9a58-2938-4b2c-9085-4989d5f7244f)]
11interface calIDateTime : nsISupports
12{
13  /**
14   * isMutable is true if this instance is modifiable.
15   * If isMutable is false, any attempts to modify
16   * the object will throw NS_ERROR_OBJECT_IS_IMMUTABLE.
17   */
18  readonly attribute boolean isMutable;
19
20  /**
21   * Make this calIDateTime instance immutable.
22   */
23  void makeImmutable();
24
25  /**
26   * Clone this calIDateTime instance into a new
27   * mutable object.
28   */
29  calIDateTime clone();
30
31  /**
32   * valid is true if this object contains a valid
33   * time/date.
34   */
35  // true if this thing is set/valid
36  readonly attribute boolean isValid;
37
38  /**
39   * nativeTime contains this instance's PRTime value relative
40   * to the UTC epoch, regardless of the timezone that's set
41   * on this instance.  If nativeTime is set, the given UTC PRTime
42   * value is exploded into year/month/etc, forcing the timezone
43   * setting to UTC.
44   *
45   * @warning: When the timezone is set to 'floating', this will return
46   * the nativeTime as-if the timezone was UTC. Take this into account
47   * when comparing values.
48   *
49   * @note on objects that are pinned to a timezone and have isDate set,
50   * nativeTime will be 00:00:00 in the timezone of that date, not 00:00:00 in
51   * UTC.
52   */
53  attribute PRTime nativeTime;
54
55  /**
56   * Full 4-digit year value (e.g. "1989", "2004")
57   */
58  attribute short year;
59
60  /**
61   * Month, 0-11, 0 = January
62   */
63  attribute short month;
64
65  /**
66   * Day of month, 1-[28,29,30,31]
67   */
68  attribute short day;
69
70  /**
71   * Hour, 0-23
72   */
73  attribute short hour;
74
75  /**
76   * Minute, 0-59
77   */
78  attribute short minute;
79
80  /**
81   * Second, 0-59
82   */
83  attribute short second;
84
85  /**
86   * Gets or sets the timezone of this calIDateTime instance.
87   * Setting the timezone does not change the actual date/time components;
88   * to convert between timezones, use getInTimezone().
89   *
90   * @throws NS_ERROR_INVALID_ARG if null is passed in.
91   */
92  attribute calITimezone timezone;
93
94  /**
95   * Resets the datetime object.
96   *
97   * @param year     full 4-digit year value (e.g. "1989", "2004")
98   * @param month    month, 0-11, 0 = January
99   * @param day      day of month, 1-[28,29,31]
100   * @param hour     hour, 0-23
101   * @param minute   minute, 0-59
102   * @param second   second, 0-59
103   * @param timezone timezone
104   *
105   * The passed datetime will be normalized, e.g. a minute value of 60 will
106   * increase the hour.
107   *
108   * @throws NS_ERROR_INVALID_ARG if no timezone is passed in.
109   */
110  void resetTo(in short year,
111               in short month,
112               in short day,
113               in short hour,
114               in short minute,
115               in short second,
116               in calITimezone timezone);
117
118  /**
119   * The offset of the timezone this datetime is in, relative to UTC, in
120   * seconds. A positive number means that the timezone is ahead of UTC.
121   */
122  readonly attribute long timezoneOffset;
123
124  /**
125   * isDate indicates that this calIDateTime instance represents a date
126   * (a whole day), and not a specific time on that day.  If isDate is set,
127   * accessing the hour/minute/second fields will return 0, and and setting
128   * them is an illegal operation.
129   */
130  attribute boolean isDate;
131
132  /*
133   * computed values
134   */
135
136  /**
137   * Day of the week. 0-6, with Sunday = 0.
138   */
139  readonly attribute short weekday;
140
141  /**
142   * Day of the year, 1-[365,366].
143   */
144  readonly attribute short yearday;
145
146  /*
147   * Methods
148   */
149
150  /**
151   * Resets this instance to Jan 1, 1970 00:00:00 UTC.
152   */
153  void reset();
154
155  /**
156   * Return a string representation of this instance.
157   */
158  AUTF8String toString();
159
160  /**
161   * Return a new calIDateTime instance that's the result of
162   * converting this one into the given timezone.  Valid values
163   * for aTimezone are the same as the timezone field.  If
164   * the "floating" timezone is given, then this object
165   * is just cloned, and the timezone is set to floating.
166   */
167  calIDateTime getInTimezone(in calITimezone aTimezone);
168
169  // add the given calIDateTime, treating it as a duration, to
170  // this item.
171  // XXX will change
172  void addDuration (in calIDuration aDuration);
173
174  // Subtract two dates and return a duration
175  // returns duration of this - aOtherDate
176  // if aOtherDate is > this the duration will be negative
177  calIDuration subtractDate (in calIDateTime aOtherDate);
178
179  /**
180   * Compare this calIDateTime instance to aOther.  Returns -1, 0, 1 to
181   * indicate if this < aOther, this == aOther, or this > aOther,
182   * respectively.
183   *
184   * This comparison is timezone-aware; the given values are converted
185   * to a common timezone before comparing. If either this or aOther is
186   * floating, both objects are treated as floating for the comparison.
187   *
188   * If either this or aOther has isDate set, then only the date portion is
189   * compared.
190   *
191   * @exception calIErrors.INVALID_TIMEZONE  bad timezone on this object
192   *                                         (not the argument object)
193   */
194  long compare (in calIDateTime aOther);
195
196  //
197  // Some helper getters for calculating useful ranges
198  //
199
200  /**
201   * Returns SUNDAY of the given datetime object's week.
202   */
203  readonly attribute calIDateTime startOfWeek;
204
205  /**
206   * Returns SATURDAY of the datetime object's week.
207   */
208  readonly attribute calIDateTime endOfWeek;
209
210  // the start/end of the current object's month
211  readonly attribute calIDateTime startOfMonth;
212  readonly attribute calIDateTime endOfMonth;
213
214  // the start/end of the current object's year
215  readonly attribute calIDateTime startOfYear;
216  readonly attribute calIDateTime endOfYear;
217
218  /**
219   * This object as either an iCalendar DATE or DATETIME string, as
220   * appropriate and sets the timezone to either UTC or floating.
221   */
222  attribute ACString icalString;
223};
224
225/** Libical specific interfaces */
226
227[ptr] native icaltimetypeptr(struct icaltimetype);
228[builtinclass,scriptable,uuid(04139dff-a6f0-446d-9aec-2062df887ef2)]
229interface calIDateTimeLibical : calIDateTime
230{
231  [noscript,notxpcom] void toIcalTime(in icaltimetypeptr itt);
232};
233