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 */
25typedef 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 */
44struct ULocaleDisplayNames;
45
46/**
47 * C typedef for struct ULocaleDisplayNames.
48 * @stable ICU 4.4
49 */
50typedef 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 */
66U_STABLE ULocaleDisplayNames * U_EXPORT2
67uldn_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 */
76U_STABLE void U_EXPORT2
77uldn_close(ULocaleDisplayNames *ldn);
78
79#if U_SHOW_CPLUSPLUS_API
80
81U_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 */
92U_DEFINE_LOCAL_OPEN_POINTER(LocalULocaleDisplayNamesPointer, ULocaleDisplayNames, uldn_close);
93
94U_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 */
107U_STABLE const char * U_EXPORT2
108uldn_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 */
116U_STABLE UDialectHandling U_EXPORT2
117uldn_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 */
132U_STABLE int32_t U_EXPORT2
133uldn_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 */
152U_STABLE int32_t U_EXPORT2
153uldn_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 */
170U_STABLE int32_t U_EXPORT2
171uldn_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 */
188U_STABLE int32_t U_EXPORT2
189uldn_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 */
206U_STABLE int32_t U_EXPORT2
207uldn_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 */
224U_STABLE int32_t U_EXPORT2
225uldn_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 */
242U_STABLE int32_t U_EXPORT2
243uldn_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 */
261U_STABLE int32_t U_EXPORT2
262uldn_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*/
283U_STABLE ULocaleDisplayNames * U_EXPORT2
284uldn_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*/
297U_STABLE UDisplayContext U_EXPORT2
298uldn_getContext(const ULocaleDisplayNames *ldn, UDisplayContextType type,
299                UErrorCode *pErrorCode);
300
301#endif  /* !UCONFIG_NO_FORMATTING */
302#endif  /* __ULDNAMES_H__ */
303