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