| /* |
| ******************************************************************************* |
| * Copyright (C) 2010-2014, International Business Machines Corporation and * |
| * others. All Rights Reserved. * |
| ******************************************************************************* |
| */ |
| |
| #ifndef __ULDNAMES_H__ |
| #define __ULDNAMES_H__ |
| |
| /** |
| * \file |
| * \brief C API: Provides display names of Locale ids and their components. |
| */ |
| |
| #include "unicode/utypes.h" |
| #include "unicode/localpointer.h" |
| #include "unicode/uscript.h" |
| #include "unicode/udisplaycontext.h" |
| |
| /** |
| * Enum used in LocaleDisplayNames::createInstance. |
| * @stable ICU 4.4 |
| */ |
| typedef enum { |
| /** |
| * Use standard names when generating a locale name, |
| * e.g. en_GB displays as 'English (United Kingdom)'. |
| * @stable ICU 4.4 |
| */ |
| ULDN_STANDARD_NAMES = 0, |
| /** |
| * Use dialect names, when generating a locale name, |
| * e.g. en_GB displays as 'British English'. |
| * @stable ICU 4.4 |
| */ |
| ULDN_DIALECT_NAMES |
| } UDialectHandling; |
| |
| /** |
| * Opaque C service object type for the locale display names API |
| * @stable ICU 4.4 |
| */ |
| struct ULocaleDisplayNames; |
| |
| /** |
| * C typedef for struct ULocaleDisplayNames. |
| * @stable ICU 4.4 |
| */ |
| typedef struct ULocaleDisplayNames ULocaleDisplayNames; |
| |
| #if !UCONFIG_NO_FORMATTING |
| |
| /** |
| * Returns an instance of LocaleDisplayNames that returns names |
| * formatted for the provided locale, using the provided |
| * dialectHandling. The usual value for dialectHandling is |
| * ULOC_STANDARD_NAMES. |
| * |
| * @param locale the display locale |
| * @param dialectHandling how to select names for locales |
| * @return a ULocaleDisplayNames instance |
| * @param pErrorCode the status code |
| * @stable ICU 4.4 |
| */ |
| U_STABLE ULocaleDisplayNames * U_EXPORT2 |
| uldn_open(const char * locale, |
| UDialectHandling dialectHandling, |
| UErrorCode *pErrorCode); |
| |
| /** |
| * Closes a ULocaleDisplayNames instance obtained from uldn_open(). |
| * @param ldn the ULocaleDisplayNames instance to be closed |
| * @stable ICU 4.4 |
| */ |
| U_STABLE void U_EXPORT2 |
| uldn_close(ULocaleDisplayNames *ldn); |
| |
| #if U_SHOW_CPLUSPLUS_API |
| |
| U_NAMESPACE_BEGIN |
| |
| /** |
| * \class LocalULocaleDisplayNamesPointer |
| * "Smart pointer" class, closes a ULocaleDisplayNames via uldn_close(). |
| * For most methods see the LocalPointerBase base class. |
| * |
| * @see LocalPointerBase |
| * @see LocalPointer |
| * @stable ICU 4.4 |
| */ |
| U_DEFINE_LOCAL_OPEN_POINTER(LocalULocaleDisplayNamesPointer, ULocaleDisplayNames, uldn_close); |
| |
| U_NAMESPACE_END |
| |
| #endif |
| |
| /* getters for state */ |
| |
| /** |
| * Returns the locale used to determine the display names. This is |
| * not necessarily the same locale passed to {@link #uldn_open}. |
| * @param ldn the LocaleDisplayNames instance |
| * @return the display locale |
| * @stable ICU 4.4 |
| */ |
| U_STABLE const char * U_EXPORT2 |
| uldn_getLocale(const ULocaleDisplayNames *ldn); |
| |
| /** |
| * Returns the dialect handling used in the display names. |
| * @param ldn the LocaleDisplayNames instance |
| * @return the dialect handling enum |
| * @stable ICU 4.4 |
| */ |
| U_STABLE UDialectHandling U_EXPORT2 |
| uldn_getDialectHandling(const ULocaleDisplayNames *ldn); |
| |
| /* names for entire locales */ |
| |
| /** |
| * Returns the display name of the provided locale. |
| * @param ldn the LocaleDisplayNames instance |
| * @param locale the locale whose display name to return |
| * @param result receives the display name |
| * @param maxResultSize the size of the result buffer |
| * @param pErrorCode the status code |
| * @return the actual buffer size needed for the display name. If it's |
| * greater than maxResultSize, the returned name will be truncated. |
| * @stable ICU 4.4 |
| */ |
| U_STABLE int32_t U_EXPORT2 |
| uldn_localeDisplayName(const ULocaleDisplayNames *ldn, |
| const char *locale, |
| UChar *result, |
| int32_t maxResultSize, |
| UErrorCode *pErrorCode); |
| |
| /* names for components of a locale */ |
| |
| /** |
| * Returns the display name of the provided language code. |
| * @param ldn the LocaleDisplayNames instance |
| * @param lang the language code whose display name to return |
| * @param result receives the display name |
| * @param maxResultSize the size of the result buffer |
| * @param pErrorCode the status code |
| * @return the actual buffer size needed for the display name. If it's |
| * greater than maxResultSize, the returned name will be truncated. |
| * @stable ICU 4.4 |
| */ |
| U_STABLE int32_t U_EXPORT2 |
| uldn_languageDisplayName(const ULocaleDisplayNames *ldn, |
| const char *lang, |
| UChar *result, |
| int32_t maxResultSize, |
| UErrorCode *pErrorCode); |
| |
| /** |
| * Returns the display name of the provided script. |
| * @param ldn the LocaleDisplayNames instance |
| * @param script the script whose display name to return |
| * @param result receives the display name |
| * @param maxResultSize the size of the result buffer |
| * @param pErrorCode the status code |
| * @return the actual buffer size needed for the display name. If it's |
| * greater than maxResultSize, the returned name will be truncated. |
| * @stable ICU 4.4 |
| */ |
| U_STABLE int32_t U_EXPORT2 |
| uldn_scriptDisplayName(const ULocaleDisplayNames *ldn, |
| const char *script, |
| UChar *result, |
| int32_t maxResultSize, |
| UErrorCode *pErrorCode); |
| |
| /** |
| * Returns the display name of the provided script code. |
| * @param ldn the LocaleDisplayNames instance |
| * @param scriptCode the script code whose display name to return |
| * @param result receives the display name |
| * @param maxResultSize the size of the result buffer |
| * @param pErrorCode the status code |
| * @return the actual buffer size needed for the display name. If it's |
| * greater than maxResultSize, the returned name will be truncated. |
| * @stable ICU 4.4 |
| */ |
| U_STABLE int32_t U_EXPORT2 |
| uldn_scriptCodeDisplayName(const ULocaleDisplayNames *ldn, |
| UScriptCode scriptCode, |
| UChar *result, |
| int32_t maxResultSize, |
| UErrorCode *pErrorCode); |
| |
| /** |
| * Returns the display name of the provided region code. |
| * @param ldn the LocaleDisplayNames instance |
| * @param region the region code whose display name to return |
| * @param result receives the display name |
| * @param maxResultSize the size of the result buffer |
| * @param pErrorCode the status code |
| * @return the actual buffer size needed for the display name. If it's |
| * greater than maxResultSize, the returned name will be truncated. |
| * @stable ICU 4.4 |
| */ |
| U_STABLE int32_t U_EXPORT2 |
| uldn_regionDisplayName(const ULocaleDisplayNames *ldn, |
| const char *region, |
| UChar *result, |
| int32_t maxResultSize, |
| UErrorCode *pErrorCode); |
| |
| /** |
| * Returns the display name of the provided variant |
| * @param ldn the LocaleDisplayNames instance |
| * @param variant the variant whose display name to return |
| * @param result receives the display name |
| * @param maxResultSize the size of the result buffer |
| * @param pErrorCode the status code |
| * @return the actual buffer size needed for the display name. If it's |
| * greater than maxResultSize, the returned name will be truncated. |
| * @stable ICU 4.4 |
| */ |
| U_STABLE int32_t U_EXPORT2 |
| uldn_variantDisplayName(const ULocaleDisplayNames *ldn, |
| const char *variant, |
| UChar *result, |
| int32_t maxResultSize, |
| UErrorCode *pErrorCode); |
| |
| /** |
| * Returns the display name of the provided locale key |
| * @param ldn the LocaleDisplayNames instance |
| * @param key the locale key whose display name to return |
| * @param result receives the display name |
| * @param maxResultSize the size of the result buffer |
| * @param pErrorCode the status code |
| * @return the actual buffer size needed for the display name. If it's |
| * greater than maxResultSize, the returned name will be truncated. |
| * @stable ICU 4.4 |
| */ |
| U_STABLE int32_t U_EXPORT2 |
| uldn_keyDisplayName(const ULocaleDisplayNames *ldn, |
| const char *key, |
| UChar *result, |
| int32_t maxResultSize, |
| UErrorCode *pErrorCode); |
| |
| /** |
| * Returns the display name of the provided value (used with the provided key). |
| * @param ldn the LocaleDisplayNames instance |
| * @param key the locale key |
| * @param value the locale key's value |
| * @param result receives the display name |
| * @param maxResultSize the size of the result buffer |
| * @param pErrorCode the status code |
| * @return the actual buffer size needed for the display name. If it's |
| * greater than maxResultSize, the returned name will be truncated. |
| * @stable ICU 4.4 |
| */ |
| U_STABLE int32_t U_EXPORT2 |
| uldn_keyValueDisplayName(const ULocaleDisplayNames *ldn, |
| const char *key, |
| const char *value, |
| UChar *result, |
| int32_t maxResultSize, |
| UErrorCode *pErrorCode); |
| |
| /** |
| * Returns an instance of LocaleDisplayNames that returns names formatted |
| * for the provided locale, using the provided UDisplayContext settings. |
| * |
| * @param locale The display locale |
| * @param contexts List of one or more context settings (e.g. for dialect |
| * handling, capitalization, etc. |
| * @param length Number of items in the contexts list |
| * @param pErrorCode Pointer to UErrorCode input/output status. If at entry this indicates |
| * a failure status, the function will do nothing; otherwise this will be |
| * updated with any new status from the function. |
| * @return a ULocaleDisplayNames instance |
| * @stable ICU 51 |
| */ |
| U_STABLE ULocaleDisplayNames * U_EXPORT2 |
| uldn_openForContext(const char * locale, UDisplayContext *contexts, |
| int32_t length, UErrorCode *pErrorCode); |
| |
| /** |
| * Returns the UDisplayContext value for the specified UDisplayContextType. |
| * @param ldn the ULocaleDisplayNames instance |
| * @param type the UDisplayContextType whose value to return |
| * @param pErrorCode Pointer to UErrorCode input/output status. If at entry this indicates |
| * a failure status, the function will do nothing; otherwise this will be |
| * updated with any new status from the function. |
| * @return the UDisplayContextValue for the specified type. |
| * @stable ICU 51 |
| */ |
| U_STABLE UDisplayContext U_EXPORT2 |
| uldn_getContext(const ULocaleDisplayNames *ldn, UDisplayContextType type, |
| UErrorCode *pErrorCode); |
| |
| #endif /* !UCONFIG_NO_FORMATTING */ |
| #endif /* __ULDNAMES_H__ */ |
