1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/i18n/vzone.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,360 @@
1.4 +/*
1.5 +*******************************************************************************
1.6 +* Copyright (C) 2009-2011, International Business Machines Corporation and
1.7 +* others. All Rights Reserved.
1.8 +*******************************************************************************
1.9 +*/
1.10 +
1.11 +/**
1.12 +* \file
1.13 +* \brief C API: RFC2445 VTIMEZONE support
1.14 +*
1.15 +* <p>This is a C wrapper around the C++ VTimeZone class.</p>
1.16 +*/
1.17 +
1.18 +#ifndef __VZONE_H
1.19 +#define __VZONE_H
1.20 +
1.21 +#include "unicode/utypes.h"
1.22 +
1.23 +#if !UCONFIG_NO_FORMATTING
1.24 +
1.25 +#include "ztrans.h"
1.26 +
1.27 +#ifndef UCNV_H
1.28 +struct VZone;
1.29 +/**
1.30 + * A UnicodeSet. Use the vzone_* API to manipulate. Create with
1.31 + * vzone_open*, and destroy with vzone_close.
1.32 + */
1.33 +typedef struct VZone VZone;
1.34 +#endif
1.35 +
1.36 +/*********************************************************************
1.37 + * VZone API
1.38 + *********************************************************************/
1.39 +
1.40 +/**
1.41 + * Creates a vzone from the given time zone ID.
1.42 + * @param ID The time zone ID, such as America/New_York
1.43 + * @param idLength, length of the ID parameter
1.44 + * @return A vzone object initialized by the time zone ID,
1.45 + * or NULL when the ID is unknown.
1.46 + */
1.47 +U_CAPI VZone* U_EXPORT2
1.48 +vzone_openID(const UChar* ID, int32_t idLength);
1.49 +
1.50 +/**
1.51 + * Create a vzone instance by RFC2445 VTIMEZONE data
1.52 + * @param vtzdata The string including VTIMEZONE data block
1.53 + * @param vtzdataLength, length of the vtzdata
1.54 + * @param status Output param to filled in with a success or an error.
1.55 + * @return A vzone initialized by the VTIMEZONE data or
1.56 + * NULL if failed to load the rule from the VTIMEZONE data.
1.57 + */
1.58 +U_CAPI VZone* U_EXPORT2
1.59 +vzone_openData(const UChar* vtzdata, int32_t vtzdataLength, UErrorCode& status);
1.60 +
1.61 +/**
1.62 + * Disposes of the storage used by a VZone object. This function should
1.63 + * be called exactly once for objects returned by vzone_open*.
1.64 + * @param set the object to dispose of
1.65 + */
1.66 +U_CAPI void U_EXPORT2
1.67 +vzone_close(VZone* zone);
1.68 +
1.69 +/**
1.70 + * Returns a copy of this object.
1.71 + * @param zone the original vzone
1.72 + * @return the newly allocated copy of the vzone
1.73 + */
1.74 +U_CAPI VZone* U_EXPORT2
1.75 +vzone_clone(const VZone *zone);
1.76 +
1.77 +/**
1.78 + * Returns true if zone1 is identical to zone2
1.79 + * and vis versa.
1.80 + * @param zone1 to be checked for containment
1.81 + * @param zone2 to be checked for containment
1.82 + * @return true if the test condition is met
1.83 + */
1.84 +U_CAPI UBool U_EXPORT2
1.85 +vzone_equals(const VZone* zone1, const VZone* zone2);
1.86 +
1.87 +/**
1.88 + * Gets the RFC2445 TZURL property value. When a vzone instance was
1.89 + * created from VTIMEZONE data, the initial value is set by the TZURL
1.90 + * property value in the data. Otherwise, the initial value is not set.
1.91 + * @param zone, the vzone to use
1.92 + * @param url Receives the RFC2445 TZURL property value.
1.93 + * @param urlLength, length of the url
1.94 + * @return TRUE if TZURL attribute is available and value is set.
1.95 + */
1.96 +U_CAPI UBool U_EXPORT2
1.97 +vzone_getTZURL(VZone* zone, UChar* & url, int32_t & urlLength);
1.98 +
1.99 +/**
1.100 + * Sets the RFC2445 TZURL property value.
1.101 + * @param zone, the vzone to use
1.102 + * @param url The TZURL property value.
1.103 + * @param urlLength, length of the url
1.104 + */
1.105 +U_CAPI void U_EXPORT2
1.106 +vzone_setTZURL(VZone* zone, UChar* url, int32_t urlLength);
1.107 +
1.108 +/**
1.109 + * Gets the RFC2445 LAST-MODIFIED property value. When a vzone instance
1.110 + * was created from VTIMEZONE data, the initial value is set by the
1.111 + * LAST-MODIFIED property value in the data. Otherwise, the initial value
1.112 + * is not set.
1.113 + * @param zone, the vzone to use
1.114 + * @param lastModified Receives the last modified date.
1.115 + * @return TRUE if lastModified attribute is available and value is set.
1.116 + */
1.117 +U_CAPI UBool U_EXPORT2
1.118 +vzone_getLastModified(VZone* zone, UDate& lastModified);
1.119 +
1.120 +/**
1.121 + * Sets the RFC2445 LAST-MODIFIED property value.
1.122 + * @param zone, the vzone to use
1.123 + * @param lastModified The LAST-MODIFIED date.
1.124 + */
1.125 +U_CAPI void U_EXPORT2
1.126 +vzone_setLastModified(VZone* zone, UDate lastModified);
1.127 +
1.128 +/**
1.129 + * Writes RFC2445 VTIMEZONE data for this time zone
1.130 + * @param zone, the vzone to use
1.131 + * @param result Output param to filled in with the VTIMEZONE data.
1.132 + * @param resultLength, length of the result output
1.133 + * @param status Output param to filled in with a success or an error.
1.134 + */
1.135 +U_CAPI void U_EXPORT2
1.136 +vzone_write(VZone* zone, UChar* & result, int32_t & resultLength, UErrorCode& status);
1.137 +
1.138 +/**
1.139 + * Writes RFC2445 VTIMEZONE data for this time zone applicalbe
1.140 + * for dates after the specified start time.
1.141 + * @param zone, the vzone to use
1.142 + * @param start The start date.
1.143 + * @param result Output param to filled in with the VTIMEZONE data.
1.144 + * @param resultLength, length of the result output
1.145 + * @param status Output param to filled in with a success or an error.
1.146 + */
1.147 +U_CAPI void U_EXPORT2
1.148 +vzone_writeFromStart(VZone* zone, UDate start, UChar* & result, int32_t & resultLength, UErrorCode& status);
1.149 +
1.150 +/**
1.151 + * Writes RFC2445 VTIMEZONE data applicalbe for the specified date.
1.152 + * Some common iCalendar implementations can only handle a single time
1.153 + * zone property or a pair of standard and daylight time properties using
1.154 + * BYDAY rule with day of week (such as BYDAY=1SUN). This method produce
1.155 + * the VTIMEZONE data which can be handled these implementations. The rules
1.156 + * produced by this method can be used only for calculating time zone offset
1.157 + * around the specified date.
1.158 + * @param zone, the vzone to use
1.159 + * @param time The date used for rule extraction.
1.160 + * @param result Output param to filled in with the VTIMEZONE data.
1.161 + * @param status Output param to filled in with a success or an error.
1.162 + */
1.163 +U_CAPI void U_EXPORT2
1.164 +vzone_writeSimple(VZone* zone, UDate time, UChar* & result, int32_t & resultLength, UErrorCode& status);
1.165 +
1.166 +/**
1.167 + * Returns the TimeZone's adjusted GMT offset (i.e., the number of milliseconds to add
1.168 + * to GMT to get local time in this time zone, taking daylight savings time into
1.169 + * account) as of a particular reference date. The reference date is used to determine
1.170 + * whether daylight savings time is in effect and needs to be figured into the offset
1.171 + * that is returned (in other words, what is the adjusted GMT offset in this time zone
1.172 + * at this particular date and time?). For the time zones produced by createTimeZone(),
1.173 + * the reference data is specified according to the Gregorian calendar, and the date
1.174 + * and time fields are local standard time.
1.175 + *
1.176 + * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) overload,
1.177 + * which returns both the raw and the DST offset for a given time. This method
1.178 + * is retained only for backward compatibility.
1.179 + *
1.180 + * @param zone, the vzone to use
1.181 + * @param era The reference date's era
1.182 + * @param year The reference date's year
1.183 + * @param month The reference date's month (0-based; 0 is January)
1.184 + * @param day The reference date's day-in-month (1-based)
1.185 + * @param dayOfWeek The reference date's day-of-week (1-based; 1 is Sunday)
1.186 + * @param millis The reference date's milliseconds in day, local standard time
1.187 + * @param status Output param to filled in with a success or an error.
1.188 + * @return The offset in milliseconds to add to GMT to get local time.
1.189 + */
1.190 +U_CAPI int32_t U_EXPORT2
1.191 +vzone_getOffset(VZone* zone, uint8_t era, int32_t year, int32_t month, int32_t day,
1.192 + uint8_t dayOfWeek, int32_t millis, UErrorCode& status);
1.193 +
1.194 +/**
1.195 + * Gets the time zone offset, for current date, modified in case of
1.196 + * daylight savings. This is the offset to add *to* UTC to get local time.
1.197 + *
1.198 + * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) overload,
1.199 + * which returns both the raw and the DST offset for a given time. This method
1.200 + * is retained only for backward compatibility.
1.201 + *
1.202 + * @param zone, the vzone to use
1.203 + * @param era The reference date's era
1.204 + * @param year The reference date's year
1.205 + * @param month The reference date's month (0-based; 0 is January)
1.206 + * @param day The reference date's day-in-month (1-based)
1.207 + * @param dayOfWeek The reference date's day-of-week (1-based; 1 is Sunday)
1.208 + * @param millis The reference date's milliseconds in day, local standard time
1.209 + * @param monthLength The length of the given month in days.
1.210 + * @param status Output param to filled in with a success or an error.
1.211 + * @return The offset in milliseconds to add to GMT to get local time.
1.212 + */
1.213 +U_CAPI int32_t U_EXPORT2
1.214 +vzone_getOffset2(VZone* zone, uint8_t era, int32_t year, int32_t month, int32_t day,
1.215 + uint8_t dayOfWeek, int32_t millis,
1.216 + int32_t monthLength, UErrorCode& status);
1.217 +
1.218 +/**
1.219 + * Returns the time zone raw and GMT offset for the given moment
1.220 + * in time. Upon return, local-millis = GMT-millis + rawOffset +
1.221 + * dstOffset. All computations are performed in the proleptic
1.222 + * Gregorian calendar. The default implementation in the TimeZone
1.223 + * class delegates to the 8-argument getOffset().
1.224 + *
1.225 + * @param zone, the vzone to use
1.226 + * @param date moment in time for which to return offsets, in
1.227 + * units of milliseconds from January 1, 1970 0:00 GMT, either GMT
1.228 + * time or local wall time, depending on `local'.
1.229 + * @param local if true, `date' is local wall time; otherwise it
1.230 + * is in GMT time.
1.231 + * @param rawOffset output parameter to receive the raw offset, that
1.232 + * is, the offset not including DST adjustments
1.233 + * @param dstOffset output parameter to receive the DST offset,
1.234 + * that is, the offset to be added to `rawOffset' to obtain the
1.235 + * total offset between local and GMT time. If DST is not in
1.236 + * effect, this value is zero; otherwise it is a positive value,
1.237 + * typically one hour.
1.238 + * @param ec input-output error code
1.239 + */
1.240 +U_CAPI void U_EXPORT2
1.241 +vzone_getOffset3(VZone* zone, UDate date, UBool local, int32_t& rawOffset,
1.242 + int32_t& dstOffset, UErrorCode& ec);
1.243 +
1.244 +/**
1.245 + * Sets the TimeZone's raw GMT offset (i.e., the number of milliseconds to add
1.246 + * to GMT to get local time, before taking daylight savings time into account).
1.247 + *
1.248 + * @param zone, the vzone to use
1.249 + * @param offsetMillis The new raw GMT offset for this time zone.
1.250 + */
1.251 +U_CAPI void U_EXPORT2
1.252 +vzone_setRawOffset(VZone* zone, int32_t offsetMillis);
1.253 +
1.254 +/**
1.255 + * Returns the TimeZone's raw GMT offset (i.e., the number of milliseconds to add
1.256 + * to GMT to get local time, before taking daylight savings time into account).
1.257 + *
1.258 + * @param zone, the vzone to use
1.259 + * @return The TimeZone's raw GMT offset.
1.260 + */
1.261 +U_CAPI int32_t U_EXPORT2
1.262 +vzone_getRawOffset(VZone* zone);
1.263 +
1.264 +/**
1.265 + * Queries if this time zone uses daylight savings time.
1.266 + * @param zone, the vzone to use
1.267 + * @return true if this time zone uses daylight savings time,
1.268 + * false, otherwise.
1.269 + */
1.270 +U_CAPI UBool U_EXPORT2
1.271 +vzone_useDaylightTime(VZone* zone);
1.272 +
1.273 +/**
1.274 + * Queries if the given date is in daylight savings time in
1.275 + * this time zone.
1.276 + * This method is wasteful since it creates a new GregorianCalendar and
1.277 + * deletes it each time it is called. This is a deprecated method
1.278 + * and provided only for Java compatibility.
1.279 + *
1.280 + * @param zone, the vzone to use
1.281 + * @param date the given UDate.
1.282 + * @param status Output param filled in with success/error code.
1.283 + * @return true if the given date is in daylight savings time,
1.284 + * false, otherwise.
1.285 + */
1.286 +U_INTERNAL UBool U_EXPORT2
1.287 +vzone_inDaylightTime(VZone* zone, UDate date, UErrorCode& status);
1.288 +
1.289 +/**
1.290 + * Returns true if this zone has the same rule and offset as another zone.
1.291 + * That is, if this zone differs only in ID, if at all.
1.292 + * @param zone, the vzone to use
1.293 + * @param other the <code>TimeZone</code> object to be compared with
1.294 + * @return true if the given zone is the same as this one,
1.295 + * with the possible exception of the ID
1.296 + */
1.297 +U_CAPI UBool U_EXPORT2
1.298 +vzone_hasSameRules(VZone* zone, const VZone* other);
1.299 +
1.300 +/**
1.301 + * Gets the first time zone transition after the base time.
1.302 + * @param zone, the vzone to use
1.303 + * @param base The base time.
1.304 + * @param inclusive Whether the base time is inclusive or not.
1.305 + * @param result Receives the first transition after the base time.
1.306 + * @return TRUE if the transition is found.
1.307 + */
1.308 +U_CAPI UBool U_EXPORT2
1.309 +vzone_getNextTransition(VZone* zone, UDate base, UBool inclusive, ZTrans* result);
1.310 +
1.311 +/**
1.312 + * Gets the most recent time zone transition before the base time.
1.313 + * @param zone, the vzone to use
1.314 + * @param base The base time.
1.315 + * @param inclusive Whether the base time is inclusive or not.
1.316 + * @param result Receives the most recent transition before the base time.
1.317 + * @return TRUE if the transition is found.
1.318 + */
1.319 +U_CAPI UBool U_EXPORT2
1.320 +vzone_getPreviousTransition(VZone* zone, UDate base, UBool inclusive, ZTrans* result);
1.321 +
1.322 +/**
1.323 + * Returns the number of <code>TimeZoneRule</code>s which represents time transitions,
1.324 + * for this time zone, that is, all <code>TimeZoneRule</code>s for this time zone except
1.325 + * <code>InitialTimeZoneRule</code>. The return value range is 0 or any positive value.
1.326 + * @param zone, the vzone to use
1.327 + * @param status Receives error status code.
1.328 + * @return The number of <code>TimeZoneRule</code>s representing time transitions.
1.329 + */
1.330 +U_CAPI int32_t U_EXPORT2
1.331 +vzone_countTransitionRules(VZone* zone, UErrorCode& status);
1.332 +
1.333 +/**
1.334 + * Return the class ID for this class. This is useful only for comparing to
1.335 + * a return value from getDynamicClassID(). For example:
1.336 + * <pre>
1.337 + * . Base* polymorphic_pointer = createPolymorphicObject();
1.338 + * . if (polymorphic_pointer->getDynamicClassID() ==
1.339 + * . erived::getStaticClassID()) ...
1.340 + * </pre>
1.341 + * @param zone, the vzone to use
1.342 + * @return The class ID for all objects of this class.
1.343 + */
1.344 +U_CAPI UClassID U_EXPORT2
1.345 +vzone_getStaticClassID(VZone* zone);
1.346 +
1.347 +/**
1.348 + * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This
1.349 + * method is to implement a simple version of RTTI, since not all C++
1.350 + * compilers support genuine RTTI. Polymorphic operator==() and clone()
1.351 + * methods call this method.
1.352 + *
1.353 + * @param zone, the vzone to use
1.354 + * @return The class ID for this object. All objects of a
1.355 + * given class have the same class ID. Objects of
1.356 + * other classes have different class IDs.
1.357 + */
1.358 +U_CAPI UClassID U_EXPORT2
1.359 +vzone_getDynamicClassID(VZone* zone);
1.360 +
1.361 +#endif // __VZONE_H
1.362 +
1.363 +#endif
