Some suggested updates to the Win32-->.NET mapping for NLS functions....

by Michael S. Kaplan, published on 2005/02/27 08:25 -05:00, original URI: http://blogs.msdn.com/b/michkap/archive/2005/02/27/381189.aspx

The other day I posted about the Microsoft Win32 to Microsoft .NET Framework API Map and commented that there were some mistakes in the NLS functions there.

Here is a quick list of things I would change (I will send the link as feedback, too). The key to the changed table:

1. If I had no suggested changes, I did not include it in the table.
2. If the .NET suggestion was wrong or inaccurate enough, it is grayed and struck out.
3. If the .NET suggestion was close enough to right but needed more info, it is just grayed out.

The APIs that were not included here but were put elsewhere, or not included at all:

• CompareString -- see also the System.Globalization.CompareInfo class, which gives the full functionality of thae API;
• lstrcmp -- see also System.Globalization.CultureInfo.CurrentCulture.CompareInfo;
• lstrcmpi -- see also System.Globalization.CultureInfo.CurrentCulture.CompareInfo with CompareOptions.IgnoreCase;
• Foldstring -- not included in the page, no support in 1.1, but in 2.0 String.Normalize() and CharUnicodeInfo.GetDecimalDigitValue() can do quite a good job on them, as described here and here.

UPDATED National Language Functions -- only ones with additions and changes listed:

Win32 function	Description	.NET Framework API
ConvertDefaultLocale	Converts a default locale value to an actual locale identifier.	System.Globalization.CultureInfo.CurrentCulture System.Globalization.CultureInfo.InstalledUICulture Actually, you would use the static System.Globalization.CultureInfo.CreateSpecificCulture() method to create a specific culture from a neutral one, which is what that API does.
EnumCalendarInfo	Enumerates calendar information for a specified locale.	Access the System.Globalization.CultureInfo.DateTimeFormat property to get a System.Globalization.DateTimeFormatInfo object, and then access its properties: System.Globalization.DateTimeFormatInfo.AbbreviatedDayNames System.Globalization.DateTimeFormatInfo.AbbreviatedMonthNames System.Globalization.DateTimeFormatInfo.DayNames System.Globalization.DateTimeFormatInfo.LongDatePattern System.Globalization.DateTimeFormatInfo.MonthNames System.Globalization.DateTimeFormatInfo.ShortDatePattern Let's not forget the most important part -- you need to look at the information after setting the desired Calendar on the culture, first!
EnumDateFormats	Enumerates the long or short date formats that are available for a specified locale.	System.DateTime.GetDateTimeFormats(System.Globalization.CultureInfo) Or alternately, DateTimeFormatInfo.GetAllDateTimePatterns()
EnumDateFormatsEx	Enumerates the long or short date formats that are available for a specified locale, including date formats for any alternate calendars.	Iterate through the calendars: System.Globalization.CultureInfo.DateTimeFormat.Calendar = System.Globalization.CultureInfo.OptionalCalendars[i]; System.DateTime.GetDateTimeFormats(System.Globalization.CultureInfo) Or alternately, DateTimeFormatInfo.GetAllDateTimePatterns()
EnumSystemCodePages	Enumerates the code pages that are either installed on or supported by a system.	System.Globalization.CultureInfo.GetCultures(System.Globalization.CultureTypes.AllCultures) returns an array of CultureInfo The various code page properties of System.Globalization.CultureInfo.TextInfo This will not get all of the code pages and will show many repeats of those it does get -- it will also sometimes retrieve IDs that are not supported. There is not a good enumeration methodology for the supported code pages in .NET 1.1 -- but look for new enumeration methods in 2.0!
EnumSystemGeoID	Enumerates all GeoIDs on the system.	Retrieve an array of CultureInfo by calling System.Globalization.CultureInfo.GetCultures(System.Globalization.CultureTypes.AllCultures), and then access the following CultureInfo properties: System.Globalization.CultureInfo.ThreeLetterISOLanguageName System.Globalization.CultureInfo.ThreeLetterWindowsLanguageName System.Globalization.CultureInfo.TwoLetterISOLanguageName GeoID is not supported in .NET 1.1 and it is actually region-based, not language based. .NET 2.0 will support a RegionInfo.GeoId property.
EnumSystemLocales	Enumerates the locales that are either installed on or supported by a system.	System.Globalization.CultureInfo.GetCultures(System.Globalization.CultureTypes.SpecificCultures) System.Globalization.CultureInfo.GetCultures(System.Globalization.CultureTypes.InstalledWin32Cultures) Note that there is no method that can be used to get the alternate sorts, one of the important features this API supports.
EnumTimeFormats	Enumerates the time formats that are available for a specified locale.	System.DateTime.GetDateTimeFormats Or alternately, DateTimeFormatInfo.GetAllDateTimePatterns()
GetACP	Retrieves the current ANSI code-page identifier for the system.	System.Globalization.CultureInfo.InstalledUICulture.TextInfo.ANSICodePage Try Encoding.Default.CodePage, instead.
GetCalendarInfo	Retrieves information about a calendar.	System.Globalization.CultureInfo.DateTimeFormat This will only work for the currently selected Calendar -- make sure to set the Calendar from which you would like information, first.
GetLocaleInfo	Retrieves information about a locale.	System.Globalization.CultureInfo.DateTimeFormat System.Globalization.CultureInfo.NumberFormat System.Globalization.CultureInfo.TextInfo Well, instead of that, how about everything under: System.Globalization.CultureInfo System.Globalization.RegionInfo
GetOEMCP	Retrieves the current original equipment manufacturer (OEM) code-page identifier for the system.	System.Globalization.CultureInfo.InstalledUICulture.TextInfo.OEMCodePage The real OEMCP of a system is based on the default system locale, which can be changed. The Installed UI language cannot be.
GetSystemDefaultLangID	Retrieves the language identifier of the system locale.	System.Globalization.CultureInfo.InstalledUICulture The default LANGID of a system is based on the default system locale, which can be changed. The Installed UI language cannot be.
GetSystemDefaultLCID	Retrieves the system default locale identifier.	System.Globalization.CultureInfo.InstalledUICulture The system default LCID is the default system locale, which can be changed. The Installed UI language cannot be.
GetThreadLocale	Retrieves the current locale for the calling thread.	Either of the following: System.Globalization.CultureInfo.CurrentCulture System.Threading.Thread.CurrentCulture The most important change that occurs when the thread locale is changed is the resource language in the thread, meaning System.Threading.Thread.CurrentUICulture may be more accurate here.
GetUserGeoID	Gets information about the user's location.	System.Globalization.RegionInfo GeoID is not supported in .NET 1.1, but 2.0 will support a RegionInfo.GeoId property.
IsValidCodePage	Determines whether a specified code page is valid.	Use an array of CultureInfo objects returned by: System.Globalization.CultureInfo.GetCultures(System.Globalization.CultureTypes.AllCultures) Compare to the code page properties of System.Globalization.CultureInfo.TextInfo Yikes! This is time consuming and will not detect all valid code pages, and will claim some are valid that may not be supported. How about calling Encoding.GetEncoding() with a CodePage identifier and trapping both ArgumentException and NotSupportedException, instead?
LCMapString	Maps one character string to another, performing a specified locale-dependent transformation.	System.Globalization.SortKey This is only one of the many possible uses of LCMapString, which also supports uppercase/lowercase, Hiragana/Katakana, fullwidth/halfwidth, traditional/simplified mappings. Of these, only the case mappings are supported in .NET.
SetThreadLocale	Sets the current locale for the calling thread.	System.Threading.Thread.CurrentCulture Note   Sets langid only. The most important change that occurs when the thread locale is changed is the resource language in the thread, meaning System.Threading.Thread.CurrentUICulture may be more accurate here.

This post brought to you by "E" (U+0045, a.k.a. LATIN CAPITAL LETTER E)

# AC on 27 Feb 2005 5:51 AM:

# Michael Kaplan on 27 Feb 2005 4:06 PM:

referenced by

go to newer or older post, or back to index or month or day