1 /* 2 ******************************************************************************* 3 * Copyright (C) 2010-2014, International Business Machines Corporation and * 4 * others. All Rights Reserved. * 5 ******************************************************************************* 6 */ 7 8 #ifndef __ULDNAMES_H__ 9 #define __ULDNAMES_H__ 10 11 /** 12 * \file 13 * \brief C API: Provides display names of Locale ids and their components. 14 */ 15 16 #include "unicode/utypes.h" 17 #include "unicode/localpointer.h" 18 #include "unicode/uscript.h" 19 #include "unicode/udisplaycontext.h" 20 21 /** 22 * Enum used in LocaleDisplayNames::createInstance. 23 * @stable ICU 4.4 24 */ 25 typedef enum { 26 /** 27 * Use standard names when generating a locale name, 28 * e.g. en_GB displays as 'English (United Kingdom)'. 29 * @stable ICU 4.4 30 */ 31 ULDN_STANDARD_NAMES = 0, 32 /** 33 * Use dialect names, when generating a locale name, 34 * e.g. en_GB displays as 'British English'. 35 * @stable ICU 4.4 36 */ 37 ULDN_DIALECT_NAMES 38 } UDialectHandling; 39 40 /** 41 * Opaque C service object type for the locale display names API 42 * @stable ICU 4.4 43 */ 44 struct ULocaleDisplayNames; 45 46 /** 47 * C typedef for struct ULocaleDisplayNames. 48 * @stable ICU 4.4 49 */ 50 typedef struct ULocaleDisplayNames ULocaleDisplayNames; 51 52 #if !UCONFIG_NO_FORMATTING 53 54 /** 55 * Returns an instance of LocaleDisplayNames that returns names 56 * formatted for the provided locale, using the provided 57 * dialectHandling. The usual value for dialectHandling is 58 * ULOC_STANDARD_NAMES. 59 * 60 * @param locale the display locale 61 * @param dialectHandling how to select names for locales 62 * @return a ULocaleDisplayNames instance 63 * @param pErrorCode the status code 64 * @stable ICU 4.4 65 */ 66 U_STABLE ULocaleDisplayNames * U_EXPORT2 67 uldn_open(const char * locale, 68 UDialectHandling dialectHandling, 69 UErrorCode *pErrorCode); 70 71 /** 72 * Closes a ULocaleDisplayNames instance obtained from uldn_open(). 73 * @param ldn the ULocaleDisplayNames instance to be closed 74 * @stable ICU 4.4 75 */ 76 U_STABLE void U_EXPORT2 77 uldn_close(ULocaleDisplayNames *ldn); 78 79 #if U_SHOW_CPLUSPLUS_API 80 81 U_NAMESPACE_BEGIN 82 83 /** 84 * \class LocalULocaleDisplayNamesPointer 85 * "Smart pointer" class, closes a ULocaleDisplayNames via uldn_close(). 86 * For most methods see the LocalPointerBase base class. 87 * 88 * @see LocalPointerBase 89 * @see LocalPointer 90 * @stable ICU 4.4 91 */ 92 U_DEFINE_LOCAL_OPEN_POINTER(LocalULocaleDisplayNamesPointer, ULocaleDisplayNames, uldn_close); 93 94 U_NAMESPACE_END 95 96 #endif 97 98 /* getters for state */ 99 100 /** 101 * Returns the locale used to determine the display names. This is 102 * not necessarily the same locale passed to {@link #uldn_open}. 103 * @param ldn the LocaleDisplayNames instance 104 * @return the display locale 105 * @stable ICU 4.4 106 */ 107 U_STABLE const char * U_EXPORT2 108 uldn_getLocale(const ULocaleDisplayNames *ldn); 109 110 /** 111 * Returns the dialect handling used in the display names. 112 * @param ldn the LocaleDisplayNames instance 113 * @return the dialect handling enum 114 * @stable ICU 4.4 115 */ 116 U_STABLE UDialectHandling U_EXPORT2 117 uldn_getDialectHandling(const ULocaleDisplayNames *ldn); 118 119 /* names for entire locales */ 120 121 /** 122 * Returns the display name of the provided locale. 123 * @param ldn the LocaleDisplayNames instance 124 * @param locale the locale whose display name to return 125 * @param result receives the display name 126 * @param maxResultSize the size of the result buffer 127 * @param pErrorCode the status code 128 * @return the actual buffer size needed for the display name. If it's 129 * greater than maxResultSize, the returned name will be truncated. 130 * @stable ICU 4.4 131 */ 132 U_STABLE int32_t U_EXPORT2 133 uldn_localeDisplayName(const ULocaleDisplayNames *ldn, 134 const char *locale, 135 UChar *result, 136 int32_t maxResultSize, 137 UErrorCode *pErrorCode); 138 139 /* names for components of a locale */ 140 141 /** 142 * Returns the display name of the provided language code. 143 * @param ldn the LocaleDisplayNames instance 144 * @param lang the language code whose display name to return 145 * @param result receives the display name 146 * @param maxResultSize the size of the result buffer 147 * @param pErrorCode the status code 148 * @return the actual buffer size needed for the display name. If it's 149 * greater than maxResultSize, the returned name will be truncated. 150 * @stable ICU 4.4 151 */ 152 U_STABLE int32_t U_EXPORT2 153 uldn_languageDisplayName(const ULocaleDisplayNames *ldn, 154 const char *lang, 155 UChar *result, 156 int32_t maxResultSize, 157 UErrorCode *pErrorCode); 158 159 /** 160 * Returns the display name of the provided script. 161 * @param ldn the LocaleDisplayNames instance 162 * @param script the script whose display name to return 163 * @param result receives the display name 164 * @param maxResultSize the size of the result buffer 165 * @param pErrorCode the status code 166 * @return the actual buffer size needed for the display name. If it's 167 * greater than maxResultSize, the returned name will be truncated. 168 * @stable ICU 4.4 169 */ 170 U_STABLE int32_t U_EXPORT2 171 uldn_scriptDisplayName(const ULocaleDisplayNames *ldn, 172 const char *script, 173 UChar *result, 174 int32_t maxResultSize, 175 UErrorCode *pErrorCode); 176 177 /** 178 * Returns the display name of the provided script code. 179 * @param ldn the LocaleDisplayNames instance 180 * @param scriptCode the script code whose display name to return 181 * @param result receives the display name 182 * @param maxResultSize the size of the result buffer 183 * @param pErrorCode the status code 184 * @return the actual buffer size needed for the display name. If it's 185 * greater than maxResultSize, the returned name will be truncated. 186 * @stable ICU 4.4 187 */ 188 U_STABLE int32_t U_EXPORT2 189 uldn_scriptCodeDisplayName(const ULocaleDisplayNames *ldn, 190 UScriptCode scriptCode, 191 UChar *result, 192 int32_t maxResultSize, 193 UErrorCode *pErrorCode); 194 195 /** 196 * Returns the display name of the provided region code. 197 * @param ldn the LocaleDisplayNames instance 198 * @param region the region code whose display name to return 199 * @param result receives the display name 200 * @param maxResultSize the size of the result buffer 201 * @param pErrorCode the status code 202 * @return the actual buffer size needed for the display name. If it's 203 * greater than maxResultSize, the returned name will be truncated. 204 * @stable ICU 4.4 205 */ 206 U_STABLE int32_t U_EXPORT2 207 uldn_regionDisplayName(const ULocaleDisplayNames *ldn, 208 const char *region, 209 UChar *result, 210 int32_t maxResultSize, 211 UErrorCode *pErrorCode); 212 213 /** 214 * Returns the display name of the provided variant 215 * @param ldn the LocaleDisplayNames instance 216 * @param variant the variant whose display name to return 217 * @param result receives the display name 218 * @param maxResultSize the size of the result buffer 219 * @param pErrorCode the status code 220 * @return the actual buffer size needed for the display name. If it's 221 * greater than maxResultSize, the returned name will be truncated. 222 * @stable ICU 4.4 223 */ 224 U_STABLE int32_t U_EXPORT2 225 uldn_variantDisplayName(const ULocaleDisplayNames *ldn, 226 const char *variant, 227 UChar *result, 228 int32_t maxResultSize, 229 UErrorCode *pErrorCode); 230 231 /** 232 * Returns the display name of the provided locale key 233 * @param ldn the LocaleDisplayNames instance 234 * @param key the locale key whose display name to return 235 * @param result receives the display name 236 * @param maxResultSize the size of the result buffer 237 * @param pErrorCode the status code 238 * @return the actual buffer size needed for the display name. If it's 239 * greater than maxResultSize, the returned name will be truncated. 240 * @stable ICU 4.4 241 */ 242 U_STABLE int32_t U_EXPORT2 243 uldn_keyDisplayName(const ULocaleDisplayNames *ldn, 244 const char *key, 245 UChar *result, 246 int32_t maxResultSize, 247 UErrorCode *pErrorCode); 248 249 /** 250 * Returns the display name of the provided value (used with the provided key). 251 * @param ldn the LocaleDisplayNames instance 252 * @param key the locale key 253 * @param value the locale key's value 254 * @param result receives the display name 255 * @param maxResultSize the size of the result buffer 256 * @param pErrorCode the status code 257 * @return the actual buffer size needed for the display name. If it's 258 * greater than maxResultSize, the returned name will be truncated. 259 * @stable ICU 4.4 260 */ 261 U_STABLE int32_t U_EXPORT2 262 uldn_keyValueDisplayName(const ULocaleDisplayNames *ldn, 263 const char *key, 264 const char *value, 265 UChar *result, 266 int32_t maxResultSize, 267 UErrorCode *pErrorCode); 268 269 /** 270 * Returns an instance of LocaleDisplayNames that returns names formatted 271 * for the provided locale, using the provided UDisplayContext settings. 272 * 273 * @param locale The display locale 274 * @param contexts List of one or more context settings (e.g. for dialect 275 * handling, capitalization, etc. 276 * @param length Number of items in the contexts list 277 * @param pErrorCode Pointer to UErrorCode input/output status. If at entry this indicates 278 * a failure status, the function will do nothing; otherwise this will be 279 * updated with any new status from the function. 280 * @return a ULocaleDisplayNames instance 281 * @stable ICU 51 282 */ 283 U_STABLE ULocaleDisplayNames * U_EXPORT2 284 uldn_openForContext(const char * locale, UDisplayContext *contexts, 285 int32_t length, UErrorCode *pErrorCode); 286 287 /** 288 * Returns the UDisplayContext value for the specified UDisplayContextType. 289 * @param ldn the ULocaleDisplayNames instance 290 * @param type the UDisplayContextType whose value to return 291 * @param pErrorCode Pointer to UErrorCode input/output status. If at entry this indicates 292 * a failure status, the function will do nothing; otherwise this will be 293 * updated with any new status from the function. 294 * @return the UDisplayContextValue for the specified type. 295 * @stable ICU 51 296 */ 297 U_STABLE UDisplayContext U_EXPORT2 298 uldn_getContext(const ULocaleDisplayNames *ldn, UDisplayContextType type, 299 UErrorCode *pErrorCode); 300 301 #endif /* !UCONFIG_NO_FORMATTING */ 302 #endif /* __ULDNAMES_H__ */ 303
