src/include/wearable/utils_i18n_ulocale.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  * Copyright (C) 1997-2013, International Business Machines
  17  * Corporation and others.  All Rights Reserved.
  18  */
  19
  20 #ifndef __UTILS_I18N_ULOCALE_H__
  21 #define __UTILS_I18N_ULOCALE_H__
  22
  23 #include <utils_i18n_types.h>
  24
  25 /**
  26  * @file utils_i18n_ulocale.h
  27  * @version 0.1
  28  * @brief utils_i18n_ulocale
  29  */
  30
  31 /**
  32  * @ingroup CAPI_BASE_UTILS_I18N_MODULE
  33  * @defgroup CAPI_BASE_UTILS_I18N_ULOCALE_MODULE Ulocale
  34  * @brief A Locale represents a specific geographical, political, or cultural region.
  35  * @section CAPI_BASE_UTILS_I18N_ULOCALE_MODULE_HEADER Required Header
  36  *  \#include <utils_i18n.h>
  37  *
  38  * @section CAPI_BASE_UTILS_I18N_ULOCALE_MODULE_OVERVIEW Overview
  39  * @details A Locale represents a specific geographical, political, or cultural region.
  40  *          An operation that requires a Locale to perform its task is called locale-sensitive
  41  *          and uses the Locale to tailor information for the user. For example, displaying
  42  *          a number is a locale-sensitive operation. The number should be formatted according
  43  *          to the customs/conventions of the user's native country, region, or culture.
  44  *          In the C APIs, a locale is simply a const char string.
  45  *
  46  * @section CAPI_BASE_UTILS_I18N_ULOCALE_MODULE_SAMPLE_CODE_1 Sample Code 1
  47  * @brief Gets a default locale and a full name for the locale
  48  * @code
  49     const char *locale;
  50     const char *in_locale_id = "en_US";
  51     char language[64] = {0,};
  52     i18n_uchar result_w[64] = {0,};
  53     char result[64] = {0,};
  54     int language_capacity = 64;
  55     int buf_size_language;
  56     int buf_size_display_name;
  57     int ret = I18N_ERROR_NONE;
  58
  59     // Sets default locale
  60     ret = i18n_ulocale_set_default(getenv("LC_TIME"));
  61
  62     // Gets default locale
  63     ret = i18n_ulocale_get_default(&locale);
  64     if ( ret != I18N_ERROR_NONE ) {
  65         dlog_print(DLOG_ERROR, LOG_TAG, "i18n_ulocale_get_default() failed!!! \n");
  66     }
  67     dlog_print(DLOG_INFO, LOG_TAG, "default locale : %s\n", locale);    // default locale : en_GB.UTF-8
  68
  69     // Gets the language code for the specified locale
  70     ret = i18n_ulocale_get_language(locale, language, language_capacity, &buf_size_language);
  71     if ( ret != I18N_ERROR_NONE ) {
  72         dlog_print(DLOG_ERROR, LOG_TAG, "i18n_ulocale_get_language() failed!!! \n");
  73     }
  74     dlog_print(DLOG_INFO, LOG_TAG, "language code for the locale : %s\n", language);  // language code for the locale : en
  75
  76     // Gets the full name suitable for display for the specified locale
  77     ret = i18n_ulocale_get_display_name(locale, in_locale_id, result_w, 64, &buf_size_display_name);
  78     if ( ret != I18N_ERROR_NONE ) {
  79         dlog_print(DLOG_ERROR, LOG_TAG, "i18n_ulocale_get_display_name() failed!!! \n");
  80     }
  81     i18n_ustring_copy_au(result, result_w);
  82     dlog_print(DLOG_INFO, LOG_TAG, "full name suitable for the locale : %s\n", result); // full name suitable for the locale : English (United Kingdom)
  83  * @endcode
  84  *
  85  * @section CAPI_BASE_UTILS_I18N_ULOCALE_MODULE_SAMPLE_CODE_2 Sample Code 2
  86  * @brief See all available locales
  87  * @code
  88     int i = 0;
  89     int32_t count = i18n_ulocale_count_available();
  90     for(i = 0; i < count; i++)
  91     {
  92         dlog_print(DLOG_INFO, LOG_TAG, "Available locale %d : %s " ,i, i18n_ulocale_get_available(i));
  93         //   ...
  94         //Available locale 5 : en_GB
  95         //Available locale 6 : en_US
  96         //Available locale 7 : en_US_POSIX
  97         //   ...
  98     }
  99  * @endcode
 100  */
 101
 102 /**
 103  * @addtogroup CAPI_BASE_UTILS_I18N_ULOCALE_MODULE
 104  * @{
 105  */
 106
 107 #ifdef __cplusplus
 108 extern "C" {
 109 #endif
 110
 111 /**
 112  * @brief Gets I18N's default locale.
 113  * @details The returned string is a snapshot in time, and will remain valid
 114  *          and unchanged even when i18n_ulocale_set_default() is called.
 115  *          The returned storage is owned by I18N, and must not be altered or deleted by the caller.
 116  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 117  *
 118  * @param[out] locale   The I18N default locale
 119  *
 120  * @retval #I18N_ERROR_NONE Successful
 121  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 122  */
 123 int i18n_ulocale_get_default ( const char **locale );
 124
 125 /**
 126  * @brief Sets I18N's default locale.
 127  * @details By default (without calling this function),
 128  *          I18N's default locale will be based on information obtained from the underlying system environment.
 129  *
 130  *          Changes to I18N's default locale do not propagate back to the system environment.
 131  *
 132  *          Changes to I18N's default locale to not affect any services that may already be open based on the previous default locale value.
 133  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 134  *
 135  * @param[in] locale_id     The new I18N default locale.\n
 136  *                          A value of @c NULL will try to get the system's default locale.
 137  *
 138  * @retval #I18N_ERROR_NONE Successful
 139  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 140  */
 141 int i18n_ulocale_set_default ( const char *locale_id );
 142
 143 /**
 144  * @brief Gets the language code for the specified locale.
 145  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 146  *
 147  * @param[in] locale_id             The locale to get the ISO language code with.\n
 148  *                                  @c NULL may be used to specify the default.
 149  * @param[out] language             The language code for @a locale_id
 150  * @param[in] language_capacity     The size of the @a language buffer to store the language code with
 151  * @param[out] buf_size_language    The actual buffer size needed for the language code.\n
 152  *                                  If it's greater than @a language_capacity, the returned language code will be truncated.
 153  *
 154  * @retval #I18N_ERROR_NONE Successful
 155  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 156  */
 157 int i18n_ulocale_get_language ( const char *locale_id, char *language, int32_t language_capacity, int32_t *buf_size_language );
 158
 159 /**
 160  * @brief Gets the country code for the specified locale.
 161  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 162  *
 163  * @param[in]  locale_id            The locale to get the country code with
 164  * @param[out] country              The country code for @a locale_id
 165  * @param[in]  country_capacity     The size of the @a country buffer to store the country code with
 166  * @param[out] error                Error information if retrieving the country code failed
 167  *
 168  * @return The actual buffer size needed for the country code.\n
 169  *         If it's greater than @a country_capacity, the returned country code will be truncated.
 170  */
 171 int32_t i18n_ulocale_get_country ( const char *locale_id, char *country, int32_t country_capacity, int *error );
 172
 173 /**
 174  * @brief Gets the full name suitable for display for the specified locale.
 175  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 176  *
 177  * @param[in] locale_id                 The locale to get the displayable name with.\n
 178  *                                      @c NULL may be used to specify the default.
 179  * @param[in] in_locale_id              The locale to be used to display the name.\n
 180  *                                      @c NULL may be used to specify the default.
 181  * @param[out] result                   The displayable name for @a locale_id
 182  * @param[in] max_result_size           The size of the name buffer to store the displayable full name with
 183  * @param[out] buf_size_display_name    The actual buffer size needed for the displayable name.\n
 184  *                                      If it's greater than @a max_result_size, the returned displayable name will be truncated.
 185  *
 186  * @retval #I18N_ERROR_NONE Successful
 187  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 188  */
 189 int i18n_ulocale_get_display_name ( const char *locale_id, const char *in_locale_id, i18n_uchar *result, int32_t max_result_size, int32_t *buf_size_display_name );
 190
 191 /**
 192  * @brief Gets the specified locale from a list of all available locales.
 193  * @details The return value is a pointer to an item of a locale name array.
 194  *          Both this array and the pointers it contains are owned by I18N
 195  *          and should not be deleted or written through by the caller.
 196  *          The locale name is terminated by a null pointer.
 197  * @remarks The specific error code can be obtained using the get_last_result() method.
 198  *          Error codes are described in Exceptions section.
 199  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 200  *
 201  * @param[in] n     The specific locale name index of the available locale list
 202  *
 203  * @return A specified locale name of all available locales
 204  * @exception #I18N_ERROR_NONE Success
 205  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 206  */
 207 const char* i18n_ulocale_get_available ( int32_t n );
 208
 209 /**
 210  * @brief Gets the size of the all available locale list.
 211  * @remarks The specific error code can be obtained using the get_last_result() method.
 212  *          Error codes are described in Exceptions section.
 213  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 214  *
 215  * @return The size of the locale list
 216  * @exception #I18N_ERROR_NONE Success
 217  */
 218 int32_t i18n_ulocale_count_available ( void );
 219
 220 // Newly Added APIs
 221
 222 /**
 223  * @brief Gets the script code for the specified locale.
 224  * @remarks The specific error code can be obtained using the get_last_result() method.
 225  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 226  * @since_tizen 2.3.1
 227  *
 228  * @param[in] locale_id         The locale to get the ISO script code with
 229  * @param[out] script           The script code for @a locale_id. Must not be @c NULL.
 230  * @param[in] script_capacity   The size of the @a script buffer to store the script code with
 231  *
 232  * @return The actual buffer size needed for the script code. If it's greater than @a script_capacity,
 233  *         the returned script code will be truncated. If the @a script buffer is @c NULL
 234  *         or the @a script_capacity is lower than @c 0 , then the #I18N_ERROR_INVALID_PARAMETER error will be set
 235  *         and @c -1 will be returned.
 236  *
 237  * @exception #I18N_ERROR_NONE Successful
 238  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 239  */
 240 int32_t i18n_ulocale_get_script ( const char *locale_id, char *script, int32_t script_capacity );
 241
 242 /**
 243  * @brief Gets the variant code for the specified locale.
 244  * @remarks The specific error code can be obtained using the get_last_result() method.
 245  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 246  * @since_tizen 2.3.1
 247  *
 248  * @param[in] locale_id         The locale to get the variant code with
 249  * @param[out] variant          The variant code for @a locale_id
 250  * @param[in] variant_capacity  The size of the @a variant buffer to store the variant code with
 251  *
 252  * @return The actual buffer size needed for the variant code. If it's greater than @a variant_capacity,
 253  *         the returned variant code will be truncated. If the @a variant buffer is @c NULL
 254  *         or the @a variant_capacity is lower than @c 0 , then the #I18N_ERROR_INVALID_PARAMETER error will be set
 255  *         and @c -1 will be returned.
 256  *
 257  * @exception #I18N_ERROR_NONE Successful
 258  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 259  */
 260 int32_t i18n_ulocale_get_variant ( const char *locale_id, char *variant, int32_t variant_capacity );
 261
 262 /**
 263  * @brief Gets the full name for the specified locale.
 264  * @details Note : This has the effect of 'canonicalizing' the I18N locale ID to
 265  *          a certain extent. Upper and lower case are set as needed.
 266  *          It does NOT map aliased names in any way.
 267  *          See the top of this header file.
 268  *          This API supports preflighting.
 269  * @remarks The specific error code can be obtained using the get_last_result() method.
 270  *          Error codes are described in #i18n_error_code_e description.
 271  * @since_tizen 2.3.1
 272  *
 273  * @param[in] locale_id         The locale to get the full name with
 274  * @param[out] name             Fill in buffer for the name without keywords.
 275  * @param[in] name_capacity     Capacity of the fill in buffer.
 276  *
 277  * @return The actual buffer size needed for the full name. If it's greater than @a name_capacity,
 278  *         the returned full name will be truncated.
 279  * @exception #I18N_ERROR_NONE Successful
 280  * @exception #I18N_ERROR_BUFFER_OVERFLOW A result would not fit in the supplied buffer
 281  */
 282 int32_t i18n_ulocale_get_name ( const char *locale_id, char *name, int32_t name_capacity );
 283
 284 /**
 285  * @brief Gets the full name for the specified locale.
 286  * @details Note : This has the effect of 'canonicalizing' the string to
 287  *          a certain extent. Upper and lower case are set as needed,
 288  *          and if the components were in 'POSIX' format they are changed to
 289  *          I18N format. It does NOT map aliased names in any way.
 290  *          See the top of this header file.
 291  * @remarks The specific error code can be obtained using the get_last_result() method.
 292  *          Error codes are described in #i18n_error_code_e description.
 293  * @since_tizen 2.3.1
 294  *
 295  * @param[in] locale_id         The locale to get the full name with
 296  * @param[out] name             The full name for @a locale_id
 297  * @param[in] name_capacity     The size of the @a name buffer to store the full name with
 298  *
 299  * @return The actual buffer size needed for the full name. If it's greater than @a name_capacity,
 300  *         the returned full name will be truncated.
 301  * @exception #I18N_ERROR_NONE Successful
 302  * @exception #I18N_ERROR_BUFFER_OVERFLOW A result would not fit in the supplied buffer
 303  */
 304 int32_t i18n_ulocale_canonicalize ( const char *locale_id, char *name, int32_t name_capacity );
 305
 306 /**
 307  * @brief Gets the ISO language code for the specified locale.
 308  * @remarks The specific error code can be obtained using the get_last_result() method.
 309  *          Error codes are described in Exceptions section.
 310  * @since_tizen 2.3.1
 311  *
 312  * @param[in] locale_id     The locale to get the ISO language code with
 313  *
 314  * @return A language the ISO language code for @a locale_id
 315  *
 316  * @exception #I18N_ERROR_NONE Successful
 317  */
 318 const char * i18n_ulocale_get_iso3_language ( const char *locale_id );
 319
 320 /**
 321  * @brief Gets the ISO country code for the specified locale.
 322  * @remarks The specific error code can be obtained using the get_last_result() method.
 323  *          Error codes are described in Exceptions section.
 324  * @since_tizen 2.3.1
 325  *
 326  * @param[in] locale_id     The locale to get the ISO country code with
 327  *
 328  * @return A country the ISO country code for @a locale_id
 329  *
 330  * @exception #I18N_ERROR_NONE Successful
 331  */
 332 const char * i18n_ulocale_get_iso3_country ( const char *locale_id );
 333
 334 /**
 335  * @brief Gets the Win32 LCID value for the specified locale.
 336  * @details If the I18N locale is not recognized by Windows, 0 will be returned.
 337  * @remarks The specific error code can be obtained using the get_last_result() method.
 338  *          Error codes are described in Exceptions section.
 339  * @since_tizen 2.3.1
 340  *
 341  * @param[in] locale_id     The locale to get the Win32 LCID value with
 342  *
 343  * @return A country the Win32 LCID for @a locale_id
 344  *
 345  * @exception #I18N_ERROR_NONE Successful
 346  */
 347 uint32_t i18n_ulocale_get_lcid ( const char *locale_id );
 348
 349 /**
 350  * @brief Gets the language name suitable for display for the specified locale.
 351  * @remarks The specific error code can be obtained using the get_last_result() method.
 352  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 353  * @since_tizen 2.3.1
 354  *
 355  * @param[in] locale                The locale to get the ISO language code with
 356  * @param[in] display_locale        The locale to be used to display the name.\n
 357  *                                  @c NULL may be used to specify the default.
 358  * @param[out] language             The displayable language code for @a locale.
 359  * @param[in] language_capacity     The size of the @a language buffer to store the displayable language code with
 360  *
 361  * @return The actual buffer size needed for the displayable language code. If it's greater than
 362  *         @a language_capacity, the returned language code will be truncated. If the @a language buffer is @c NULL
 363  *         or the @a language_capacity is lower than @c 0 , then the #I18N_ERROR_INVALID_PARAMETER error will be set
 364  *         and @c 0 will be returned.
 365  *
 366  * @exception #I18N_ERROR_NONE Successful
 367  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 368  */
 369 int32_t i18n_ulocale_get_display_language ( const char *locale, const char *display_locale, i18n_uchar *language, int32_t language_capacity );
 370
 371 /**
 372  * @brief Gets the script name suitable for display for the specified locale.
 373  * @remarks The specific error code can be obtained using the get_last_result() method.
 374  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 375  * @since_tizen 2.3.1
 376  *
 377  * @param[in] locale            The locale to get the displayable script code with. @c NULL may be used to specify the default.
 378  * @param[in] display_locale    The locale to be used to display the name. @c NULL may be used to specify the default.
 379  * @param[out] script           The displayable country code for @a locale
 380  * @param[in] script_capacity   The size of the script buffer to store the displayable script code with
 381  *
 382  * @return The actual buffer size needed for the displayable script code. If it's greater than @a script_capacity,
 383  *         the returned displayable script code will be truncated. If the @a script buffer is @c NULL
 384  *         or the @a script_capacity is lower than @c 0 , then the #I18N_ERROR_INVALID_PARAMETER error will be set
 385  *         and @c 0 will be returned.
 386  *
 387  * @exception #I18N_ERROR_NONE Successful
 388  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 389  */
 390 int32_t i18n_ulocale_get_display_script ( const char *locale, const char *display_locale, i18n_uchar *script, int32_t script_capacity );
 391
 392 /**
 393  * @brief Gets the country name suitable for display for the specified locale.
 394  * @remarks The specific error code can be obtained using the get_last_result() method.
 395  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 396  * @since_tizen 2.3.1
 397  *
 398  * @param[in] locale            The locale to get the displayable country code with. @c NULL may be used to specify the default.
 399  * @param[in] display_locale    The locale to be used to display the name. @c NULL may be used to specify the default.
 400  * @param[out] country          The displayable country code for @a locale
 401  * @param[in] country_capacity  The size of the @a country buffer to store the displayable country code with
 402  *
 403  * @return The actual buffer size needed for the displayable country code. If it's greater than @a country_capacity,
 404  *         the returned displayable country code will be truncated. If the @a country buffer is @c NULL
 405  *         or the @a country_capacity is lower than @c 0 , then the #I18N_ERROR_INVALID_PARAMETER error will be set
 406  *         and @c 0 will be returned.
 407  *
 408  * @exception #I18N_ERROR_NONE Successful
 409  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 410  */
 411 int32_t i18n_ulocale_get_display_country ( const char *locale, const char *display_locale, i18n_uchar *country, int32_t country_capacity );
 412
 413 /**
 414  * @brief Gets the variant name suitable for display for the specified locale.
 415  * @remarks The specific error code can be obtained using the get_last_result() method.
 416  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 417  * @since_tizen 2.3.1
 418  *
 419  * @param[in] locale            The locale to get the displayable variant code with. @c NULL may be used to specify the default.
 420  * @param[in] display_locale    The locale to be used to display the name. @c NULL may be used to specify the default.
 421  * @param[out] variant          The displayable variant code for @a locale
 422  * @param[in] variant_capacity  The size of the @a variant buffer to store the displayable variant code with
 423  *
 424  * @return The actual buffer size needed for the displayable variant code. If it's greater than @a variant_capacity,
 425  *         the returned displayable variant code will be truncated. If the @a variant buffer is @c NULL
 426  *         or the @a variant_capacity is lower than @c 0 , then the #I18N_ERROR_INVALID_PARAMETER error will be set
 427  *         and @c 0 will be returned.
 428  *
 429  * @exception #I18N_ERROR_NONE Successful
 430  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 431  */
 432 int32_t i18n_ulocale_get_display_variant ( const char *locale, const char *display_locale, i18n_uchar *variant, int32_t variant_capacity );
 433
 434 /**
 435  * @brief Gets the keyword name suitable for display for the specified locale.
 436  * @details E.g : for the locale string de_DE\@collation=PHONEBOOK, this API gets the display string for the keyword collation.
 437  *          Usage :
 438  * @code
 439  *    i18n_error_code_e status = I18N_ERROR_NONE;
 440  *    const char* keyword = NULL;
 441  *    int32_t keyword_len = 0;
 442  *    int32_t keyword_count = 0;
 443  *    i18n_uchar display_keyword[256];
 444  *    int32_t display_keyword_len = 0;
 445  *    i18n_uenumeration_h keyword_enum = i18n_ulocale_keywords_create("de_DE@collation=PHONEBOOK;calendar=TRADITIONAL");
 446  *
 447  *    for(keyword_count = i18n_uenumeration_count(keyword_enum); keyword_count > 0; keyword_count--){
 448  *          status = get_last_result();
 449  *          if(status > 0){
 450  *              // something went wrong so handle the error
 451  *              break;
 452  *          }
 453  *          // the uenum_next returns NULL-terminated string
 454  *          keyword = i18n_uenumeration_next(keyword_enum, &keyword_len);
 455  *          display_keyword_len = i18n_ulocale_get_display_keyword(keyword, "en_US", display_keyword, 256);
 456  *          // do something interesting
 457  *    }
 458  *    i18n_uenumeration_destroy(keyword_enum);
 459  * @endcode
 460  * @remarks The specific error code can be obtained using the get_last_result() method.
 461  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 462  * @since_tizen 2.3.1
 463  *
 464  * @param[in] keyword           The keyword whose display string needs to be returned.
 465  * @param[in] display_locale    The locale to be used to display the name. @c NULL may be used to specify the default.
 466  * @param[out] dest             The buffer to which the displayable keyword should be written.
 467  * @param[in] dest_capacity     The size of the buffer (number of #i18n_uchar characters). If it is 0, then
 468  *                              @a dest may be @c NULL and the function will only return the length of the result without
 469  *                              writing any of the result string (pre-flighting).
 470  *
 471  * @return The actual buffer size needed for the displayable variant code. If the @a dest buffer is @c NULL
 472  *         or the @a dest_capacity is lower than @c 0 , then the #I18N_ERROR_INVALID_PARAMETER error will be set
 473  *         and @c 0 will be returned.
 474  *
 475  * @exception #I18N_ERROR_NONE Successful
 476  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 477  *
 478  * @see i18n_ulocale_keywords_create()
 479  * @see i18n_uenumeration_count()
 480  * @see i18n_uenumeration_next()
 481  * @see i18n_uenumeration_destroy()
 482  */
 483 int32_t i18n_ulocale_get_display_keyword ( const char *keyword, const char *display_locale, i18n_uchar *dest, int32_t dest_capacity );
 484
 485 /**
 486  * @brief Gets the value of the keyword suitable for display for the specified locale.
 487  * @details E.g : for the locale string de_DE\@collation=PHONEBOOK, this API gets the display string for PHONEBOOK, in the display locale, when "collation" is specified as the keyword.
 488  * @remarks The specific error code can be obtained using the get_last_result() method.
 489  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 490  * @since_tizen 2.3.1
 491  *
 492  * @param[in] locale            The locale to get the displayable variant code with. @c NULL may be used to specify the default.
 493  * @param[in] keyword           The keyword for whose value should be used.
 494  * @param[in] display_locale    The locale to be used to display the name. @c NULL may be used to specify the default.
 495  * @param[out] dest             The buffer to which the displayable keyword should be written.
 496  * @param[in] dest_capacity     The size of the buffer (number of #i18n_uchar characters). If it is 0, then
 497  *                              @a dest may be @c NULL and the function will only return the length of the result
 498  *                              without writing any of the result string (pre-flighting).
 499  *
 500  * @return The actual buffer size needed for the displayable variant code. If the @a dest buffer is @c NULL
 501  *         or the @a dest_capacity is lower than @c 0 , then the #I18N_ERROR_INVALID_PARAMETER error will be set
 502  *         and @c 0 will be returned.
 503  *
 504  * @exception #I18N_ERROR_NONE Successful
 505  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 506  */
 507 int32_t i18n_ulocale_get_display_keyword_value ( const char *locale, const char *keyword, const char *display_locale, i18n_uchar *dest, int32_t dest_capacity );
 508
 509 /**
 510  * @brief Gets a list of all available 2-letter language codes defined in ISO 639,
 511  *        plus additional 3-letter codes determined to be useful for locale generation as
 512  *        defined by Unicode CLDR.
 513  * @details This is a pointer to an array of pointers to arrays of char. All of these pointers are owned
 514  *          by I18N - do not delete them, and do not write through them.
 515  *          The array is terminated with a @c NULL pointer.
 516  * @remarks The specific error code can be obtained using the get_last_result() method.
 517  *          Error codes are described in Exceptions section.
 518  * @since_tizen 2.3.1
 519  *
 520  * @return A list of all available language codes
 521  *
 522  * @exception #I18N_ERROR_NONE Successful
 523  */
 524 const char * const *i18n_ulocale_get_iso_languages ( void );
 525
 526 /**
 527  *
 528  * @brief Gets a list of all available 2-letter country codes defined in ISO 639.
 529  * @details This is a pointer to an array of pointers to arrays of char. All of these pointers are
 530  *          owned by I18N - do not delete them, and do not write through them.
 531  *          The array is terminated with a @c NULL pointer.
 532  * @remarks The specific error code can be obtained using the get_last_result() method.
 533  *          Error codes are described in Exceptions section.
 534  * @since_tizen 2.3.1
 535  *
 536  * @return A list of all available country codes
 537  *
 538  * @exception #I18N_ERROR_NONE Successful
 539  */
 540 const char * const *i18n_ulocale_get_iso_countries ( void );
 541
 542 /**
 543  * @brief Truncates the locale ID string to get the parent locale ID.
 544  * @details Copies the part of the string before the last underscore.
 545  *          The parent locale ID will be an empty string if there is no
 546  *          underscore, or if there is only one underscore at @a locale_id[0].
 547  * @remarks The specific error code can be obtained using the get_last_result() method.
 548  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 549  * @since_tizen 2.3.1
 550  *
 551  * @param[in] locale_id         Input locale ID string.
 552  * @param[out] parent           Output string buffer for the parent locale ID. Must not be @c NULL.
 553  * @param[in] parent_capacity   Size of the output buffer. If it's lower than the number of characters
 554  *                              stored in the @a locale_id between the first character and the last occurrence
 555  *                              of the underscore ("_") character, than the error code will be set to
 556  *                              #I18N_ERROR_BUFFER_OVERFLOW.
 557  *
 558  * @return The length of the parent locale ID. If the @a parent buffer is @c NULL or the @a parent_capacity is lower than @c 0,
 559  *         then the #I18N_ERROR_INVALID_PARAMETER error will be set and @c -1 will be returned.
 560  *
 561  * @exception #I18N_ERROR_NONE Successful
 562  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 563  * @exception #I18N_ERROR_BUFFER_OVERFLOW If the capacity of the @a parent is lower than the number of characters
 564  *                                        in the @a locale_id from index 0 to the index of the last occurrence of
 565  *                                        the underscore ("_") symbol.
 566  */
 567 int32_t i18n_ulocale_get_parent ( const char *locale_id, char *parent, int32_t parent_capacity );
 568
 569 /**
 570  * @brief Gets the full name for the specified locale.
 571  * @details Note : This has the effect of 'canonicalizing' the string to a certain extent.
 572  *          Upper and lower case are set as needed,
 573  *          and if the components were in 'POSIX' format they are changed to I18N format.
 574  *          It does NOT map aliased names in any way.
 575  *          See the top of this header file.
 576  *
 577  *          This API strips off the keyword part, so "de_DE\@collation=phonebook" will become "de_DE".
 578  *          This API supports preflighting.
 579  * @remarks The specific error code can be obtained using the get_last_result() method.
 580  *          Error codes are described in #i18n_error_code_e description.
 581  * @since_tizen 2.3.1
 582  *
 583  * @param[in] locale_id         The locale to get the full name with
 584  * @param[out] name             Fill in buffer for the name without keywords.
 585  * @param[in] name_capacity     Capacity of the fill in buffer.
 586  *
 587  * @return The actual buffer size needed for the full name. If it's greater than @a name_capacity,
 588  *         the returned full name will be truncated.
 589  * @exception #I18N_ERROR_NONE Successful
 590  * @exception #I18N_ERROR_BUFFER_OVERFLOW A result would not fit in the supplied buffer
 591  */
 592 int32_t i18n_ulocale_get_base_name ( const char *locale_id, char *name, int32_t name_capacity );
 593
 594 /**
 595  * @brief Gets an enumeration of keywords for the specified locale.
 596  * @details Enumeration must get disposed of by the client using i18n_uenumeration_destroy() function.
 597  * @remarks Error codes are described in #i18n_error_code_e description.
 598  * @since_tizen 2.3.1
 599  *
 600  * @param[in] locale_id     The locale to get the variant code with
 601  *
 602  * @param enumeration A pointer to the enumeration of keywords or @c NULL if there are no keywords.
 603  * @return The obtained error code.
 604  * @retval #I18N_ERROR_NONE Successful
 605  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 606  */
 607 int i18n_ulocale_keywords_create ( const char *locale_id, i18n_uenumeration_h *enumeration );
 608
 609 /**
 610  * @brief Gets the value for a keyword.
 611  * @details Locale name does not need to be normalized.
 612  * @remarks The specific error code can be obtained using the get_last_result() method.
 613  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 614  * @since_tizen 2.3.1
 615  *
 616  * @param[in] locale_id         A locale name containing the keyword ("de_DE@currency=EURO;collation=PHONEBOOK")
 617  * @param[in] keyword_name      The name of the keyword for which we want the value. Case insensitive.
 618  * @param[out] buffer           Receiving buffer
 619  * @param[in] buffer_capacity   Capacity of receiving @a buffer
 620  *
 621  * @return The length of keyword value. If the @a keyword_name or @a buffer is @c NULL or the @a buffer_capacity is lower than @c 0,
 622  *         then the #I18N_ERROR_INVALID_PARAMETER error will be set and @c -1 will be returned.
 623  *
 624  * @exception #I18N_ERROR_NONE Successful
 625  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 626  */
 627 int32_t i18n_ulocale_get_keyword_value ( const char *locale_id, const char *keyword_name, char *buffer, int32_t buffer_capacity );
 628
 629 /**
 630  * @brief Sets or removes the value of the specified keyword.
 631  * @details For removing all keywords, use i18n_ulocale_get_base_name().
 632  *
 633  *          NOTE : Unlike almost every other I18N function which takes a
 634  *          buffer, this function will NOT truncate the output text. If a
 635  *          #I18N_ERROR_BUFFER_OVERFLOW is received, it means that the original
 636  *          buffer is untouched. This is done to prevent incorrect or possibly
 637  *          even malformed locales from being generated and used.
 638  * @remarks The specific error code can be obtained using the get_last_result() method.
 639  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 640  * @since_tizen 2.3.1
 641  *
 642  * @param[in] keyword_name      A name of the keyword to be set. Case insensitive.
 643  * @param[in] keyword_value     A value of the keyword to be set. If 0-length or
 644  *                              @c NULL, will result in the keyword being removed.
 645  *                              No error is given if that keyword does not exist.
 646  * @param[out] buffer           Input buffer containing locale to be modified.
 647  * @param[in] buffer_capacity   Capacity of receiving @a buffer
 648  *
 649  * @return The length needed for the @a buffer. If the @a keyword_name or @a buffer is @c NULL or the @a buffer_capacity is lower than @c 0,
 650  *         then the #I18N_ERROR_INVALID_PARAMETER error will be set and @c -1 will be returned.
 651  *
 652  * @exception #I18N_ERROR_NONE Successful
 653  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 654  *
 655  * @see i18n_ulocale_get_keyword_value()
 656  */
 657 int32_t i18n_ulocale_set_keyword_value ( const char *keyword_name, const char *keyword_value, char *buffer, int32_t buffer_capacity );
 658
 659 /**
 660  * @brief Gets the layout character orientation for the specified locale.
 661  * @remarks Error codes are described in #i18n_error_code_e description.
 662  * @since_tizen 2.3.1
 663  *
 664  * @param[in] locale_id     locale name
 665  * @param[out] layout_type A pointer to the enum indicating the layout orientation for characters.
 666  *
 667  * @return The obtained error code.
 668  * @retval #I18N_ERROR_NONE Successful
 669  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 670  */
 671 int i18n_ulocale_get_character_orientation ( const char *locale_id, i18n_ulocale_layout_type_e *layout_type );
 672
 673 /**
 674  * @brief Gets the layout line orientation for the specified locale.
 675  * @remarks Error codes are described in #i18n_error_code_e description.
 676  * @since_tizen 2.3.1
 677  *
 678  * @param[in] locale_id     locale name
 679  * @param[out] layout_type A pointer to the enum indicating the layout orientation for lines.
 680  *
 681  * @return The obtained error code.
 682  * @retval #I18N_ERROR_NONE Successful
 683  * @retval #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 684  */
 685 int i18n_ulocale_get_line_orientation ( const char *locale_id, i18n_ulocale_layout_type_e *layout_type );
 686
 687 /**
 688  * @brief Gets the I18N locale ID for the specified Win32 LCID value.
 689  * @remarks The specific error code can be obtained using the get_last_result() method.
 690  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 691  * @since_tizen 2.3.1
 692  *
 693  * @param[in] host_id           The Win32 LCID to translate
 694  * @param[out] locale           The output buffer for the I18N locale ID, which will be NULL-terminated if there is room.
 695  * @param[in] locale_capacity   The size of the output buffer
 696  *
 697  * @return The actual size of the locale ID, not including NULL-termination.
 698  *         If the @a locale buffer is @c NULL or the @a locale_capacity is lower than @c 0,
 699  *         then the #I18N_ERROR_INVALID_PARAMETER error will be set and @c -1 will be returned.
 700  *
 701  * @exception #I18N_ERROR_NONE Successful
 702  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 703  */
 704 int32_t i18n_ulocale_get_locale_for_lcid ( uint32_t host_id, char *locale, int32_t locale_capacity );
 705
 706 /**
 707  * @brief Adds the likely subtags for a provided locale ID, per the algorithm described
 708  *        in the following CLDR technical report : http://www.unicode.org/reports/tr35/#Likely_Subtags
 709  * @details If @a locale_id is already in the maximal form, or there is no data available
 710  *          for maximization, it will be copied to the output buffer. For example,
 711  *          "und-Zzzz" cannot be maximized, since there is no reasonable maximization.
 712  *
 713  *          Examples :
 714  *
 715  *          "en" maximizes to "en_Latn_US"
 716  *
 717  *          "de" maximizes to "de_Latn_US"
 718  *
 719  *          "sr" maximizes to "sr_Cyrl_RS"
 720  *
 721  *          "sh" maximizes to "sr_Latn_RS" (Note this will not reverse.)
 722  *
 723  *          "zh_Hani" maximizes to "zh_Hans_CN" (Note this will not reverse.)
 724  * @remarks The specific error code can be obtained using the get_last_result() method.
 725  *          Error codes are described in #i18n_error_code_e description.
 726  * @since_tizen 2.3.1
 727  *
 728  * @param[in] locale_id                     The locale to maximize
 729  * @param[out] maximized_locale_id          The maximized locale
 730  * @param[in] maximized_locale_id_capacity  The capacity of the @a maximized_locale_id buffer
 731  *
 732  * @return The actual buffer size needed for the maximized locale. If it's
 733  *         greater than @a maximized_lacale_id_capacity, the returned ID will be truncated.
 734  *         On error, the return value is -1.
 735  * @exception #I18N_ERROR_NONE Successful
 736  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 737  */
 738 int32_t i18n_ulocale_add_likely_subtags ( const char *locale_id, char *maximized_locale_id, int32_t maximized_locale_id_capacity );
 739
 740 /**
 741  * @brief Minimizes the subtags for a provided locale ID, per the algorithm described
 742  *        in the following CLDR technical report: http://www.unicode.org/reports/tr35/#Likely_Subtags
 743  * @details If @a locale_id is already in the minimal form, or there is no data available
 744  *          for minimization, it will be copied to the output buffer.  Since the
 745  *          minimization algorithm relies on proper maximization, see the comments
 746  *          for i18n_ulocale_add_likely_subtags() for reasons why there might not be any data.
 747  *
 748  *          Examples :
 749  *
 750  *          "en_Latn_US" minimizes to "en"
 751  *
 752  *          "de_Latn_US" minimizes to "de"
 753  *
 754  *          "sr_Cyrl_RS" minimizes to "sr"
 755  *
 756  *          "zh_Hant_TW" minimizes to "zh_TW" (The region is preferred to the script, and minimizing to "zh" would imply "zh_Hans_CN".)
 757  * @remarks The specific error code can be obtained using the get_last_result() method.
 758  *          Error codes are described in #i18n_error_code_e description.
 759  * @since_tizen 2.3.1
 760  *
 761  * @param[in] locale_id                     The locale to minimize
 762  * @param[out] minimized_locale_id          The minimized locale
 763  * @param[in] minimized_locale_id_capacity  The capacity of the @a minimized_locale_id buffer
 764  *
 765  * @return The actual buffer size needed for the minimized locale. If it's
 766  *         greater than @a minimized_locale_id_capacity, the returned ID will be truncated.
 767  *         On error, the return value is -1.
 768  * @exception #I18N_ERROR_NONE Successful
 769  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 770  */
 771 int32_t i18n_ulocale_minimize_subtags ( const char *locale_id, char *minimized_locale_id, int32_t minimized_locale_id_capacity );
 772
 773 /**
 774  * @brief Returns a locale ID for the specified BCP47 language tag string.
 775  * @details If the specified language tag contains any ill-formed subtags,
 776  *          the first such subtag and all following subtags are ignored.<br>
 777  *
 778  *          This implements the 'Language-Tag' production of BCP47, and so
 779  *          supports grandfathered (regular and irregular) as well as private
 780  *          use language tags. Private use tags are represented as 'x-whatever',
 781  *          and grandfathered tags are converted to their canonical replacements
 782  *          where they exist. Note that a few grandfathered tags have no modern
 783  *          replacement, these will be converted using the fallback described in
 784  *          the first paragraph, so some information might be lost.
 785  * @remarks The specific error code can be obtained using the get_last_result() method.
 786  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 787  * @since_tizen 2.3.1
 788  *
 789  * @param[in] langtag             The input BCP47 language tag.
 790  * @param[out] locale_id          The output buffer receiving a locale ID for the
 791  *                                specified BCP47 language tag.
 792  * @param[in] locale_id_capacity  The size of the @a locale_id output buffer.
 793  * @param[in] parsed_length       If not @c NULL, successfully parsed length
 794  *                                for the input language tag is set.
 795  *
 796  * @return The length of the locale ID. If the @a langtag or @a locale_id buffer is @c NULL or the @a locale_id_capacity is lower than @c 0,
 797  *         then the #I18N_ERROR_INVALID_PARAMETER error will be set and @c -1 will be returned.
 798  *
 799  * @exception #I18N_ERROR_NONE Successful
 800  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 801  */
 802 int32_t i18n_ulocale_for_language_tag ( const char *langtag, char *locale_id, int32_t locale_id_capacity, int32_t *parsed_length );
 803
 804 /**
 805  * @brief Returns a well-formed language tag for this locale ID.
 806  * @details Note : When @a strict is @c false, any locale
 807  *          fields which do not satisfy the BCP47 syntax requirement will
 808  *          be omitted from the result.  When @a strict is
 809  *          @c true, this function sets #I18N_ERROR_INVALID_PARAMETER to the
 810  *          result if any locale fields do not satisfy the
 811  *          BCP47 syntax requirement.
 812  * @remarks The specific error code can be obtained using the get_last_result() method.
 813  *          Error codes are described in Exceptions section and #i18n_error_code_e description.
 814  * @since_tizen 2.3.1
 815  *
 816  * @param[in] locale_id         The input locale ID
 817  * @param[out] langtag          The output buffer receiving BCP47 language
 818  *                              tag for the locale ID.
 819  * @param[in] langtag_capacity  The size of the BCP47 language tag
 820  *                              output buffer.
 821  * @param[in] strict            Boolean value indicating if the function returns
 822  *                              an error for an ill-formed input locale ID.
 823  *
 824  * @return The length of the BCP47 language tag. If the @a locale_id  or @a langtag buffer is @c NULL or the @a langtag_capacity is lower than @c 0,
 825  *         then the #I18N_ERROR_INVALID_PARAMETER error will be set and @c -1 will be returned.
 826  *
 827  * @exception #I18N_ERROR_NONE Successful
 828  * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
 829  */
 830 int32_t i18n_ulocale_to_language_tag ( const char *locale_id, char *langtag, int32_t langtag_capacity, i18n_ubool strict );
 831
 832 #ifdef __cplusplus
 833 }
 834 #endif
 835
 836 /**
 837  * @}
 838  * @}
 839  */
 840
 841 #endif  /* __UTILS_I18N_ULOCALE_H__*/