Locale-Sensitive Windows C++ Function
BOOL GetStringTypeEx(LCID Locale, DWORD dwInfoType, LPCTSTR lpSrcStr, int cchSrc, LPWORD lpCharType);
BOOL GetStringTypeExA(LCID Locale, DWORD dwInfoType, LPCSTR lpSrcStr, int cchSrc, LPWORD lpCharType);
BOOL GetStringTypeExW(LCID Locale, DWORD dwInfoType, LPCWSTR lpSrcStr, int cchSrc, LPWORD lpCharType);
Internationalization (I18n) Function Overview
The GetStringTypeEx function determines character type information (alphabetic, numeric, control,
etc), bi-directional layout information, and text processing information
of the string argument lpSrcStr, and stores the result in the array pointed to by lpCharType.
If successful, GetStringTypeEx returns a non-zero value; otherwise, it returns 0 and
sets extended error information that can be obtained by calling GetLastError.
In the narrow version of this function (GetStringTypeExA), Locale
defines the ANSI code page to use to translate the string pointed to by lpSrcStr from single or multibyte-characters to Unicode UTF-16 characters
prior to the analysis of each Unicode character for character type information.
Note that the GetStringTypeExW ignores this parameter.
The dwInfoType flag specifies the type of character information to retrieve, and can be one of the following values:
CT_CTYPE1 to retrieve character type information.
CT_CTYPE2 to retrieve bi-directional layout information.
CT_CTYPE3 to retrieve text processing information.
cchSrc specifies the size, in TCHARs, of the string
pointed to by the lpSrcStr argument. If this count includes the null-terminating character,
then GetStringTypeEx returns character type information for the NULL character.
If cchSrc is a negative number, the string is assumed to be null-terminated and the length
is calculated automatically and includes the NULL character. In other words,
the calculated length is _tcslen(lpSrcStr) + 1.
The output array lpCharType must point to 16-bit values and be large enough to
hold a value for each lpSrcStr character. To ensure this, set the number of elements to
cchSrc, if cchSrc is a positive value, and to
_tcslen(lpSrcStr) + 1, if cchSrc is a
negative value.
GetStringTypeExA is the narrow version of the function, passing in a single or multibyte string and a length value in bytes.
GetStringTypeExW is the wide version of the function, passing in a wide-character string and a length value in wide characters (WCHARs).
See the MSDN Library for
additional information.
I18n Issues
Use the appropriate version of the function as required for internationalization support, noting the following:
GetStringTypeEx does accommodate the #define UNICODE switch, mapping
to the corresponding narrow or wide version of the function, and should be used in place of
GetStringTypeA or
GetStringTypeW.
Formulate the correct LCID to pass into GetStringTypeA.
Although there are two predefined LCID constants that may be used:
LOCALE_SYSTEM_DEFAULT
(the system's default locale returned by GetSystemDefaultLCID)
and LOCALE_USER_DEFAULT (the current user's default locale returned by
GetUserDefaultLCID),
neither of these will work in an internationalized application where the locale is independent of
the user's system settings.
Ensure that if cchSrc is a positive value, it is set correctly for the chosen platform;
bytes for the narrow version and WCHARs for the wide version. See Locale-Sensitive Length Functions
for a discussion on multibyte and wide character sizes.
Recommended Replacements*
When possible, use the Generic version of the function, rather than the narrow or wide versions, and let the Windows #define UNICODE compiler switch determine which version of the function will be called.
*If you're already using the recommended function, see I18n Issues for other reasons why Globalyzer is detecting the function.
|
