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.

Microsoft Windows MBCS	FormatMessageA
Microsoft Windows Unicode	FormatMessageW
Microsoft Windows Generic	FormatMessage