Locale-Sensitive Windows C++ Function
DWORD FormatMessage(DWORD dwFlags, LPCVOID lpSource, DWORD dwMessageId, DWORD dwLanguageId, LPTSTR lpBuffer, DWORD nSize, va_list* Arguments);
DWORD FormatMessageA(DWORD dwFlags, LPCVOID lpSource, DWORD dwMessageId, DWORD dwLanguageId, LPSTR lpBuffer, DWORD nSize, va_list* Arguments);
DWORD FormatMessageW(DWORD dwFlags, LPCVOID lpSource, DWORD dwMessageId, DWORD dwLanguageId, LPWSTR lpBuffer, DWORD nSize, va_list* Arguments);
Internationalization (I18n) Function Overview
The FormatMessage function retrieves the message string specified by the lpSource argument, formats it using the Arguments data, and writes the formatted
output to lpBuffer . It returns the number of TCHARs if successful; else it returns 0 and
sets extended error information that can be obtained by calling GetLastError .
The dwFlags argument can specify formatting options and indicate how to interpret the lpSource argument.
lpSource can be a string, or the handle to an already-loaded resource module.
dwFlags can also indicate that FormatMessage should search the system's message
table resource(s) for the message string. In the case where a resource table is accessed, the
message identifier dwMessageId and the language identifier dwLanguageId are
used to identify the desired message string.
dwMessageId is the message identifier for the requested message, and is ignored
if dwFlags includes FORMAT_MESSAGE_FROM_STRING .
dwLanguageId is the language identifier for the requested message,
and is ignored if dwFlags includes FORMAT_MESSAGE_FROM_STRING .
nSize is the size in TCHARs of lpBuffer if
dwFlags does not include FORMAT_MESSAGE_ALLOCATE_BUFFER ; otherwise
this argument specifies the minimum number of TCHARs to allocate for the output buffer.
Arguments is a pointer to an array of values that are used as insert values in the formatted message.
A %1 in the message string indicates the first value in the Arguments array; a %2 indicates the second argument; etc.
FormatMessageA is the narrow version of the function, passing in single or multibyte strings and length values in bytes.
FormatMessageW is the wide version of the function, passing in wide-character strings and the length values in wide characters (WCHARs ).
See the MSDN library for more information on
the dwFlags settings and the formatting options supported by the message string.
I18n Issues
Use the appropriate version of the function as required for internationalization support, noting the following:
In an internationalized application, FormatMessage should be used in place of string concatenations, since
the data insertion points can vary according to locale and
strings can be retrieved from resource modules.
Where locale-dependent numeric formatting is required, use the locale-sensitive
GetNumberFormat function to first
format numbers and then insert them as strings, rather than using the %d or %i
format options, which are locale-independent.
If used, formulate the correct dwLanguageId to pass into FormatMessage .
Although there are two predefined dwLanguageId constants that may be used:
LANG_SYSTEM_DEFAULT
(the system's default language returned by GetSystemDefaultLangID )
and LANG_USER_DEFAULT (the current user's default language returned by
GetUserDefaultLangID ),
neither of these will work in an internationalized application where the language is independent of
the user's system settings.
Ensure that if nSize is used, it is correct 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 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.
|