icuSources/i18n/vzone.h

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