Parameter confusion #2

by Michael S. Kaplan, published on 2005/10/21 14:10 -04:00, original URI: http://blogs.msdn.com/b/michkap/archive/2005/10/21/483526.aspx

It seems like it was just ages ago that I talked about Parameter Confusion in regard to the LCMapString function when used for sort keys.

Oh wait, it was just yesterday. :-)

There is another direction in which the confusion can exist, though -- this time not with the difference but with the consistency.

Let's take a look at the GetLocaleInfo function. its prototype is simple enough:

int GetLocaleInfo(
  LCID Locale,      // locale identifier
  LCTYPE LCType,    // information type
  LPTSTR lpLCData,  // information buffer
  int cchData       // size of buffer
);

Simple enough, right? That cchData has a simple set of rules that it goes by:

cchData

[in] Specifies the size, in TCHARs, of the lpLCData buffer. If cchData is zero, the function returns the number of TCHARs required to hold the information, including the terminating null character, and the buffer pointed to by lpLCData is not used.

Well, not completely simple, but close enough. Since you are passing a string, it is just saying to use the count of characters and not the count of bytes.

Of course, when you include the LOCALE_RETURN_NUMBER flag in with your LCType, is when things get a bit more complicated:

LOCALE_RETURN_NUMBER

Windows 98/Me, Windows NT 4.0 and later: This causes the function to return the value as a number instead of as a string. The buffer that receives the value must be at least the length of a DWORD. This flag can be combined with any specifier beginning with LOCALE_I by using the binary-OR operator.

Yikes, now that certainly does put a cat among the pigeons. What should the value in cchData be now, with this buffer that must be the length of a DWORD?

The answer is deceptively simple -- it should be the same value -- the size in TCHARs. The easiest way to do this is to generically pass sizeof(DWORD) / sizeof(TCHAR) any time you are using the LOCALE_RETURN_NUMBER flag on any of the LOCALE_I* LCType values.

You can be a little fancier in cases where the number is typed as something different -- like with LOCALE_ICALENDARTYPE (which returns a CALID). But then if you look at the definition of CALID in winnls.h you will see why I am not too concerned about the need pass sizeof(CALID) / sizeof(TCHAR) for that case:

//
//  Calendar ID.
//
typedef DWORD CALID;

Ok, perhaps this ends up being kind of simple, after this part about LOCALE_RETURN_NUMBER is explained. Lots of people still find it to be kind of confusing....

This post brought to you by "ޝ" (U+079d, a.k.a. THAANA LETTER SHEENU)

# Gabe on 22 Oct 2005 3:27 AM:

# Michael S. Kaplan on 22 Oct 2005 1:39 PM:

# Gabe on 26 Oct 2005 6:01 PM:

# Michael S. Kaplan on 26 Oct 2005 6:07 PM:

referenced by

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