1 /* 2 ******************************************************************************* 3 * Copyright (C) 2009-2010, International Business Machines Corporation and * 4 * others. All Rights Reserved. * 5 ******************************************************************************* 6 */ 7 8 /** 9 * \file 10 * \brief C API: RFC2445 VTIMEZONE support 11 * 12 * <p>This is a C wrapper around the C++ VTimeZone class.</p> 13 */ 14 15 #ifndef __VZONE_H 16 #define __VZONE_H 17 18 #include "unicode/utypes.h" 19 #include "ztrans.h" 20 21 #ifndef UCNV_H 22 struct VZone; 23 /** 24 * A UnicodeSet. Use the vzone_* API to manipulate. Create with 25 * vzone_open*, and destroy with vzone_close. 26 * @stable ICU 2.4 27 */ 28 typedef struct VZone VZone; 29 #endif 30 31 /********************************************************************* 32 * VZone API 33 *********************************************************************/ 34 35 /** 36 * Creates a vzone from the given time zone ID. 37 * @param ID The time zone ID, such as America/New_York 38 * @param idLength, length of the ID parameter 39 * @return A vzone object initialized by the time zone ID, 40 * or NULL when the ID is unknown. 41 * @draft ICU 4.4 42 */ 43 U_DRAFT VZone* U_EXPORT2 44 vzone_openID(const UChar* ID, int32_t idLength); 45 46 /** 47 * Create a vzone instance by RFC2445 VTIMEZONE data 48 * @param vtzdata The string including VTIMEZONE data block 49 * @param vtzdataLength, length of the vtzdata 50 * @param status Output param to filled in with a success or an error. 51 * @return A vzone initialized by the VTIMEZONE data or 52 * NULL if failed to load the rule from the VTIMEZONE data. 53 * @draft ICU 4.4 54 */ 55 U_DRAFT VZone* U_EXPORT2 56 vzone_openData(const UChar* vtzdata, int32_t vtzdataLength, UErrorCode& status); 57 58 /** 59 * Disposes of the storage used by a VZone object. This function should 60 * be called exactly once for objects returned by vzone_open*. 61 * @param set the object to dispose of 62 * @draft ICU 4.4 63 */ 64 U_DRAFT void U_EXPORT2 65 vzone_close(VZone* zone); 66 67 /** 68 * Returns a copy of this object. 69 * @param zone the original vzone 70 * @return the newly allocated copy of the vzone 71 * @draft ICU 4.4 72 */ 73 U_DRAFT VZone* U_EXPORT2 74 vzone_clone(const VZone *zone); 75 76 /** 77 * Returns true if zone1 is identical to zone2 78 * and vis versa. 79 * @param zone1 to be checked for containment 80 * @param zone2 to be checked for containment 81 * @return true if the test condition is met 82 * @draft ICU 4.4 83 */ 84 U_DRAFT UBool U_EXPORT2 85 vzone_equals(const VZone* zone1, const VZone* zone2); 86 87 /** 88 * Gets the RFC2445 TZURL property value. When a vzone instance was 89 * created from VTIMEZONE data, the initial value is set by the TZURL 90 * property value in the data. Otherwise, the initial value is not set. 91 * @param zone, the vzone to use 92 * @param url Receives the RFC2445 TZURL property value. 93 * @param urlLength, length of the url 94 * @return TRUE if TZURL attribute is available and value is set. 95 * @draft ICU 4.4 96 */ 97 U_DRAFT UBool U_EXPORT2 98 vzone_getTZURL(VZone* zone, UChar* & url, int32_t & urlLength); 99 100 /** 101 * Sets the RFC2445 TZURL property value. 102 * @param zone, the vzone to use 103 * @param url The TZURL property value. 104 * @param urlLength, length of the url 105 * @draft ICU 4.4 106 */ 107 U_DRAFT void U_EXPORT2 108 vzone_setTZURL(VZone* zone, UChar* url, int32_t urlLength); 109 110 /** 111 * Gets the RFC2445 LAST-MODIFIED property value. When a vzone instance 112 * was created from VTIMEZONE data, the initial value is set by the 113 * LAST-MODIFIED property value in the data. Otherwise, the initial value 114 * is not set. 115 * @param zone, the vzone to use 116 * @param lastModified Receives the last modified date. 117 * @return TRUE if lastModified attribute is available and value is set. 118 * @draft ICU 4.4 119 */ 120 U_DRAFT UBool U_EXPORT2 121 vzone_getLastModified(VZone* zone, UDate& lastModified); 122 123 /** 124 * Sets the RFC2445 LAST-MODIFIED property value. 125 * @param zone, the vzone to use 126 * @param lastModified The LAST-MODIFIED date. 127 * @draft ICU 4.4 128 */ 129 U_DRAFT void U_EXPORT2 130 vzone_setLastModified(VZone* zone, UDate lastModified); 131 132 /** 133 * Writes RFC2445 VTIMEZONE data for this time zone 134 * @param zone, the vzone to use 135 * @param result Output param to filled in with the VTIMEZONE data. 136 * @param resultLength, length of the result output 137 * @param status Output param to filled in with a success or an error. 138 * @draft ICU 4.4 139 */ 140 U_DRAFT void U_EXPORT2 141 vzone_write(VZone* zone, UChar* & result, int32_t & resultLength, UErrorCode& status); 142 143 /** 144 * Writes RFC2445 VTIMEZONE data for this time zone applicalbe 145 * for dates after the specified start time. 146 * @param zone, the vzone to use 147 * @param start The start date. 148 * @param result Output param to filled in with the VTIMEZONE data. 149 * @param resultLength, length of the result output 150 * @param status Output param to filled in with a success or an error. 151 * @draft ICU 4.4 152 */ 153 U_DRAFT void U_EXPORT2 154 vzone_writeFromStart(VZone* zone, UDate start, UChar* & result, int32_t & resultLength, UErrorCode& status); 155 156 /** 157 * Writes RFC2445 VTIMEZONE data applicalbe for the specified date. 158 * Some common iCalendar implementations can only handle a single time 159 * zone property or a pair of standard and daylight time properties using 160 * BYDAY rule with day of week (such as BYDAY=1SUN). This method produce 161 * the VTIMEZONE data which can be handled these implementations. The rules 162 * produced by this method can be used only for calculating time zone offset 163 * around the specified date. 164 * @param zone, the vzone to use 165 * @param time The date used for rule extraction. 166 * @param result Output param to filled in with the VTIMEZONE data. 167 * @param status Output param to filled in with a success or an error. 168 * @draft ICU 4.4 169 */ 170 U_DRAFT void U_EXPORT2 171 vzone_writeSimple(VZone* zone, UDate time, UChar* & result, int32_t & resultLength, UErrorCode& status); 172 173 /** 174 * Returns the TimeZone's adjusted GMT offset (i.e., the number of milliseconds to add 175 * to GMT to get local time in this time zone, taking daylight savings time into 176 * account) as of a particular reference date. The reference date is used to determine 177 * whether daylight savings time is in effect and needs to be figured into the offset 178 * that is returned (in other words, what is the adjusted GMT offset in this time zone 179 * at this particular date and time?). For the time zones produced by createTimeZone(), 180 * the reference data is specified according to the Gregorian calendar, and the date 181 * and time fields are local standard time. 182 * 183 * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) overload, 184 * which returns both the raw and the DST offset for a given time. This method 185 * is retained only for backward compatibility. 186 * 187 * @param zone, the vzone to use 188 * @param era The reference date's era 189 * @param year The reference date's year 190 * @param month The reference date's month (0-based; 0 is January) 191 * @param day The reference date's day-in-month (1-based) 192 * @param dayOfWeek The reference date's day-of-week (1-based; 1 is Sunday) 193 * @param millis The reference date's milliseconds in day, local standard time 194 * @param status Output param to filled in with a success or an error. 195 * @return The offset in milliseconds to add to GMT to get local time. 196 * @draft ICU 4.4 197 */ 198 U_DRAFT int32_t U_EXPORT2 199 vzone_getOffset(VZone* zone, uint8_t era, int32_t year, int32_t month, int32_t day, 200 uint8_t dayOfWeek, int32_t millis, UErrorCode& status); 201 202 /** 203 * Gets the time zone offset, for current date, modified in case of 204 * daylight savings. This is the offset to add *to* UTC to get local time. 205 * 206 * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) overload, 207 * which returns both the raw and the DST offset for a given time. This method 208 * is retained only for backward compatibility. 209 * 210 * @param zone, the vzone to use 211 * @param era The reference date's era 212 * @param year The reference date's year 213 * @param month The reference date's month (0-based; 0 is January) 214 * @param day The reference date's day-in-month (1-based) 215 * @param dayOfWeek The reference date's day-of-week (1-based; 1 is Sunday) 216 * @param millis The reference date's milliseconds in day, local standard time 217 * @param monthLength The length of the given month in days. 218 * @param status Output param to filled in with a success or an error. 219 * @return The offset in milliseconds to add to GMT to get local time. 220 * @draft ICU 4.4 221 */ 222 U_DRAFT int32_t U_EXPORT2 223 vzone_getOffset2(VZone* zone, uint8_t era, int32_t year, int32_t month, int32_t day, 224 uint8_t dayOfWeek, int32_t millis, 225 int32_t monthLength, UErrorCode& status); 226 227 /** 228 * Returns the time zone raw and GMT offset for the given moment 229 * in time. Upon return, local-millis = GMT-millis + rawOffset + 230 * dstOffset. All computations are performed in the proleptic 231 * Gregorian calendar. The default implementation in the TimeZone 232 * class delegates to the 8-argument getOffset(). 233 * 234 * @param zone, the vzone to use 235 * @param date moment in time for which to return offsets, in 236 * units of milliseconds from January 1, 1970 0:00 GMT, either GMT 237 * time or local wall time, depending on `local'. 238 * @param local if true, `date' is local wall time; otherwise it 239 * is in GMT time. 240 * @param rawOffset output parameter to receive the raw offset, that 241 * is, the offset not including DST adjustments 242 * @param dstOffset output parameter to receive the DST offset, 243 * that is, the offset to be added to `rawOffset' to obtain the 244 * total offset between local and GMT time. If DST is not in 245 * effect, this value is zero; otherwise it is a positive value, 246 * typically one hour. 247 * @param ec input-output error code 248 * @draft ICU 4.4 249 */ 250 U_DRAFT void U_EXPORT2 251 vzone_getOffset3(VZone* zone, UDate date, UBool local, int32_t& rawOffset, 252 int32_t& dstOffset, UErrorCode& ec); 253 254 /** 255 * Sets the TimeZone's raw GMT offset (i.e., the number of milliseconds to add 256 * to GMT to get local time, before taking daylight savings time into account). 257 * 258 * @param zone, the vzone to use 259 * @param offsetMillis The new raw GMT offset for this time zone. 260 * @draft ICU 4.4 261 */ 262 U_DRAFT void U_EXPORT2 263 vzone_setRawOffset(VZone* zone, int32_t offsetMillis); 264 265 /** 266 * Returns the TimeZone's raw GMT offset (i.e., the number of milliseconds to add 267 * to GMT to get local time, before taking daylight savings time into account). 268 * 269 * @param zone, the vzone to use 270 * @return The TimeZone's raw GMT offset. 271 * @draft ICU 4.4 272 */ 273 U_DRAFT int32_t U_EXPORT2 274 vzone_getRawOffset(VZone* zone); 275 276 /** 277 * Queries if this time zone uses daylight savings time. 278 * @param zone, the vzone to use 279 * @return true if this time zone uses daylight savings time, 280 * false, otherwise. 281 * @draft ICU 4.4 282 */ 283 U_DRAFT UBool U_EXPORT2 284 vzone_useDaylightTime(VZone* zone); 285 286 /** 287 * Queries if the given date is in daylight savings time in 288 * this time zone. 289 * This method is wasteful since it creates a new GregorianCalendar and 290 * deletes it each time it is called. This is a deprecated method 291 * and provided only for Java compatibility. 292 * 293 * @param zone, the vzone to use 294 * @param date the given UDate. 295 * @param status Output param filled in with success/error code. 296 * @return true if the given date is in daylight savings time, 297 * false, otherwise. 298 * @deprecated ICU 2.4. Use Calendar::inDaylightTime() instead. 299 */ 300 U_DRAFT UBool U_EXPORT2 301 vzone_inDaylightTime(VZone* zone, UDate date, UErrorCode& status); 302 303 /** 304 * Returns true if this zone has the same rule and offset as another zone. 305 * That is, if this zone differs only in ID, if at all. 306 * @param zone, the vzone to use 307 * @param other the <code>TimeZone</code> object to be compared with 308 * @return true if the given zone is the same as this one, 309 * with the possible exception of the ID 310 * @draft ICU 4.4 311 */ 312 U_DRAFT UBool U_EXPORT2 313 vzone_hasSameRules(VZone* zone, const VZone* other); 314 315 /** 316 * Gets the first time zone transition after the base time. 317 * @param zone, the vzone to use 318 * @param base The base time. 319 * @param inclusive Whether the base time is inclusive or not. 320 * @param result Receives the first transition after the base time. 321 * @return TRUE if the transition is found. 322 * @draft ICU 4.4 323 */ 324 U_DRAFT UBool U_EXPORT2 325 vzone_getNextTransition(VZone* zone, UDate base, UBool inclusive, ZTrans* result); 326 327 /** 328 * Gets the most recent time zone transition before the base time. 329 * @param zone, the vzone to use 330 * @param base The base time. 331 * @param inclusive Whether the base time is inclusive or not. 332 * @param result Receives the most recent transition before the base time. 333 * @return TRUE if the transition is found. 334 * @draft ICU 4.4 335 */ 336 U_DRAFT UBool U_EXPORT2 337 vzone_getPreviousTransition(VZone* zone, UDate base, UBool inclusive, ZTrans* result); 338 339 /** 340 * Returns the number of <code>TimeZoneRule</code>s which represents time transitions, 341 * for this time zone, that is, all <code>TimeZoneRule</code>s for this time zone except 342 * <code>InitialTimeZoneRule</code>. The return value range is 0 or any positive value. 343 * @param zone, the vzone to use 344 * @param status Receives error status code. 345 * @return The number of <code>TimeZoneRule</code>s representing time transitions. 346 * @draft ICU 4.4 347 */ 348 U_DRAFT int32_t U_EXPORT2 349 vzone_countTransitionRules(VZone* zone, UErrorCode& status); 350 351 /** 352 * Return the class ID for this class. This is useful only for comparing to 353 * a return value from getDynamicClassID(). For example: 354 * <pre> 355 * . Base* polymorphic_pointer = createPolymorphicObject(); 356 * . if (polymorphic_pointer->getDynamicClassID() == 357 * . erived::getStaticClassID()) ... 358 * </pre> 359 * @param zone, the vzone to use 360 * @return The class ID for all objects of this class. 361 * @draft ICU 4.4 362 */ 363 U_DRAFT UClassID U_EXPORT2 364 vzone_getStaticClassID(VZone* zone); 365 366 /** 367 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This 368 * method is to implement a simple version of RTTI, since not all C++ 369 * compilers support genuine RTTI. Polymorphic operator==() and clone() 370 * methods call this method. 371 * 372 * @param zone, the vzone to use 373 * @return The class ID for this object. All objects of a 374 * given class have the same class ID. Objects of 375 * other classes have different class IDs. 376 * @draft ICU 4.4 377 */ 378 U_DRAFT UClassID U_EXPORT2 379 vzone_getDynamicClassID(VZone* zone); 380 381 #endif // __VZONE_H 382
