by Michael S. Kaplan, published on 2008/03/22 10:01 -04:00, original URI: http://blogs.msdn.com/b/michkap/archive/2008/03/22/8330506.aspx
Content of Michael Kaplan's personal blog not approved by Microsoft (see disclaimer)!
I always want to think the best a function.
Kind of like how I always want to think the best of people.
Especially if I know that it is a part of an API set that I fond of.
Kind of like how if a person is a family member or good friend of one of my friends.
I might not even mind that it does not behave as documented each time.
Kind of like if a person does stuff like get drunk and say act embarrassing or whatever.
But eventually I flip the bozo bit and decide a function is just a useless piece of crap with no redeeming value and that using it is a total waste of time until and unless it is completely rewritten from the ground up.
Kind of like if a person becomes an alcoholic and starts breaking into your house to steal stuff to sell for liquor and you kick them out and refuse to let them back into your life unless they go to rehab.
Holy taking an analogy too far, Batman!
But you might know what I mean here.
An example of such a function, for me, is GetGeoInfo.
Now I have been something of an enabler for this function, what with my blogging about it over the years in What the hell is up with Timor-Leste? and What the hell is up with Timor-Leste? [Microsoft edition] and It's not quite done yet and Some of GetGeoInfo is sorta broken.
But that last one was an understatement.
Basically, GEO_TIMEZONES? It isn't implemented.
GEO_OFFICIALLANGUAGES? Also not implemented.
At least we got them up update the MSDN topic about them.
Anyway, the other day was the last straw.
Because the GEO_RFC1766, documented as:
GEO_RFC1766 The name for a string, compliant with RFC 4646 (Windows Vista and later), that is derived from the GetGeoInfo parameters language and GeoId.
then to find out what they mean by language, documented as:
LangId [in] Identifier for the language, used with the value of Location. The application can set this parameter to 0, with GEO_RFC1766 or GEO_LCID specified for GeoType. This setting causes the function to retrieve the language identifier by calling GetUserDefaultLangID.
Note: The application must set this parameter to 0 if GeoType has any value other than GEO_RFC1766 or GEO_LCID.
...
If the application specifies GEO_RFC1766 for GeoType, it should specify a language identifier for LangId that is appropriate to the specified geographical location identifier. The appropriate language is either a locale-neutral language or one with a locale corresponding to the specified identifier. The resulting string, compliant with RFC 4646 (Windows Vista and later), constitutes a locale name.
For example, if Location is specified as 0xF4 for United States, GeoType is specified as GEO_RFC1766, and LangId is specified as either 0x09 for locale-neutral English or 0x409 for English (United States), the function retrieves "en-US" on successful return. In fact, the function ignores the locale-specific portion of the language. Thus, if the application specifies LangId as 0x809 for English (United Kingdom), the function also writes "en-US" to lpGeoData.
Consider another example. If Location is specified as 0xF4 for United States, GeoType is specified as GEO_RFC1766, and LangId is specified as 0x04 for Chinese, the function retrieves "zh-US" on successful return. This is not the name of a supported locale.
This function just blithely admitted to useless, purposeless functionality that unless you carefully call with exact parameters that define the exact language you want will return meaningless results not reasonable to use elsewhere.
And a parameter named LangId that only works with the PRIMARYLANGID portion of the value, even if a full LangId would be needed to intelligently guess (which the function is okay with since ut ahs no plans to intelligently guess).
And bad enough that it names itself after RFC 1766 even though that is two versions of the standard behind. It is fully optimized for creating tags that no reasonable person would ever want to have in any version of the RFC.
And then there is the GEO_LCID, documented as:
GEO_LCID A locale identifier derived from the GetGeoInfo parameters language and GeoId.
then to find out what they mean by language, documented as:
If the application specifies GEO_LCID for GeoType, the function treats the language identifier as a locale identifier (LCID). It attempts to return the locale identifier if it is associated with the provided geographical identifier in some way.
This one also strips off the region info from the LCID you pass in and then tries to create another one if it can -- which it likely won't be able to do anyway.
In other words, if you know the values are completely reasonable and compatible then the function will be helpful, otherwise not so much.
But if you knew the exact values to pass then you wouldn't even need it!
Well, I'm done trying make excuses for this worthless function that spends so much of its time being useless. I could do a better job throwing a dart at a map (something I did once when I decided to take a year off from school, and ended up staying there half a decade. People at the time accused me of acting quite randomly, but I was a lot more freaking deterministic than "Mr. zh-US GetGeoInfo" over here.
I'm locking it out of my house until someone sends it to rehabrewrite.
Any NLS devs nearby want to make a function useful for some future version? Or at least fix up the docs to describe just how useless some of these enumeration values are without requiring full understanding of the functionality on the part of the users? :-)
Because until then, GetGeoInfo is a mostly useless bloody waste of a function....
This blog brought to you by G (U+0047, aka LATIN CAPITAL LETTER G)