CFLocale.h

   1 /*
   2  * Copyright (c) 2012 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 /*      CFLocale.h
  25         Copyright (c) 2002-2011, Apple Inc. All rights reserved.
  26 */
  27
  28 #if !defined(__COREFOUNDATION_CFLOCALE__)
  29 #define __COREFOUNDATION_CFLOCALE__ 1
  30
  31 #include <CoreFoundation/CFBase.h>
  32 #include <CoreFoundation/CFArray.h>
  33 #include <CoreFoundation/CFDictionary.h>
  34
  35 CF_EXTERN_C_BEGIN
  36
  37 typedef const struct __CFLocale *CFLocaleRef;
  38
  39 CF_EXPORT
  40 CFTypeID CFLocaleGetTypeID(void);
  41
  42 CF_EXPORT
  43 CFLocaleRef CFLocaleGetSystem(void);
  44         // Returns the "root", canonical locale.  Contains fixed "backstop" settings.
  45
  46 CF_EXPORT
  47 CFLocaleRef CFLocaleCopyCurrent(void);
  48         // Returns the logical "user" locale for the current user.
  49         // [This is Copy in the sense that you get a retain you have to release,
  50         // but we may return the same cached object over and over.]  Settings
  51         // you get from this locale do not change under you as CFPreferences
  52         // are changed (for safety and correctness).  Generally you would not
  53         // grab this and hold onto it forever, but use it to do the operations
  54         // you need to do at the moment, then throw it away.  (The non-changing
  55         // ensures that all the results of your operations are consistent.)
  56
  57 CF_EXPORT
  58 CFArrayRef CFLocaleCopyAvailableLocaleIdentifiers(void);
  59         // Returns an array of CFStrings that represents all locales for
  60         // which locale data is available.
  61
  62 CF_EXPORT
  63 CFArrayRef CFLocaleCopyISOLanguageCodes(void);
  64         // Returns an array of CFStrings that represents all known legal ISO
  65         // language codes.  Note: many of these will not have any supporting
  66         // locale data in Mac OS X.
  67
  68 CF_EXPORT
  69 CFArrayRef CFLocaleCopyISOCountryCodes(void);
  70         // Returns an array of CFStrings that represents all known legal ISO
  71         // country codes.  Note: many of these will not have any supporting
  72         // locale data in Mac OS X.
  73
  74 CF_EXPORT
  75 CFArrayRef CFLocaleCopyISOCurrencyCodes(void);
  76         // Returns an array of CFStrings that represents all known legal ISO
  77         // currency codes.  Note: some of these currencies may be obsolete, or
  78         // represent other financial instruments.
  79
  80 CF_EXPORT
  81 CFArrayRef CFLocaleCopyCommonISOCurrencyCodes(void) CF_AVAILABLE(10_5, 2_0);
  82         // Returns an array of CFStrings that represents ISO currency codes for
  83         // currencies in common use.
  84
  85 CF_EXPORT
  86 CFArrayRef CFLocaleCopyPreferredLanguages(void) CF_AVAILABLE(10_5, 2_0);
  87         // Returns the array of canonicalized CFString locale IDs that the user prefers.
  88
  89 CF_EXPORT
  90 CFStringRef CFLocaleCreateCanonicalLanguageIdentifierFromString(CFAllocatorRef allocator, CFStringRef localeIdentifier);
  91         // Map an arbitrary language identification string (something close at
  92         // least) to a canonical language identifier.
  93
  94 CF_EXPORT
  95 CFStringRef CFLocaleCreateCanonicalLocaleIdentifierFromString(CFAllocatorRef allocator, CFStringRef localeIdentifier);
  96         // Map an arbitrary locale identification string (something close at
  97         // least) to the canonical identifier.
  98
  99 CF_EXPORT
 100 CFStringRef CFLocaleCreateCanonicalLocaleIdentifierFromScriptManagerCodes(CFAllocatorRef allocator, LangCode lcode, RegionCode rcode);
 101         // Map a Mac OS LangCode and RegionCode to the canonical locale identifier.
 102
 103 CF_EXPORT
 104 CFStringRef CFLocaleCreateLocaleIdentifierFromWindowsLocaleCode(CFAllocatorRef allocator, uint32_t lcid) CF_AVAILABLE(10_6, 4_0);
 105         // Map a Windows LCID to the canonical locale identifier.
 106
 107 CF_EXPORT
 108 uint32_t CFLocaleGetWindowsLocaleCodeFromLocaleIdentifier(CFStringRef localeIdentifier) CF_AVAILABLE(10_6, 4_0);
 109         // Map a locale identifier to a Windows LCID.
 110
 111 enum {
 112     kCFLocaleLanguageDirectionUnknown = 0,
 113     kCFLocaleLanguageDirectionLeftToRight = 1,
 114     kCFLocaleLanguageDirectionRightToLeft = 2,
 115     kCFLocaleLanguageDirectionTopToBottom = 3,
 116     kCFLocaleLanguageDirectionBottomToTop = 4
 117 };
 118 typedef CFIndex CFLocaleLanguageDirection;
 119
 120 CF_EXPORT
 121 CFLocaleLanguageDirection CFLocaleGetLanguageCharacterDirection(CFStringRef isoLangCode) CF_AVAILABLE(10_6, 4_0);
 122
 123 CF_EXPORT
 124 CFLocaleLanguageDirection CFLocaleGetLanguageLineDirection(CFStringRef isoLangCode) CF_AVAILABLE(10_6, 4_0);
 125
 126 CF_EXPORT
 127 CFDictionaryRef CFLocaleCreateComponentsFromLocaleIdentifier(CFAllocatorRef allocator, CFStringRef localeID);
 128         // Parses a locale ID consisting of language, script, country, variant,
 129         // and keyword/value pairs into a dictionary. The keys are the constant
 130         // CFStrings corresponding to the locale ID components, and the values
 131         // will correspond to constants where available.
 132         // Example: "en_US@calendar=japanese" yields a dictionary with three
 133         // entries: kCFLocaleLanguageCode=en, kCFLocaleCountryCode=US, and
 134         // kCFLocaleCalendarIdentifier=kCFJapaneseCalendar.
 135
 136 CF_EXPORT
 137 CFStringRef CFLocaleCreateLocaleIdentifierFromComponents(CFAllocatorRef allocator, CFDictionaryRef dictionary);
 138         // Reverses the actions of CFLocaleCreateDictionaryFromLocaleIdentifier,
 139         // creating a single string from the data in the dictionary. The
 140         // dictionary {kCFLocaleLanguageCode=en, kCFLocaleCountryCode=US,
 141         // kCFLocaleCalendarIdentifier=kCFJapaneseCalendar} becomes
 142         // "en_US@calendar=japanese".
 143
 144 CF_EXPORT
 145 CFLocaleRef CFLocaleCreate(CFAllocatorRef allocator, CFStringRef localeIdentifier);
 146         // Returns a CFLocaleRef for the locale named by the "arbitrary" locale identifier.
 147
 148 CF_EXPORT
 149 CFLocaleRef CFLocaleCreateCopy(CFAllocatorRef allocator, CFLocaleRef locale);
 150         // Having gotten a CFLocale from somebody, code should make a copy
 151         // if it is going to use it for several operations
 152         // or hold onto it.  In the future, there may be mutable locales.
 153
 154 CF_EXPORT
 155 CFStringRef CFLocaleGetIdentifier(CFLocaleRef locale);
 156         // Returns the locale's identifier.  This may not be the same string
 157         // that the locale was created with (CFLocale may canonicalize it).
 158
 159 CF_EXPORT
 160 CFTypeRef CFLocaleGetValue(CFLocaleRef locale, CFStringRef key);
 161         // Returns the value for the given key.  This is how settings and state
 162         // are accessed via a CFLocale.  Values might be of any CF type.
 163
 164 CF_EXPORT
 165 CFStringRef CFLocaleCopyDisplayNameForPropertyValue(CFLocaleRef displayLocale, CFStringRef key, CFStringRef value);
 166         // Returns the display name for the given value.  The key tells what
 167         // the value is, and is one of the usual locale property keys, though
 168         // not all locale property keys have values with display name values.
 169
 170
 171 CF_EXPORT const CFStringRef kCFLocaleCurrentLocaleDidChangeNotification CF_AVAILABLE(10_5, 2_0);
 172
 173
 174 // Locale Keys
 175 CF_EXPORT const CFStringRef kCFLocaleIdentifier;
 176 CF_EXPORT const CFStringRef kCFLocaleLanguageCode;
 177 CF_EXPORT const CFStringRef kCFLocaleCountryCode;
 178 CF_EXPORT const CFStringRef kCFLocaleScriptCode;
 179 CF_EXPORT const CFStringRef kCFLocaleVariantCode;
 180
 181 CF_EXPORT const CFStringRef kCFLocaleExemplarCharacterSet;
 182 CF_EXPORT const CFStringRef kCFLocaleCalendarIdentifier;
 183 CF_EXPORT const CFStringRef kCFLocaleCalendar;
 184 CF_EXPORT const CFStringRef kCFLocaleCollationIdentifier;
 185 CF_EXPORT const CFStringRef kCFLocaleUsesMetricSystem;
 186 CF_EXPORT const CFStringRef kCFLocaleMeasurementSystem; // "Metric" or "U.S."
 187 CF_EXPORT const CFStringRef kCFLocaleDecimalSeparator;
 188 CF_EXPORT const CFStringRef kCFLocaleGroupingSeparator;
 189 CF_EXPORT const CFStringRef kCFLocaleCurrencySymbol;
 190 CF_EXPORT const CFStringRef kCFLocaleCurrencyCode; // ISO 3-letter currency code
 191 CF_EXPORT const CFStringRef kCFLocaleCollatorIdentifier CF_AVAILABLE(10_6, 4_0);
 192 CF_EXPORT const CFStringRef kCFLocaleQuotationBeginDelimiterKey CF_AVAILABLE(10_6, 4_0);
 193 CF_EXPORT const CFStringRef kCFLocaleQuotationEndDelimiterKey CF_AVAILABLE(10_6, 4_0);
 194 CF_EXPORT const CFStringRef kCFLocaleAlternateQuotationBeginDelimiterKey CF_AVAILABLE(10_6, 4_0);
 195 CF_EXPORT const CFStringRef kCFLocaleAlternateQuotationEndDelimiterKey CF_AVAILABLE(10_6, 4_0);
 196
 197 // Values for kCFLocaleCalendarIdentifier
 198 CF_EXPORT const CFStringRef kCFGregorianCalendar;
 199 CF_EXPORT const CFStringRef kCFBuddhistCalendar;
 200 CF_EXPORT const CFStringRef kCFChineseCalendar;
 201 CF_EXPORT const CFStringRef kCFHebrewCalendar;
 202 CF_EXPORT const CFStringRef kCFIslamicCalendar;
 203 CF_EXPORT const CFStringRef kCFIslamicCivilCalendar;
 204 CF_EXPORT const CFStringRef kCFJapaneseCalendar;
 205 CF_EXPORT const CFStringRef kCFRepublicOfChinaCalendar CF_AVAILABLE(10_6, 4_0);
 206 CF_EXPORT const CFStringRef kCFPersianCalendar CF_AVAILABLE(10_6, 4_0);
 207 CF_EXPORT const CFStringRef kCFIndianCalendar CF_AVAILABLE(10_6, 4_0);
 208 CF_EXPORT const CFStringRef kCFISO8601Calendar CF_AVAILABLE(10_6, 4_0);
 209
 210 CF_EXTERN_C_END
 211
 212 #endif /* ! __COREFOUNDATION_CFLOCALE__ */
 213