Revision control
Copy as Markdown
Other Tools
/* 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
#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;
};