FormatMessage
The FormatMessage
function formats a message string. The function requires a message definition
as input. The message definition can come from a buffer passed into the
function. It can come from a message table resource in an already-loaded
module. Or the caller can ask the function to search the system s message table
resource(s) for the message definition. The function finds the message
definition in a message table resource based on a message identifier and a
language identifier. The function copies the formatted message text to an
output buffer, processing any embedded insert sequences if requested.
DWORD FormatMessage(
|
DWORD dwFlags, |
// source and
processing options |
|
LPCVOID lpSource, |
// pointer to message source |
|
DWORD dwMessageId, |
// requested
message identifier |
|
DWORD dwLanguageId, |
// language
identifier for requested message |
|
LPTSTR lpBuffer, |
// pointer to
message buffer |
|
DWORD nSize, |
// maximum size of
message buffer |
|
va_list *Arguments |
// address of array
of message inserts |
|
); |
|
Parameters
dwFlags
Contains a
set of bit flags that specify aspects of the formatting process and how to
interpret the lpSource parameter. The low-order byte of dwFlags
specifies how the function handles line breaks in the output buffer. The
low-order byte can also specify the maximum width of a formatted output line.
You can
specify a combination of the following bit flags:
|
Value |
Meaning |
|
FORMAT_MESSAGE_ALLOCATE_BUFFER |
|
|
|
Specifies
that the lpBuffer parameter is a pointer to a PVOID pointer,
and that the nSize parameter specifies the minimum number of bytes
(ANSI version) or characters (Unicode version) to allocate for an output
message buffer. The function allocates a buffer large enough to hold the
formatted message, and places a pointer to the allocated buffer at the
address specified by lpBuffer. The caller should use the LocalFree function to free the
buffer when it is no longer needed. |
|
FORMAT_MESSAGE_IGNORE_INSERTS |
|
|
|
Specifies
that insert sequences in the message definition are to be ignored and passed
through to the output buffer unchanged. This flag is useful for fetching a
message for later formatting. If this flag is set, the Arguments
parameter is ignored. |
|
FORMAT_MESSAGE_FROM_STRING |
|
|
|
Specifies
that lpSource is a pointer to a null-terminated message definition.
The message definition may contain insert sequences, just as the message text
in a message table resource may. Cannot be used with FORMAT_MESSAGE_FROM_HMODULE
or FORMAT_MESSAGE_FROM_SYSTEM. |
|
FORMAT_MESSAGE_FROM_HMODULE |
|
|
|
Specifies
that lpSource is a module handle containing the message-table
resource(s) to search. If this lpSource handle is NULL, the current
process s application image file will be searched. Cannot be used with
FORMAT_MESSAGE_FROM_STRING. |
|
FORMAT_MESSAGE_FROM_SYSTEM |
|
|
|
Specifies
that the function should search the system message-table resource(s) for the
requested message. If this flag is specified with
FORMAT_MESSAGE_FROM_HMODULE, the function searches the system message table
if the message is not found in the module specified by lpSource.
Cannot be used with FORMAT_MESSAGE_FROM_STRING. If this
flag is specified, an application can pass the result of the GetLastError function to
retrieve the message text for a system-defined error. |
|
FORMAT_MESSAGE_ARGUMENT_ARRAY |
|
|
|
Specifies
that the Arguments parameter is not a va_list structure,
but instead is just a pointer to an array of 32-bit values that represent the
arguments. |
The low-order
byte of dwFlags can specify the maximum width of a formatted output
line. Use the FORMAT_MESSAGE_MAX_WIDTH_MASK constant and bitwise Boolean operations
to set and retrieve this maximum width value.
The following
table shows how FormatMessage interprets the value of the low-order
byte.
|
Value |
Meaning |
|
0 |
There are
no output line width restrictions. The function stores line breaks that are
in the message definition text into the output buffer. |
|
A nonzero
value other than FORMAT_MESSAGE_MAX_WIDTH_MASK |
The nonzero
value is the maximum number of characters in an output line. The function
ignores regular line breaks in the message definition text. The function
never splits a string delimited by white space across a line break. The
function stores hard-coded line breaks in the message definition text into
the output buffer. Hard-coded line breaks are coded with the %n escape
sequence. |
|
FORMAT_MESSAGE_MAX_WIDTH_MASK |
The
function ignores regular line breaks in the message definition text. The
function stores hard-coded line breaks in the message definition text into
the output buffer. The function generates no new line breaks. |
lpSource
Specifies the
location of the message definition. The type of this parameter depends upon the
settings in the dwFlags parameter.
|
dwFlags Setting |
Parameter
Type |
|
FORMAT_MESSAGE_FROM_HMODULE |
lpSource is an hModule of the module that contains the
message table to search. |
|
FORMAT_MESSAGE_FROM_STRING |
lpSource is an LPTSTR that points to unformatted
message text. It will be scanned for inserts and formatted accordingly. |
If neither of
these flags is set in dwFlags, then lpSource is ignored.
dwMessageId
Specifies the
32-bit message identifier for the requested message. This parameter is ignored
if dwFlags includes FORMAT_MESSAGE_FROM_STRING.
dwLanguageId
Specifies the
32-bit language identifier for the requested message. This parameter is ignored
if dwFlags includes FORMAT_MESSAGE_FROM_STRING.
If you pass a
specific LANGID in this parameter, FormatMessage will return a message
for that LANGID only. If the function cannot find a message for that LANGID, it
returns ERROR_RESOURCE_LANG_NOT_FOUND. If you pass in zero, FormatMessage
looks for a message for LANGIDs in the following order:
1. Language neutral
2. Thread LANGID, based on the thread's locale value
3. User default LANGID, based on the user's default locale value
4. System default LANGID, based on the system default locale value
5. US English
If FormatMessage
doesn't find a message for any of the above LANGIDs, it returns any language
message string that is present. If even that fails, it returns
ERROR_RESOURCE_LANG_NOT_FOUND.
lpBuffer
Points to a
buffer for the formatted (and null-terminated) message. If dwFlags
includes FORMAT_MESSAGE_ALLOCATE_BUFFER, the function allocates a buffer using
the LocalAlloc
function, and places the address of the buffer at the address specified in lpBuffer.
nSize
If the
FORMAT_MESSAGE_ALLOCATE_BUFFER flag is not set, this parameter specifies the
maximum number of bytes (ANSI version) or characters (Unicode version) that can
be stored in the output buffer. If FORMAT_MESSAGE_ALLOCATE_BUFFER is set, this
parameter specifies the minimum number of bytes or characters to allocate for
an output buffer.
Arguments
Points to an
array of 32-bit values that are used as insert values in the formatted message.
%1 in the format string indicates the first value in the Arguments array;
%2 indicates the second argument; and so on.
The
interpretation of each 32-bit value depends on the formatting information
associated with the insert in the message definition. The default is to treat
each value as a pointer to a null-terminated string.
By default,
the Arguments parameter is of type va_list*, which is a language-
and implementation-specific data type for describing a variable number of
arguments. If you do not have a pointer of type va_list*, then specify
the FORMAT_MESSAGE_ARGUMENT_ARRAY flag and pass a pointer to an array of 32-bit
values; those values are input to the message formatted as the insert values.
Each insert must have a corresponding element in the array.
Return Values
If the
function succeeds, the return value is the number of bytes (ANSI version) or
characters (Unicode version) stored in the output buffer, excluding the
terminating null character.
If the
function fails, the return value is zero. To get extended error information,
call GetLastError.
Remarks
The FormatMessage
function can be used to obtain error message strings for the system error codes
returned by GetLastError, as shown in the following sample code.
LPVOID lpMsgBuf;
FormatMessage(
FORMAT_MESSAGE_ALLOCATE_BUFFER
| FORMAT_MESSAGE_FROM_SYSTEM,
NULL,
GetLastError(),
MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), // Default language
(LPTSTR)
&lpMsgBuf,
0,
NULL
);
// Display the string.
MessageBox( NULL, lpMsgBuf, "GetLastError",
MB_OK|MB_ICONINFORMATION );
// Free the buffer.
LocalFree( lpMsgBuf );
Within the
message text, several escape sequences are supported for dynamically formatting
the message. These escape sequences and their meanings are shown in the
following table. All escape sequences start with the percent character (%).
|
Escape
Sequence |
Meaning |
|
%0 |
Terminates
a message text line without a trailing newline character. This escape
sequence can be used to build up long lines or to terminate the message
itself without a trailing newline character. It is useful for prompt
messages. |
|
%n!printf format string! |
Identifies
an insert. The value of n can be in the range 1 through 99. The printf
format string (which must be bracketed by exclamation marks) is optional and
defaults to !s! if not specified. |
|
|
The printf
format string can contain the * specifier for either the precision or the
width component. If * is specified for one component, the FormatMessage
function uses insert %n+1; it uses %n+2 if * is specified for
both components. |
|
|
Floating-point
printf format specifiers e, E, f, and
g are not
supported. The workaround is to to use the sprintf function to format
the floating-point number into a temporary buffer, then use that buffer as
the insert string. |
Any other
nondigit character following a percent character is formatted in the output
message without the percent character. Following are some examples:
|
Format
string |
Resulting
output |
|
%% |
A single
percent sign in the formatted message text. |
|
%n |
A hard line
break when the format string occurs at the end of a line. This format string
is useful when FormatMessage is supplying regular line breaks so the
message fits in a certain width. |
|
%space |
A space in
the formatted message text. This format string can be used to ensure the
appropriate number of trailing spaces in a message text line. |
|
%. |
A single
period in the formatted message text. This format string can be used to
include a single period at the beginning of a line without terminating the
message text definition. |
|
%! |
A single
exclamation point in the formatted message text. This format string can be
used to include an exclamation point immediately after an insert without its
being mistaken for the beginning of a printf format string. |
See Also