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