| DWORD FormatMessage(dwFlags, lpSource, dwMessageId, dwLanguageId, lpBuffer, nSize, lpArguments) | |||||
| DWORD dwFlags; | /* specifies source and processing options | */ | |||
| LPVOID lpSource; | /* specifies message source | */ | |||
| DWORD dwMessageId; | /* requested message ID | */ | |||
| DWORD dwLanguageId; | /* language ID for requested message | */ | |||
| LPSTR lpBuffer; | /* address of message buffer | */ | |||
| DWORD nSize; | /* maximum size of the message buffer | */ | |||
| LPVOID lpArguments; | /* address of array of message inserts | */ | |||
The FormatMessage function formats a message string. The function takes a message definition from a buffer, from a message-table resource, or from the system's message-table resources(s), processes any embedded insert sequences in the message, and copies the resulting message to an output buffer.
dwFlags
Specifies formatting options and contents of the lpSource parameter. This parameter can be some combination of the following values:
| Value | Meaning |
| FORMAT_MESSAGE_ALLOCATE_BUFFER | ||
| Specifies that lpBuffer is the address of a VOID pointer and nSize specifies the minimum number of bytes to allocate for the formatted message. This function will allocate a buffer large enough to hold the formatted message and place a pointer to the buffer at lpBuffer. The caller should use the LocalFree function to free this pointer when it is no longer needed. | ||
| FORMAT_MESSAGE_IGNORE_INSERTS | ||
| Specifies that insert sequences in the message definition should be ignored and passed through to the output buffer as is. This flag can be used to fetch a message for later formatting. If this flag is set, the lpArguments parameter is ignored. | ||
| FORMAT_MESSAGE_FROM_STRING | Specifies that lpSource is a pointer to a null-terminated message definition that may contain insert sequences. | |
| FORMAT_MESSAGE_FROM_HMODULE | ||
| Specifies that lpSource is a module handle that contains the message table resource(s) to search. If this handle is NULL, then the current application's image file will be searched. | ||
| FORMAT_MESSAGE_FROM_SYSTEM | Specifies that the function should search the system message table resource(s) for the requested message. This flag should only be used if dwFlags does not include FORMAT_MESSAGE_FROM_STRING or FORMAT_MESSAGE_FROM_HMODULE . | |
The low-order eight bits of dwFlags specify the maximum width, in characters, of each line formatted into the output buffer. If the maximum width is not zero, FormatMessage calculates line breaks based on the maximum width, ignoring line breaks in the message definition. White-space delimited strings are never split across a line break.
If the maximum width is zero, only the line breaks in the message definition are placed in the output buffer.
lpSource
Specifies the location of the message string. This parameter is either a pointer to a null-terminated string or a module handle, depending on the settings in the dwFlags parameter.
This parameter is ignored if dwFlags does not include either FORMAT_MESSAGE_FROM_STRING or FORMAT_MESSAGE_FROM_HMODULE .
dwMessageId
Specifies the message identifier for the requested message. This parameter is ignored if dwFlags includes FORMAT_MESSAGE_FROM_STRING .
dwLanguageId
Specifies language identifier for the requested message. This parameter is ignored if dwFlags includes FORMAT_MESSAGE_FROM_STRING .
lpBuffer
Points to a buffer for the formatted (and null-terminated) message. If dwFlags includes FORMAT_MESSAGE_ALLOCATE_BUFFER, the function allocates a buffer and places the address of the buffer at lpBuffer.
nSize
Specifies the maximum number of bytes that can be stored in the output buffer.
lpArguments
Points to an array of 32-bit values that are used as insert values in the formatted message. How each value is interpreted 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.
If the function is successful, the return value is the number of bytes actually stored in the output buffer, excluding the terminating null character. Otherwise, the return value is zero. Use the GetLastError function to obtain extended error information.
An application can use the FORMAT_MESSAGE_MAX_WIDTH_MASK constant to mask the low eight bits of dwFlags to retrieve the maximum line length.
Within the message text, several escape sequences are supported for dynamically formatting the message. All escape sequences start with the percent sign character (%).
| Escape | Meaning |
| %0 | Terminates a message text line without a trailing newline. This can be used to build up long lines or to terminate the message itself without a trailing newline, which is useful for prompt messages. |
| %n!printf format string! | Identifies an insert. The value of n can be between 1 and 99. The printf format string (which must 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 width components. If * is specified, the FormatMessage function uses insert %n+1 (and %n+2 if * is specified for both precision and width). |
Inserts must reference a parameter passed to the FormatMessage function.
Any other non-digit character following a percent sign will be formatted in the output message without the percent sign. Some examples:
| Format String | Meaning |
| %% | Produces a single percent sign in the formatted message text. |
| %\ | Produces a hard line break when it occurs at the end of a a line. Useful when FormatMessage is supplying normal line breaks so the message fits in a certain width. |
| %space | Produces a space in the formatted message text. This can be used to insure there are the appropriate number of trailing spaces in a message text line. |
| %. | Produces a single period in the formatted message text. This can be used to get a single period at the beginning of a line without terminating the message text definition. |
| %! | Produces a single exclamation point in the formatted message text. This can be used to get an exclamation point immediately after an insert without it being mistaken for the beginning of a printf format string. |
LoadString