diff options
Diffstat (limited to 'comm/calendar/base/public/calIDateTime.idl')
| -rw-r--r-- | comm/calendar/base/public/calIDateTime.idl | 228 |
1 files changed, 228 insertions, 0 deletions
diff --git a/comm/calendar/base/public/calIDateTime.idl b/comm/calendar/base/public/calIDateTime.idl new file mode 100644 index 0000000000..e4da295843 --- /dev/null +++ b/comm/calendar/base/public/calIDateTime.idl @@ -0,0 +1,228 @@ +/* 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 second, 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(); + + /** + * Returns a string representation of this instance suitable for JSON. + */ + AUTF8String toJSON(); + + /** + * 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; +}; |