src/include/wearable/utils_i18n_ucalendar.h

   1 /*
   2  * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  *    Licensed under the Apache License, Version 2.0 (the "License");
   5  *    you may not use this file except in compliance with the License.
   6  *    You may obtain a copy of the License at
   7  *
   8  *        http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  *    Unless required by applicable law or agreed to in writing, software
  11  *    distributed under the License is distributed on an "AS IS" BASIS,
  12  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  *    See the License for the specific language governing permissions and
  14  *    limitations under the License.
  15  */
  16
  17 #ifndef __UTILS_I18N_UCALENDAR_H__
  18 #define __UTILS_I18N_UCALENDAR_H__
  19
  20 #include <utils_i18n_types.h>
  21
  22 /**
  23  * @file utils_i18n_ucalendar.h
  24  * @version 0.1
  25  * @brief utils_i18n_ucalendar
  26  */
  27
  28 /**
  29  * @ingroup CAPI_BASE_UTILS_I18N_MODULE
  30  * @defgroup CAPI_BASE_UTILS_I18N_UCALENDAR_MODULE Ucalendar
  31  * @brief The Ucalendar is used for converting between an udate module and a set of integer fields
  32  *       such as #I18N_UCALENDAR_YEAR, #I18N_UCALENDAR_MONTH, #I18N_UCALENDAR_DATE, #I18N_UCALENDAR_HOUR, and so on.
  33  * @section CAPI_BASE_UTILS_I18N_UCALENDAR_MODULE_HEADER Required Header
  34  *  \#include <utils_i18n.h>
  35  * @section CAPI_BASE_UTILS_I18N_UCALENDAR_MODULE_OVERVIEW Overview
  36  * @details The Ucalendar is used for converting between an udate module and a set of integer fields
  37  *       such as #I18N_UCALENDAR_YEAR, #I18N_UCALENDAR_MONTH, #I18N_UCALENDAR_DATE, #I18N_UCALENDAR_HOUR, and so on.
  38  *       (An udate module represents a specific instant in time with millisecond precision. See udate for
  39  *       information about the udate.)
  40  *
  41  * @section CAPI_BASE_UTILS_I18N_UCALENDAR_MODULE_SAMPLE_CODE_1 Sample Code 1
  42  * @brief Converts the given date and time to the corresponding UTC time(number of seconds that have elapsed since January 1, 1970), considering the given time zone
  43  * @code
  44
  45  #define ms2sec(ms) (long long int)(ms)/1000.0
  46
  47   // get time in sec from input date and time
  48   long long int _time_convert_itol(char *tzid, int y, int mon, int d, int h, int min, int s)
  49  {
  50      long long int lli;
  51      i18n_ucalendar_h ucal;
  52      i18n_udate date;
  53      int ret = I18N_ERROR_NONE;
  54      int year, month, day, hour, minute, second;
  55      int len;
  56
  57      i18n_uchar *_tzid = NULL;
  58
  59      if (tzid == NULL) {
  60          tzid = "Etc/GMT";
  61      }
  62      _tzid = (i18n_uchar*)calloc(strlen(tzid) + 1, sizeof(i18n_uchar));
  63      if (_tzid == NULL) {
  64          return -1;
  65      }
  66      // converts 'tzid' to unicode string
  67      i18n_ustring_copy_ua(_tzid, tzid);
  68
  69      // gets length of '_tzid'
  70      i18n_ustring_get_length(_tzid, &len);
  71      // creates i18n_ucalendar_h
  72      ret = i18n_ucalendar_create(_tzid, len, "en_US", I18N_UCALENDAR_TRADITIONAL, &ucal);
  73      if (ret) {
  74          dlog_print(DLOG_INFO, LOG_TAG, "i18n_ucalendar_create failed.\n");
  75          return -1;
  76      }
  77
  78      // sets i18n_ucalendar_h's date
  79      i18n_ucalendar_set_date_time(ucal, y, mon-1, d, h, min, s);
  80
  81      // gets the current value of a field from i18n_ucalendar_h
  82      i18n_ucalendar_get(ucal, I18N_UCALENDAR_YEAR, &year);
  83      i18n_ucalendar_get(ucal, I18N_UCALENDAR_MONTH, &month);
  84      i18n_ucalendar_get(ucal, I18N_UCALENDAR_DATE, &day);
  85      i18n_ucalendar_get(ucal, I18N_UCALENDAR_HOUR, &hour);
  86      i18n_ucalendar_get(ucal, I18N_UCALENDAR_MINUTE, &minute);
  87      i18n_ucalendar_get(ucal, I18N_UCALENDAR_SECOND, &second);
  88      dlog_print(DLOG_INFO, LOG_TAG, "Date from ucal, year:%d month:%d day:%d hour:%d minute:%d second:%d.\n",year, month, day, hour, minute, second);
  89
  90      // gets i18n_ucalendar's current time and converts it from milliseconds to seconds
  91      i18n_ucalendar_get_milliseconds(ucal, &date);
  92      lli = ms2sec(date);
  93      // destroys i18n_ucalendar_h
  94      i18n_ucalendar_destroy(ucal);
  95      if (_tzid) {
  96          free(_tzid);
  97      }
  98
  99      return lli;
 100  }
 101  * @endcode
 102  *
 103  * @section CAPI_BASE_UTILS_I18N_UCALENDAR_MODULE_SAMPLE_CODE_2 Sample Code 2
 104  * @brief Describes an example that uses _time_convert_itol from 'Sample Code 2'
 105  * @code
 106        // converts the given time to UTC time(number of seconds that have elapsed since January 1, 1970)
 107      long long int time = _time_convert_itol("Etc/GMT", 2014, 5, 28, 15, 14, 0);
 108      dlog_print(DLOG_INFO, LOG_TAG, "Time Zone: %s\t, %d/%d/%d/%d/%d/%d\n", "Etc/GMT", 2014, 5, 28, 15, 14, 0);
 109      dlog_print(DLOG_INFO, LOG_TAG, "_time_convert_itol test : %lld\n", time);
 110  * @endcode
 111  */
 112
 113 #ifdef __cplusplus
 114 extern "C" {
 115 #endif
 116
 117 /**
 118  * @addtogroup CAPI_BASE_UTILS_I18N_UCALENDAR_MODULE
 119  * @{
 120  */
 121
 122 /**
 123  * @brief Sets the default time zone.
 124  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 125  *
 126  * @param[in] zone_id null-terminated time zone ID
 127  *
 128  * @return An #i18n_error_code_e error code
 129  * @retval #I18N_ERROR_NONE Successful
 130  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 131  */
 132 int i18n_ucalendar_set_default_timezone ( const i18n_uchar *zone_id );
 133
 134 /**
 135  * @brief Gets the current date and time.
 136  * @details The value returned is represented as milliseconds from the epoch.
 137  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 138  *
 139  * @param[out] date The current date and time
 140  *
 141  * @retval #I18N_ERROR_NONE Successful
 142  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 143  */
 144 int i18n_ucalendar_get_now ( i18n_udate *date );
 145
 146 /**
 147  * @brief Creates an #i18n_ucalendar_h.
 148  * An #i18n_ucalendar_h may be used to convert a millisecond value to a year,
 149  * month, and day.
 150  * @details Note: When an unknown TimeZone ID is specified, the #i18n_ucalendar_h returned
 151  * by the function is initialized with GMT ("Etc/GMT") without any
 152  * errors/warnings.
 153  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 154  * @remarks Must release @a calendar using i18n_ucalendar_destroy().
 155  *
 156  * @param[in] zone_id The desired TimeZone ID \n
 157  *                    If @c 0, use the default time zone.
 158  * @param[in] len The length of the zone ID,
 159  *                    otherwise @c -1 if null-terminated
 160  * @param[in] locale The desired locale
 161  *                  If @c NULL, the default locale will be used.
 162  * @param[in] type The type of #I18N_UCALENDAR_DEFAULT to create \n
 163  *                  This can be #I18N_UCALENDAR_GREGORIAN to create the Gregorian
 164  * calendar for the locale, or #I18N_UCALENDAR_DEFAULT to create the default calendar for the locale (the
 165  * default calendar may also be Gregorian).
 166  * @param[out] calendar A pointer to an #i18n_ucalendar_h,
 167  *                    otherwise @c 0 if an error occurs
 168  *
 169  * @return An #i18n_error_code_e error code
 170  * @retval #I18N_ERROR_NONE Successful
 171  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 172  * @retval #I18N_ERROR_OUT_OF_MEMORY Out of memory
 173  */
 174 int i18n_ucalendar_create ( const i18n_uchar *zone_id, int32_t len, const char *locale, i18n_ucalendar_type_e type, i18n_ucalendar_h *calendar );
 175
 176 /**
 177  * @brief Destroys an #i18n_ucalendar_h.
 178  * @details Once destroyed, an #i18n_ucalendar_h may no longer be used.
 179  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 180  *
 181  * @param[in] calendar The #i18n_ucalendar_h to destroy
 182  * @retval #I18N_ERROR_NONE Successful
 183  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 184  */
 185 int i18n_ucalendar_destroy ( i18n_ucalendar_h calendar );
 186
 187 /**
 188  * @brief Creates a copy of a #i18n_ucalendar_h.
 189  * This function performs a deep copy.
 190  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 191  *
 192  * @param[in] cal The #i18n_ucalendar_h to copy
 193  * @param[out] identical_to_cal A pointer to a #i18n_ucalendar_h identical to @a cal.
 194  * @retval #I18N_ERROR_NONE Successful
 195  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 196  */
 197 int i18n_ucalendar_clone ( const i18n_ucalendar_h cal, i18n_ucalendar_h *identical_to_cal );
 198
 199 /**
 200  * @brief Gets the display name for a calendar's TimeZone.
 201  * @details A display name is suitable for presentation to a user.
 202  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 203  *
 204  * @param[in] calendar     The #i18n_ucalendar_h to query
 205  * @param[in] type         The desired display name format \n
 206  *                         One of #I18N_UCALENDAR_STANDARD, #I18N_UCALENDAR_SHORT_STANDARD, #I18N_UCALENDAR_DST, or #I18N_UCALENDAR_SHORT_DST
 207  * @param[in] locale       The desired locale for the display name
 208  * @param[out] result      A pointer to a buffer to receive the formatted number
 209  * @param[in] result_len The maximum size of the result
 210  * @param[out] buf_size_needed The total buffer size needed \n
 211  *              If greater than @a result_len, the output is truncated
 212  *
 213  * @retval #I18N_ERROR_NONE Successful
 214  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 215  */
 216 int i18n_ucalendar_get_timezone_displayname ( const i18n_ucalendar_h calendar, i18n_ucalendar_displayname_type_e type, const char *locale, i18n_uchar *result, int32_t result_len, int32_t *buf_size_needed );
 217
 218 /**
 219  * @brief Determines if an #i18n_ucalendar_h is currently in daylight savings time.
 220  * @details Daylight savings time is not used in all parts of the world.
 221  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 222  *
 223  * @param[in] calendar The #i18n_ucalendar_h to query
 224  * @param[out] is_in   If @c true @a calendar is currently in daylight savings time,
 225  *                     otherwise @c false
 226  *
 227  * @retval #I18N_ERROR_NONE Successful
 228  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 229  */
 230 int i18n_ucalendar_is_in_daylight_time ( const i18n_ucalendar_h calendar, i18n_ubool *is_in );
 231
 232 /**
 233  * @brief Sets the value of a field in a #i18n_ucalendar_h.
 234  * @details All fields are represented as 32-bit integers.
 235  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 236  *
 237  * @param[in] cal The #i18n_ucalendar_h to modify
 238  * @param[in] field The field to set \n
 239  *              One of #I18N_UCALENDAR_ERA, #I18N_UCALENDAR_YEAR,
 240  * #I18N_UCALENDAR_MONTH, #I18N_UCALENDAR_WEEK_OF_YEAR, #I18N_UCALENDAR_WEEK_OF_MONTH,
 241  * #I18N_UCALENDAR_DATE, #I18N_UCALENDAR_DAY_OF_YEAR, #I18N_UCALENDAR_DAY_OF_WEEK,
 242  * #I18N_UCALENDAR_DAY_OF_WEEK_IN_MONTH, #I18N_UCALENDAR_AM_PM, #I18N_UCALENDAR_HOUR,
 243  * #I18N_UCALENDAR_HOUR_OF_DAY, #I18N_UCALENDAR_MINUTE, #I18N_UCALENDAR_SECOND,
 244  * #I18N_UCALENDAR_MILLISECOND, #I18N_UCALENDAR_ZONE_OFFSET, #I18N_UCALENDAR_DST_OFFSET.
 245  * @param[in] val The desired value of @a field.
 246  * @retval #I18N_ERROR_NONE Successful
 247  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 248  */
 249 int i18n_ucalendar_set ( i18n_ucalendar_h cal, i18n_ucalendar_date_fields_e field, int32_t val );
 250
 251 /**
 252  * @brief Sets a numeric attribute associated with an #i18n_ucalendar_h.
 253  * @details Numeric attributes include the first day of the week, or the minimal number
 254  * of days in the first week of the month.
 255  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 256  *
 257  * @param[in] calendar The #i18n_ucalendar_h to modify
 258  * @param[in] attr The desired attribute \n
 259  *              One of #I18N_UCALENDAR_LENIENT, #I18N_UCALENDAR_FIRST_DAY_OF_WEEK,
 260  * or #I18N_UCALENDAR_MINIMAL_DAYS_IN_FIRST_WEEK.
 261  *
 262  * @param[in] val The new value of @a attr
 263  * @retval #I18N_ERROR_NONE Successful
 264  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 265  */
 266 int i18n_ucalendar_set_attribute ( i18n_ucalendar_h calendar, i18n_ucalendar_attribute_e attr, int32_t val );
 267
 268 /**
 269  * @brief Gets a numeric attribute associated with an i18n_ucalendar.
 270  * @details Numeric attributes include the first day of the week, or the minimal numbers of days
 271  * in the first week of the month.
 272  *
 273  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 274  *
 275  * @param[in] calendar The i18n_ucalendar to query
 276  * @param[in] attr The desired attribute \n
 277  *              One of #I18N_UCALENDAR_LENIENT, #I18N_UCALENDAR_FIRST_DAY_OF_WEEK,
 278  * or #I18N_UCALENDAR_MINIMAL_DAYS_IN_FIRST_WEEK.
 279  *
 280  * @param[out] val The value of @a attr
 281  * @retval #I18N_ERROR_NONE Successful
 282  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 283  */
 284 int i18n_ucalendar_get_attribute ( i18n_ucalendar_h calendar, i18n_ucalendar_attribute_e attr, int32_t *val);
 285
 286 /**
 287  * @brief Gets a calendar's current time in milliseconds.
 288  * @details The time is represented as milliseconds from the epoch.
 289  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 290  *
 291  * @param[in] calendar The #i18n_ucalendar_h to query
 292  * @param[out] date The calendar's current time in milliseconds
 293  *
 294  * @retval #I18N_ERROR_NONE Successful
 295  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 296  * @see i18n_ucalendar_set_milliseconds()
 297  * @see i18n_ucalendar_set_date_time()
 298  */
 299 int i18n_ucalendar_get_milliseconds( const i18n_ucalendar_h calendar, i18n_udate *date );
 300
 301 /**
 302  * @brief Sets a calendar's current time in milliseconds.
 303  * @details The time is represented as milliseconds from the epoch.
 304  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 305  *
 306  * @param[in] calendar The #i18n_ucalendar_h to set
 307  * @param[in] milliseconds The desired date and time
 308  *
 309  * @retval #I18N_ERROR_NONE Successful
 310  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 311  * @see i18n_ucalendar_get_milliseconds()
 312  * @see i18n_ucalendar_set_date_time()
 313  */
 314 int i18n_ucalendar_set_milliseconds ( i18n_ucalendar_h calendar, i18n_udate milliseconds );
 315
 316 /**
 317  * @brief Sets a calendar's current date.
 318  * @details The date is represented as a series of 32-bit integers.
 319  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 320  *
 321  * @param[in] calendar The #i18n_ucalendar_h to set
 322  * @param[in] year The desired year
 323  * @param[in] month The desired month\n
 324  *          One of #I18N_UCALENDAR_JANUARY, #I18N_UCALENDAR_FEBRUARY, #I18N_UCALENDAR_MARCH, #I18N_UCALENDAR_APRIL, #I18N_UCALENDAR_MAY,
 325  *          #I18N_UCALENDAR_JUNE, #I18N_UCALENDAR_JULY, #I18N_UCALENDAR_AUGUST, #I18N_UCALENDAR_SEPTEMBER, #I18N_UCALENDAR_OCTOBER, #I18N_UCALENDAR_NOVEMBER, or #I18N_UCALENDAR_DECEMBER
 326  * @param[in] date The desired day of the month
 327  * @param[in] hour The desired hour of the day
 328  * @param[in] min The desired minute
 329  * @param[in] sec The desired second
 330  *
 331  * @retval #I18N_ERROR_NONE Successful
 332  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 333  * @see i18n_ucalendar_get_milliseconds()
 334  * @see i18n_ucalendar_set_milliseconds()
 335  */
 336 int i18n_ucalendar_set_date_time ( i18n_ucalendar_h calendar, int32_t year, int32_t month, int32_t date, int32_t hour, int32_t min, int32_t sec );
 337
 338 /**
 339  * @brief Returns @c true if two #i18n_ucalendar_h calendars are equivalent.
 340  * @details Equivalent #i18n_ucalendar_h calendars will behave identically, but they may be set to
 341  * different times.
 342  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 343  *
 344  * @param[in] calendar1 The first of the calendars to compare
 345  * @param[in] calendar2 The second of the calendars to compare
 346  * @param[out] equiv If @c true @a cal1 and @a cal2 are equivalent, otherwise @c false
 347  *
 348  * @retval #I18N_ERROR_NONE Successful
 349  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 350  */
 351 int i18n_ucalendar_is_equivalent_to ( const i18n_ucalendar_h calendar1, const i18n_ucalendar_h calendar2, i18n_ubool *equiv );
 352
 353 /**
 354  * @brief Adds a specified signed amount to a particular field in a #i18n_ucalendar_h.
 355  * @details This can modify more significant fields in the calendar.
 356  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 357  *
 358  * @param[in] calendar The #i18n_ucalendar_h to which to add
 359  * @param[in] field The field to which to add the signed value\n One of #I18N_UCALENDAR_ERA, #I18N_UCALENDAR_YEAR, #I18N_UCALENDAR_MONTH,
 360  * #I18N_UCALENDAR_WEEK_OF_YEAR, #I18N_UCALENDAR_WEEK_OF_MONTH, #I18N_UCALENDAR_DATE, #I18N_UCALENDAR_DAY_OF_YEAR, #I18N_UCALENDAR_DAY_OF_WEEK,
 361  * #I18N_UCALENDAR_DAY_OF_WEEK_IN_MONTH, #I18N_UCALENDAR_AM_PM, #I18N_UCALENDAR_HOUR, #I18N_UCALENDAR_HOUR_OF_DAY, #I18N_UCALENDAR_MINUTE, #I18N_UCALENDAR_SECOND,
 362  * #I18N_UCALENDAR_MILLISECOND.
 363  * @param[in] amount The signed amount to add to the field \n
 364  *              If the amount causes the value to exceed to maximum or minimum values for that field,
 365  *              other fields are modified to preserve the magnitude of the change.
 366  *
 367  * @retval #I18N_ERROR_NONE Successful
 368  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 369
 370  */
 371 int i18n_ucalendar_add ( i18n_ucalendar_h calendar, i18n_ucalendar_date_fields_e field, int32_t amount );
 372
 373 /**
 374  * @brief Gets the current value of a field from an #i18n_ucalendar_h.
 375  * @details All fields are represented as 32-bit integers.
 376  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 377  *
 378  * @param[in] calendar The #i18n_ucalendar_h to query
 379  * @param[in] field The desired field\n One of I18N_UCALENDAR_ERA, I18N_UCALENDAR_YEAR, I18N_UCALENDAR_MONTH,
 380  * #I18N_UCALENDAR_WEEK_OF_YEAR, #I18N_UCALENDAR_WEEK_OF_MONTH, #I18N_UCALENDAR_DATE, #I18N_UCALENDAR_DAY_OF_YEAR, #I18N_UCALENDAR_DAY_OF_WEEK,
 381  * #I18N_UCALENDAR_DAY_OF_WEEK_IN_MONTH, #I18N_UCALENDAR_AM_PM, #I18N_UCALENDAR_HOUR, #I18N_UCALENDAR_HOUR_OF_DAY, #I18N_UCALENDAR_MINUTE, #I18N_UCALENDAR_SECOND,
 382  * #I18N_UCALENDAR_MILLISECOND, #I18N_UCALENDAR_ZONE_OFFSET, or #I18N_UCALENDAR_DST_OFFSET.
 383  * @param[out] val The value of the desired field.
 384  *
 385  * @retval #I18N_ERROR_NONE Successful
 386  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 387  */
 388 int i18n_ucalendar_get ( const i18n_ucalendar_h calendar, i18n_ucalendar_date_fields_e field, int32_t *val );
 389
 390
 391 // Newly Added APIs
 392
 393
 394
 395 /**
 396  * @brief Returns the difference between the target time and the time this calendar object is currently set to.
 397  * @details If the target time is after the current calendar setting, the the returned value will be positive.
 398  *          The field parameter specifies the units of the return value.
 399  *          For example, if field is I18N_UCALENDAR_MONTH and i18n_ucalendar_get_field_difference returns 3,
 400  *          then the target time is 3 to less than 4 months after the current calendar setting. <br>
 401  *          As a side effect of this call, this calendar is advanced toward target by the given amount.
 402  *          That is, calling this function has the side effect of calling i18n_ucalendar_add on this calendar with the
 403  *          specified field and an amount equal to the return value from this function. <br>
 404  *          A typical way of using this function is to call it first with the largest field of interest, then with progressively smaller fields.
 405  * @since_tizen 2.3.1
 406  *
 407  * @param[in] calendar The i18n_ucalendar_h to compare and update.
 408  * @param[in] target   The target date to compare to the current calendar setting.
 409  * @param[in] field    One of #I18N_UCALENDAR_ERA, #I18N_UCALENDAR_YEAR, #I18N_UCALENDAR_MONTH,
 410  *                     #I18N_UCALENDAR_WEEK_OF_YEAR, #I18N_UCALENDAR_WEEK_OF_MONTH, #I18N_UCALENDAR_DATE,
 411  *                     #I18N_UCALENDAR_DAY_OF_YEAR, #I18N_UCALENDAR_DAY_OF_WEEK, #I18N_UCALENDAR_DAY_OF_WEEK_IN_MONTH,
 412  *                     #I18N_UCALENDAR_AM_PM, #I18N_UCALENDAR_HOUR, #I18N_UCALENDAR_HOUR_OF_DAY, #I18N_UCALENDAR_MINUTE,
 413  *                     #I18N_UCALENDAR_SECOND, #I18N_UCALENDAR_MILLISECOND.
 414  *                     <strong>Please note</strong> that the returned value type is int32_t. In case of #I18N_UCALENDAR_MILLISECOND, maximal
 415  *                     difference between dates may be equal to the maximal value of the int32_t, which is 2147483647 (about one month difference).
 416  *                     If the difference is bigger, then the #I18N_ERROR_INVALID_PARAMETER error will be returned.
 417  * @param[out] status  A pointer to an i18n_error_code_e to receive any errors
 418  *
 419  * @return The date difference for the specified field.
 420  */
 421 int32_t i18n_ucalendar_get_field_difference ( i18n_ucalendar_h calendar, i18n_udate target, i18n_ucalendar_date_fields_e field, i18n_error_code_e *status );
 422
 423 /**
 424  * @brief Creates an enumeration over system time zone IDs with the given filter conditions.
 425  * @since_tizen 2.3.1
 426  *
 427  * @param[in] zone_type The system time zone type.
 428  * @param[in] region The ISO 3166 two-letter country code or UN M.49 three-digit
 429  *      area code. When @c NULL, no filtering done by region.
 430  * @param[in] raw_offset An offset from GMT in milliseconds, ignoring the effect
 431  *      of daylight savings time, if any. When @c NULL, no filtering done by zone offset.
 432  *
 433  * @param[out] enumeration A Pointer to the enumeration object that the caller must dispose of using
 434  *      i18n_uenumeration_destroy(), or@c  NULL upon failure.
 435  *
 436  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 437  * @retval #I18N_ERROR_NONE Successful
 438  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 439  */
 440 int i18n_ucalendar_timezone_id_enumeration_create ( i18n_system_timezone_type_e zone_type, const char *region, const int32_t *raw_offset, i18n_uenumeration_h *enumeration);
 441
 442 /**
 443  * @brief Creates an enumeration over all time zones.
 444  * @since_tizen 2.3.1
 445  *
 446  * @param[out] enumeration A pointer to the enumeration object that the caller must dispose of using
 447  *      i18n_uenumeration_destroy(), or @c NULL upon failure.
 448  *
 449  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 450  * @retval #I18N_ERROR_NONE Successful
 451  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 452  */
 453 int i18n_ucalendar_timezones_create (i18n_uenumeration_h * enumeration);
 454
 455 /**
 456  * @brief Creates an enumeration over all time zones associated with the given country.
 457  * @details Some zones are affiliated with no country (e.g., "UTC"); these may also be retrieved, as a group.
 458  * @since_tizen 2.3.1
 459  *
 460  * @param[in] country The ISO 3166 two-letter country code, or @c NULL to retrieve zones not affiliated with any country
 461  *
 462  * @param[out] enumeration A pointer to the enumeration object that the caller must dispose of using
 463  *      i18n_uenumeration_destroy(), or @c NULL upon failure.
 464  *
 465  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 466  * @retval #I18N_ERROR_NONE Successful
 467  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 468  */
 469 int i18n_ucalendar_country_timezones_create (const char *country, i18n_uenumeration_h * enumeration);
 470
 471 /**
 472  * @brief Returns the default time zone.
 473  * @details The default is determined initially by querying the host operating system.
 474  *      It may be changed with i18n_ucalendar_set_default_timezone()
 475  *      or with the C++ TimeZone API.
 476  * @remarks The specific error code can be obtained using the get_last_result()
 477  *      method. Error codes are described in #i18n_error_code_e description.
 478  * @since_tizen 2.3.1
 479  *
 480  * @param[out] result A buffer to receive the result, or @c NULL
 481  * @param[in]     result_capacity The capacity of the @c result buffer
 482  *
 483  * @return The @c result string length, not including the terminating @c NULL.
 484  * @exception #I18N_ERROR_NONE Successful
 485  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid parameter
 486  */
 487 int32_t i18n_ucalendar_get_default_timezone (i18n_uchar *result, int32_t result_capacity);
 488
 489 /**
 490  * @brief Sets the TimeZone used by a #i18n_ucalendar_h.
 491  * @details A #i18n_ucalendar_h uses a timezone for converting from Greenwich time to local time.
 492  * @since_tizen 2.3.1
 493  *
 494  * @param[in] calendar The #i18n_ucalendar_h to set.
 495  * @param[in] zone_id The desired TimeZone ID. If NULL, use the default time zone.
 496  * @param[in] length The length of @c zone_id, or -1 if NULL-terminated.
 497  *
 498  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 499  * @retval #I18N_ERROR_NONE Successful
 500  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 501  */
 502 int i18n_ucalendar_set_timezone ( i18n_ucalendar_h calendar, const i18n_uchar *zone_id, int32_t length );
 503
 504 /**
 505  * @brief Gets the ID of the calendar's time zone.
 506  * @remarks The specific error code can be obtained using the get_last_result()
 507  *      method. Error codes are described in Exceptions section and
 508  *      #i18n_error_code_e description.
 509  * @since_tizen 2.3.1
 510  *
 511  * @param[in] calendar The #i18n_ucalendar_h to query.
 512  * @param[out] result Receives the calendar's time zone ID.
 513  * @param[in] result_length The maximum size of the @c result.
 514  *
 515  * @return The total buffer size needed; if greater than @c result_length, the output was truncated.
 516  * @exception #I18N_ERROR_NONE Successful
 517  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 518  */
 519 int32_t i18n_ucalendar_get_timezone_id (const i18n_ucalendar_h calendar, i18n_uchar *result, int32_t result_length);
 520
 521 /**
 522  * @brief Sets the Gregorian Calendar change date.
 523  * @details This is the point when the switch from Julian dates to Gregorian dates
 524  *      occurred. Default is 00:00:00 local time, October 15, 1582.
 525  *      Previous to this time and date will be Julian dates.
 526  *      This function works only for Gregorian calendars. If the #i18n_ucalendar_h
 527  *      is not an instance of a Gregorian calendar, then a
 528  *      #I18N_ERROR_NOT_SUPPORTED error code is set.
 529  * @since_tizen 2.3.1
 530  *
 531  * @param[in] calendar The calendar object.
 532  * @param[in] date The given Gregorian cutover date.
 533  *
 534  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 535  * @retval #I18N_ERROR_NONE Successful
 536  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 537  *
 538  * @see i18n_ucalendar_get_gregorian_change()
 539  */
 540 int i18n_ucalendar_set_gregorian_change ( i18n_ucalendar_h calendar, i18n_udate date);
 541
 542 /**
 543  * @brief Gets the Gregorian Calendar change date.
 544  * @details This is the point when the switch from Julian dates to Gregorian dates
 545  *      occurred. Default is 00:00:00 local time, October 15, 1582.
 546  *      Previous to this time and date will be Julian dates.
 547  *      This function works only for Gregorian calendars. If the #i18n_ucalendar_h
 548  *      is not an instance of a Gregorian calendar, then a
 549  *      #I18N_ERROR_NOT_SUPPORTED error code is set.
 550  * @since_tizen 2.3.1
 551  *
 552  * @param[in] calendar The calendar object.
 553  * @param[out] date A pointer to the Gregorian cutover time for this calendar.
 554  *
 555  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 556  * @retval #I18N_ERROR_NONE Successful
 557  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 558  *
 559  * @see i18n_ucalendar_set_gregorian_change()
 560  */
 561 int i18n_ucalendar_get_gregorian_change (const i18n_ucalendar_h calendar, i18n_udate *date);
 562
 563 /**
 564  * @brief Gets a locale for which calendars are available.
 565  * @details A #i18n_ucalendar_h in a locale returned by this function will contain
 566  *      the correct day and month names for the locale.
 567  * @remarks The specific error code can be obtained using the get_last_result() method.
 568  *          Error codes are described in Exceptions section.
 569  * @since_tizen 2.3.1
 570  *
 571  * @param[in] locale_index The index of the desired locale.
 572  *
 573  * @return A locale for which calendars are available, or 0 if none.
 574  * @exception #I18N_ERROR_NONE Successful
 575  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid parameter
 576  * @see i18n_ucalendar_count_available()
 577  */
 578 const char * i18n_ucalendar_get_available (int32_t locale_index);
 579
 580 /**
 581  * @brief Determines how many locales have calendars available.
 582  * @details This function is most useful as determining the loop ending condition for calls to i18n_ucalendar_get_available().
 583  * @remarks The specific error code can be obtained using the get_last_result() method.
 584  *          Error codes are described in Exceptions section.
 585  * @since_tizen 2.3.1
 586  *
 587  * @return The number of locales for which calendars are available.
 588  * @exception #I18N_ERROR_NONE Successful
 589  * @see i18n_ucalendar_get_available()
 590  */
 591 int32_t i18n_ucalendar_count_available (void);
 592
 593 /**
 594  * @brief Sets a calendar's current date.
 595  * @details The date is represented as a series of 32-bit integers.
 596  * @since_tizen 2.3.1
 597  *
 598  * @param[in] calendar The #i18n_ucalendar_h to set.
 599  * @param[in] year The desired year.
 600  * @param[in] month The desired month; one of #I18N_UCALENDAR_JANUARY, #I18N_UCALENDAR_FEBRUARY, #I18N_UCALENDAR_MARCH,
 601  *      #I18N_UCALENDAR_APRIL, #I18N_UCALENDAR_MAY, #I18N_UCALENDAR_JUNE, #I18N_UCALENDAR_JULY, #I18N_UCALENDAR_AUGUST,
 602  *      #I18N_UCALENDAR_SEPTEMBER, #I18N_UCALENDAR_OCTOBER, #I18N_UCALENDAR_NOVEMBER, #I18N_UCALENDAR_DECEMBER
 603  * @param[in] date The desired day of the month.
 604  *
 605  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 606  * @retval #I18N_ERROR_NONE Successful
 607  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 608  *
 609  * @see i18n_ucalendar_add()
 610  * @see i18n_ucalendar_set_milliseconds()
 611  * @see i18n_ucalendar_set_milliseconds()
 612  * @see i18n_ucalendar_set_date_time()
 613  */
 614 int i18n_ucalendar_set_date (i18n_ucalendar_h calendar, int32_t year, int32_t month, int32_t date);
 615
 616 /**
 617  * @brief Adds a specified signed amount to a particular field in a #i18n_ucalendar_h.
 618  * @details This will not modify more significant fields in the calendar.
 619  *      Rolling by a positive value always means moving forward in time
 620  *      (unless the limit of the field is reached, in which case it may pin or wrap),
 621  *      so for Gregorian calendar, starting with 100 BC and
 622  *      rolling the year by +1 results in 99 BC.
 623  *      When eras have a definite beginning and end (as in the Chinese calendar,
 624  *      or as in most eras in the Japanese calendar) then rolling the year past either
 625  *      limit of the era will cause the year to wrap around. When eras only have a limit at one end,
 626  *      then attempting to roll the year past that limit will result in pinning the year at that limit.
 627  *      Note that for most calendars in which era 0 years move forward in time (such as Buddhist, Hebrew, or Islamic),
 628  *      it is possible for add or roll to result in negative years for era 0 (that is the
 629  *      only way to represent years before the calendar epoch).
 630  * @since_tizen 2.3.1
 631  *
 632  * @param[in] calendar The #i18n_ucalendar_h to which to add.
 633  * @param[in] field The field to which to add the signed value; one of #I18N_UCALENDAR_ERA,
 634  *      #I18N_UCALENDAR_YEAR, #I18N_UCALENDAR_MONTH, #I18N_UCALENDAR_WEEK_OF_YEAR,
 635  *      #I18N_UCALENDAR_WEEK_OF_MONTH, #I18N_UCALENDAR_DATE, #I18N_UCALENDAR_DAY_OF_YEAR,
 636  *      #I18N_UCALENDAR_DAY_OF_WEEK, #I18N_UCALENDAR_DAY_OF_WEEK_IN_MONTH, #I18N_UCALENDAR_AM_PM,
 637  *      #I18N_UCALENDAR_HOUR, #I18N_UCALENDAR_HOUR_OF_DAY, #I18N_UCALENDAR_MINUTE,
 638  *      #I18N_UCALENDAR_SECOND, #I18N_UCALENDAR_MILLISECOND.
 639  * @param[in] amount The signed amount to add to the @c field. If the amount causes the
 640  *      value to exceed to maximum or minimum values for that field, the field is pinned
 641  *      to a permissible value.
 642  *
 643  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 644  * @retval #I18N_ERROR_NONE Successful
 645  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 646  * @remarks #I18N_UCALENDAR_ZONE_OFFSET and #I18N_UCALENDAR_DST_OFFSET are not supported by this function.
 647  * @see i18n_ucalendar_add()
 648  */
 649 int i18n_ucalendar_roll (i18n_ucalendar_h calendar, i18n_ucalendar_date_fields_e field, int32_t amount);
 650
 651 /**
 652  * @brief Determines if a field in a #i18n_ucalendar_h is set.
 653  * @details All fields are represented as 32-bit integers.
 654  * @remarks The specific error code can be obtained using the get_last_result()
 655  *      method. Error codes are described in Exceptions section.
 656  * @since_tizen 2.3.1
 657  *
 658  * @param[in] calendar The #i18n_ucalendar_h to query.
 659  * @param[in] field    The desired field.
 660  *
 661  * @return @c true if field is set, @c false otherwise.
 662  * @exception #I18N_ERROR_NONE Successful
 663  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 664  * @see i18n_ucalendar_get()
 665  * @see i18n_ucalendar_set()
 666  * @see i18n_ucalendar_clear_field()
 667  * @see i18n_ucalendar_clear()
 668  *
 669  */
 670 i18n_ubool i18n_ucalendar_is_set (const i18n_ucalendar_h calendar, i18n_ucalendar_date_fields_e field);
 671
 672 /**
 673  * @brief Clears a field in a #i18n_ucalendar_h.
 674  * @details All fields are represented as 32-bit integers.
 675  * @since_tizen 2.3.1
 676  *
 677  * @param[in] calendar The #i18n_ucalendar_h containing the field to clear.
 678  * @param[in] field    The field to clear.
 679  *
 680  * @return Error code
 681  * @retval #I18N_ERROR_NONE Successful
 682  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 683  *
 684  * @see i18n_ucalendar_get()
 685  * @see i18n_ucalendar_set()
 686  * @see i18n_ucalendar_is_set()
 687  * @see i18n_ucalendar_clear()
 688  *
 689  */
 690 int i18n_ucalendar_clear_field (i18n_ucalendar_h calendar, i18n_ucalendar_date_fields_e field);
 691
 692 /**
 693  * @brief Clears all fields in a #i18n_ucalendar_h.
 694  * @details All fields are represented as 32-bit integers.
 695  * @since_tizen 2.3.1
 696  *
 697  * @param[in] calendar #i18n_ucalendar_h to clear.
 698  *
 699  * @return Error code
 700  * @retval #I18N_ERROR_NONE Successful
 701  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 702  *
 703  * @see i18n_ucalendar_is_set()
 704  * @see i18n_ucalendar_clear_field()
 705  *
 706  */
 707 int i18n_ucalendar_clear (i18n_ucalendar_h calendar);
 708
 709 /**
 710  * @brief Determines a limit for a field in an #i18n_ucalendar_h.
 711  * @details A limit is a maximum or minimum value for a field.
 712  * @remarks The specific error code can be obtained using the get_last_result() method.
 713  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 714  * @since_tizen 2.3.1
 715  *
 716  * @param[in] calendar The #i18n_ucalendar_h to query.
 717  * @param[in] field    The desired field; one of #I18N_UCALENDAR_ERA, #I18N_UCALENDAR_YEAR, #I18N_UCALENDAR_MONTH,
 718  *                     #I18N_UCALENDAR_WEEK_OF_YEAR, #I18N_UCALENDAR_WEEK_OF_MONTH, #I18N_UCALENDAR_DATE,
 719  *                     #I18N_UCALENDAR_DAY_OF_YEAR, #I18N_UCALENDAR_DAY_OF_WEEK, #I18N_UCALENDAR_DAY_OF_WEEK_IN_MONTH,
 720  *                     #I18N_UCALENDAR_AM_PM, #I18N_UCALENDAR_HOUR, #I18N_UCALENDAR_HOUR_OF_DAY,
 721  *                     #I18N_UCALENDAR_MINUTE, #I18N_UCALENDAR_SECOND, #I18N_UCALENDAR_MILLISECOND,
 722  *                     #I18N_UCALENDAR_ZONE_OFFSET, #I18N_UCALENDAR_DST_OFFSET, #I18N_UCALENDAR_YEAR_WOY,
 723  *                     #I18N_UCALENDAR_DOW_LOCAL, #I18N_UCALENDAR_EXTENDED_YEAR, #I18N_UCALENDAR_JULIAN_DAY,
 724  *                     #I18N_UCALENDAR_MILLISECONDS_IN_DAY, #I18N_UCALENDAR_IS_LEAP_MONTH.
 725  * @param[in] type     The desired critical point; one of #I18N_UCALENDAR_MINIMUM, #I18N_UCALENDAR_MAXIMUM,
 726  *                     #I18N_UCALENDAR_GREATEST_MINIMUM, #I18N_UCALENDAR_LEAST_MAXIMUM,
 727  *                     #I18N_UCALENDAR_ACTUAL_MINIMUM, #I18N_UCALENDAR_ACTUAL_MAXIMUM.
 728  *
 729  * @exception #I18N_ERROR_NONE Successful
 730  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 731  *
 732  * @return The requested value.
 733  */
 734 int32_t i18n_ucalendar_get_limit (const i18n_ucalendar_h calendar, i18n_ucalendar_date_fields_e field, i18n_ucalendar_limit_type_e type);
 735
 736 /**
 737  * @brief Gets the locale for this @c calendar object.
 738  * @details You can choose between valid and actual locale.
 739  * @remarks The specific error code can be obtained using the get_last_result()
 740  *      method. Error codes are described in Exceptions section and
 741  *      #i18n_error_code_e description.
 742  * @since_tizen 2.3.1
 743  *
 744  * @param[in] calendar The calendar object
 745  * @param[in] type Type of the locale we're looking for (valid or actual)
 746  *
 747  * @return The requested value.
 748  * @exception #I18N_ERROR_NONE Successful
 749  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 750  */
 751 const char *i18n_ucalendar_get_locale_by_type (const i18n_ucalendar_h calendar, i18n_ulocale_data_locale_type_e type);
 752
 753 /**
 754  * @brief Returns the timezone data version currently used by ICU.
 755  * @remarks The specific error code can be obtained using the get_last_result()
 756  *      method. Error codes are described in #i18n_error_code_e description.
 757  * @since_tizen 2.3.1
 758  *
 759  * @return The version string, such as "2007f".
 760  * @exception #I18N_ERROR_NONE Successful
 761  */
 762 const char *i18n_ucalendar_get_tz_data_version (void);
 763
 764 /**
 765  * @brief Returns the canonical system timezone ID or the normalized custom time zone ID for the given time zone ID.
 766  * @remarks The specific error code can be obtained using the get_last_result()
 767  *      method. Error codes are described in Exceptions section and
 768  *      #i18n_error_code_e description.
 769  * @since_tizen 2.3.1
 770  *
 771  * @param[in] id The input timezone ID to be canonicalized.
 772  * @param[in] length The length of the @c id, or @c -1 if NULL-terminated.
 773  * @param[out] result The buffer receives the canonical system timezone ID or the custom timezone ID in normalized format.
 774  * @param[in] result_capacity The capacity of the @c result buffer.
 775  * @param[out] is_system_id Receives if the given @c id is a known system timezone ID.
 776  *
 777  * @return The result string length, not including the terminating NULL.
 778  * @exception #I18N_ERROR_NONE Successful
 779  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 780  */
 781 int32_t i18n_ucalendar_get_canonical_timezone_id (const i18n_uchar *id, int32_t length, i18n_uchar *result, int32_t result_capacity,  i18n_ubool *is_system_id);
 782
 783 /**
 784  * @brief Gets the resource keyword value string designating the calendar type for the #i18n_ucalendar_h.
 785  * @remarks The specific error code can be obtained using the get_last_result()
 786  *      method. Error codes are described in Exceptions section and
 787  *      #i18n_error_code_e description.
 788  * @since_tizen 2.3.1
 789  *
 790  * @param[in] calendar The #i18n_ucalendar_h to query.
 791  *
 792  * @return The resource keyword value string.
 793  * @exception #I18N_ERROR_NONE Successful
 794  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 795  */
 796 const char *i18n_ucalendar_get_type (const i18n_ucalendar_h calendar);
 797
 798 /**
 799  * @brief Given a key and a locale, returns an array of string values in a preferred order that would make a difference.
 800  * @details These are all and only those values where the open (creation) of the service with the
 801  *      locale formed from the input locale plus input keyword and that value
 802  *      has different behavior than creation with the input locale alone.
 803  * @since_tizen 2.3.1
 804  *
 805  * @param[in] key One of the keys supported by this service. For now, only "calendar" is supported.
 806  * @param[in] locale The locale
 807  * @param[in] commonly_used If set to @c true it will return only commonly used values with
 808  *      the given locale in preferred order. Otherwise, it will return all the available
 809  *      values for the locale.
 810  *
 811  * @param[out] enumeration A pointer to the string enumeration over keyword values for the given key and the locale.
 812  *
 813  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 814  * @retval #I18N_ERROR_NONE Successful
 815  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 816  */
 817 int i18n_ucalendar_get_keyword_values_for_locale (const char *key, const char *locale, i18n_ubool commonly_used, i18n_uenumeration_h *enumeration);
 818
 819 /**
 820  * @brief Returns whether the given day of the week is a weekday, a weekend day,
 821  *      or a day that transitions from one to the other, for the locale and calendar system
 822  *      associated with this @c #i18n_ucalendar_h (the locale's region is often the most determinant factor).
 823  * @details If a transition occurs at midnight, then the days before and after the
 824  *      transition will have the type #I18N_UCALENDAR_WEEKDAY or #I18N_UCALENDAR_WEEKEND.
 825  *      If a transition occurs at a time other than midnight, then the day of the
 826  *      transition will have the type #I18N_UCALENDAR_WEEKEND_ONSET or #I18N_UCALENDAR_WEEKEND_CEASE.
 827  *      In this case, the function i18n_ucalendar_get_weekend_transition() will
 828  *      return the point of transition.
 829  * @since_tizen 2.3.1
 830  *
 831  * @param[in] calendar The #i18n_ucalendar_h to query.
 832  * @param[in] day_of_week The day of the week whose type is desired (#I18N_UCALENDAR_SUNDAY..#I18N_UCALENDAR_SATURDAY).
 833  *
 834  * @param [out] weekday A pointer to the #i18n_ucalendar_weekday_type_e for the day of the week.
 835  *
 836  * @return Error code. Error codes not listed below are described in #i18n_error_code_e
 837  * @retval #I18N_ERROR_NONE Successful
 838  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 839  */
 840 int i18n_ucalendar_get_day_of_week_type (const i18n_ucalendar_h calendar, i18n_ucalendar_days_of_week_e day_of_week, i18n_ucalendar_weekday_type_e *weekday);
 841
 842 /**
 843  * @brief Returns the time during the day at which the weekend begins or ends in this calendar system.
 844  * @details If i18n_ucalendar_get_day_of_week_type() returns #I18N_UCALENDAR_WEEKEND_ONSET
 845  *      for the specified @c day_of_week, return the time at which the weekend begins. If
 846  *      i18n_ucalendar_get_day_of_week_type() returns #I18N_UCALENDAR_WEEKEND_CEASE for
 847  *      the specified @c day_of_week, return the time at which the weekend ends. If
 848  *      i18n_ucalendar_get_day_of_week_type() returns some other #i18n_ucalendar_weekday_type_e
 849  *      for the specified @c day_of_week, it is an error condition (#I18N_ERROR_INVALID_PARAMETER).
 850  * @remarks The specific error code can be obtained using the get_last_result()
 851  *      method. Error codes are described in Exceptions section and
 852  *      #i18n_error_code_e description.
 853  * @since_tizen 2.3.1
 854  *
 855  * @param[in] calendar The #i18n_ucalendar_h to query.
 856  * @param[in] day_of_week The day of the week whose type is desired (#I18N_UCALENDAR_SUNDAY..#I18N_UCALENDAR_SATURDAY).
 857  *
 858  * @return The milliseconds after midnight at which the weekend begins or ends.
 859  * @exception #I18N_ERROR_NONE Successful
 860  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 861  */
 862 int32_t  i18n_ucalendar_get_weekend_transition (const i18n_ucalendar_h calendar, i18n_ucalendar_days_of_week_e day_of_week);
 863
 864 /**
 865  * @brief Returns @c true if the given #i18n_udate is in the weekend in this calendar system.
 866  * @remarks The specific error code can be obtained using the get_last_result()
 867  *      method. Error codes are described in Exceptions section and
 868  *      #i18n_error_code_e description.
 869  * @since_tizen 2.3.1
 870  *
 871  * @param[in] calendar The #i18n_ucalendar_h to query.
 872  * @param[in] date The #i18n_udate in question.
 873   *
 874  * @return @c true if the given #i18n_udate is in the weekend in this calendar system, @c false otherwise.
 875  * @exception #I18N_ERROR_NONE Successful
 876  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 877  */
 878 i18n_ubool i18n_ucalendar_is_weekend (i18n_ucalendar_h calendar, i18n_udate date);
 879
 880 /**
 881  * @brief Get the #i18n_udate for the next/previous time zone transition relative
 882  *      to the calendar's current date, in the time zone to which the calendar is currently set.
 883  * @details If there is no known time zone transition of the requested type relative
 884  *      to the calendar's date, the function returns @c false.
 885  * @remarks The specific error code can be obtained using the get_last_result()
 886  *      method. Error codes are described in Exceptions section and
 887  *      #i18n_error_code_e description.
 888  * @since_tizen 2.3.1
 889  *
 890  * @param[in] calendar The #i18n_ucalendar_h to query.
 891  * @param[in] type The type of transition desired.
 892  * @param[out] transition A pointer to a #i18n_udate to be set to the transition time.
 893  *      If the function returns @c false, the value set is unspecified.
 894  *
 895  * @return @c true if the given #i18n_udate is in the weekend in this calendar system, @c false otherwise.
 896  * @exception #I18N_ERROR_NONE Successful
 897  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 898  */
 899 i18n_ubool i18n_ucalendar_get_timezone_transition_date (const i18n_ucalendar_h calendar, i18n_utimezone_transition_type_e type, i18n_udate *transition);
 900
 901 /**
 902  * @}
 903  * @}
 904  */
 905
 906 #ifdef __cplusplus
 907 }
 908 #endif
 909
 910 #endif  /* __I18N_UCALENDAR_H__*/