by Michael S. Kaplan, published on 2008/08/11 03:01 -04:00, original URI: http://blogs.msdn.com/b/michkap/archive/2008/08/11/8847467.aspx
The question in the email was:
Hi,
I am trying to debug an issue... and was wondering if you could explain or elaborate on the behavior I am seeing from
GetLcidFromRfc1766() with the string “ja-JP”
it is returning S_false, indicating that only the primary langauge tag was matched. The lcid that is returned is 1041. However, According to the windows language code identifier reference this lcid corresponds to ja-jp which has both a primary and a subtag. Is it just a coincidence that the correct lcid is being returned?
Ah, where to begin? :-)
I suppose we can start with GetLcidFromRfc1766 and its unusual return value semantic:
Returns one of the following values.
S_OK Success. S_FALSE The returned LCID matches only the primary language of the RFC1766-conforming name. E_FAIL The method cannot get the information from the database or the system. E_INVALIDARG One or more of the arguments are invalid.
I think I have made my feelings about "creative" uses of return values clear in blogs like API Consistency and Developer Comfort and When the documentation is confusing, it is often because the functionality is, too (especially the latter one which talks about the creative return value semantic of NormalizeString).
Now of course in addition to overloading an HRESULT such that both S_OK and S_FALSE are both meaningful, we have an additional problem, this one in the documentation.
After all, doesn't the text about "only the primary language of the RFC1766-conforming name" kind of imply it is talking about PRIMARYLANGID stuff?
This is what the person asking the original question was kind of thinking it meant. He was thinking that the S_FALSE implied a return of something like 0x11 (LANG_JAPANESE) when one passes "ja".
Which is why ja-jp getting S_FALSE does seem a little off!
Now this is an entirely reasonable assumption one could make given the normal and reasonable expectation of consistent terminology in documentation.
However, that is not what it means here.
If you saw The weird, weird world of the SUBLANGID from way back when, you'll have the hint -- the documentation is thinking of a LANGID/LCID value constructable with SUBLANG_DEFAULT as being the "primary" language tag.
Though if you read The weird, weird world of the SUBLANGIDyou'll see whay that is a bad idea. I mean, given the lengths the definitions try to go to make the claim that when there are multiple SUBLANGID values defined for a given PRIMARYLANGID that the first one is arbitrary and is no more privileged than later ones. You know, that Microsoft is making no claim of
MAKELANGID(LANG_PORTUGUESE, SUBLANG_PORTUGUESE_BRAZILIAN)
being more special or more important than
MAKELANGID(LANG_PORTUGUESE, SUBLANG_PORTUGUESE)
just because it is the first one.
Though if you think about it, as bad a the documentation is here, they are just documenting the [flawed] functionality.
So it is still mostly not the fault of the documentation. :-)
This blog brought to you by ၌ (U+104c, aka MYANMAR SYMBOL LOCATIVE)