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
25struct 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 */
31typedef 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 */
46U_DRAFT VZone* U_EXPORT2
47vzone_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 */
58U_DRAFT VZone* U_EXPORT2
59vzone_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 */
67U_DRAFT void U_EXPORT2
68vzone_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 */
76U_DRAFT VZone* U_EXPORT2
77vzone_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 */
87U_DRAFT UBool U_EXPORT2
88vzone_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 */
100U_DRAFT UBool U_EXPORT2
101vzone_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 */
110U_DRAFT void U_EXPORT2
111vzone_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 */
123U_DRAFT UBool U_EXPORT2
124vzone_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 */
132U_DRAFT void U_EXPORT2
133vzone_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 */
143U_DRAFT void U_EXPORT2
144vzone_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 */
156U_DRAFT void U_EXPORT2
157vzone_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 */
173U_DRAFT void U_EXPORT2
174vzone_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 */
201U_DRAFT int32_t U_EXPORT2
202vzone_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 */
225U_DRAFT int32_t U_EXPORT2
226vzone_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 */
253U_DRAFT void U_EXPORT2
254vzone_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 */
265U_DRAFT void U_EXPORT2
266vzone_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 */
276U_DRAFT int32_t U_EXPORT2
277vzone_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 */
286U_DRAFT UBool U_EXPORT2
287vzone_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 */
303U_DRAFT UBool U_EXPORT2
304vzone_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 */
315U_DRAFT UBool U_EXPORT2
316vzone_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 */
327U_DRAFT UBool U_EXPORT2
328vzone_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 */
339U_DRAFT UBool U_EXPORT2
340vzone_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 */
351U_DRAFT int32_t U_EXPORT2
352vzone_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 */
366U_DRAFT UClassID U_EXPORT2
367vzone_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 */
381U_DRAFT UClassID U_EXPORT2
382vzone_getDynamicClassID(VZone* zone);
383
384#endif // __VZONE_H
385
386#endif
387