]>
Commit | Line | Data |
---|---|---|
1 | /* | |
2 | ******************************************************************************* | |
3 | * Copyright (C) 2010-2016, 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__ */ |