icuSources/i18n/vzone.h

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