Flag behavior for the NLS APIs

by Michael S. Kaplan, published on 2005/03/29 02:18 -05:00, original URI: http://blogs.msdn.com/b/michkap/archive/2005/03/29/403216.aspx

Flags for APIs are an interesting thing, especially when you have APIs that you improve between versions. And the NLS APIs are no exception to this.

There are two ways one could handle flag values that are undefined in the current version of an API:

1. You can disallow any unknown flag value.
   • PRO -- you never have to worry about a future version "changing" behavior
   • CON -- callers have to write version dependent code if they want to call multiple versions
2. You can allow but ignore any unknown flag value.
   • PRO -- Only one call semantic is needed across all versions
   • CON -- You never know when flags are used and when they are ignored

Just in case people were not sure, by and large the NLS API use #1, something that I think most APIs do. While the ability to call the code just one way is nice, never being sure what the behavior is really not so nice. And when you look at APIs from the point of view of not knowing what will come next, you never want to add that kind of uncertainty to the mix for the future.

(Note that the one glaring exception to this is the LOCALE_NOUSEROVERRIDE flag, which actually gets pretty controversial when you get down to it (cf: When is it a backcompat break and when is it fulfilling not-yet-fulfilled technology?)

It was interesting working on the Microsoft Layer for Unicode, which tries to let people write Unicode applications. What to do with the flags that are NT-specific becomes an even more interesting set of debates with people who start each meeting claiming they have no strong feelings about the issue and end each meeting ready to kill the ignorant wingnuts who want Microsoft to go down in flames via their own bad decisions. Hopefully you'll see the counterpoint there....

On the whole I am happy with the behavior of the rest of the APIs (and with most of the behavior of GetLocaleInfo, et. al., ignoring the LOCALE_NOUSEROVERRIDE stuff). And that is speaking as a former external developer who had to write all of that version-specific code. Because I would rather see the API fail up front than appear to succeed while actually ignoring what I told it to do. An API that accepts but ignores random crap (and if you think about, all it is random crap when it is not yet defined) is not a very robust API....

Though I must admit as that same former external developer who had to write code against up to ten versions of Windows that the flags only working in some version and not others can be quite a pain to keep straight.

A smattering of flags that were added later:

• MB_ERR_INVALID_CHARS -- Used with MultiByteToWideChar. Illegal to use in UTF-8 until Windows XP, at which point it became supported.
• WC_NO_BEST_FIT_CHARS -- Used with WideCharToMultiByte. Valid on all platforms other than Windows 95, 95 OSR-2, NT 3.1 and NT 3.51.
• LOCALE_FONTSIGNATURE -- Used with GetLocaleInfo. Valid on all platforms other NT 3.1 and NT 3.51.
• LOCALE_IDEFAULTEBCDICCODEPAGE -- Used with GetLocaleInfo. Valid on XP, Server 2003, and later.
• LOCALE_IDIGITSUBSTITUTION -- Used with GetLocaleInfo. Valid on XP, Server 2003, and later.
• LOCALE_IPAPERSIZE -- Used with GetLocaleInfo. Valid on XP, Server 2003, and later.
• LOCALE_RETURN_NUMBER -- Used with GetLocaleInfo. Valid on all platforms other than Windows 95, 95 OSR-2, NT 3.1 and NT 3.51.
• LOCALE_SENGCURRNAME -- Used with GetLocaleInfo. Valid on all platforms other than Windows 95, 95 OSR-2, NT 3.1 and NT 3.51.
• LOCALE_SISO3166CTRYNAME -- Used with GetLocaleInfo. Valid on all platforms other than Windows 95, 95 OSR-2, NT 3.1 and NT 3.51.
• LOCALE_SISO639LANGNAME -- Used with GetLocaleInfo. Valid on all platforms other than Windows 95, 95 OSR-2, NT 3.1 and NT 3.51.
• LOCALE_SNATIVECURRNAME -- Used with GetLocaleInfo. Valid on all platforms other than Windows 95, 95 OSR-2, NT 3.1 and NT 3.51.
• LOCALE_SSORTNAME -- Used with GetLocaleInfo. Valid on all platforms other than Windows 95, 95 OSR-2, NT 3.1 and NT 3.51.
• LOCALE_SYEARMONTH -- Used with GetLocaleInfo. Valid on all platforms other than Windows 95, 95 OSR-2, NT 3.1 and NT 3.51.
• LCID_ALTERNATE_SORTS -- Used with EnumSystemLocales. Valid on all platforms other than Windows 95, 95 OSR-2, NT 3.1 NT 3.51, and NT 4.0.

And so on. All flags added for new functionality that on prior versions would cause the API to fail with an ERROR_INVALID_FLAGS return from GetLastError()...

This post brought to you by "ᾮ" (U+1fae, GREEK CAPITAL LETTER OMEGA WITH PSILI AND PERISPOMENI AND PROSGEGRAMMENI)

# AC on 29 Mar 2005 11:42 AM:

# Michael Kaplan on 29 Mar 2005 12:06 PM:

# Dean Harding on 29 Mar 2005 3:45 PM:

Bartosz Wójcik on 5 Jan 2010 10:51 AM:

Michael S. Kaplan on 5 Jan 2010 11:07 AM:

Bartosz Wójcik on 5 Jan 2010 2:05 PM:

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