Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This method formats a message string.

Syntax 

STDMETHOD(FormatMessage)(
  THIS_ DWORD 
dwFlags,
  DWORD 
dwMessageId,
  DWORD 
dwLanguageId,
  LPTSTR 
lpBuffer,
  DWORD 
nSize,
  va_list* 
Arguments,
  DWORD* 
pcb
) PURE;

Parameters

dwFlags

[in] Any combination of the following bit flags to specify the formatting process and how to interpret the lpSourceparameter.

The low-order byte of dwFlagsspecifies how FormatMessagehandles line breaks in the output buffer. The low-order byte can also specify the maximum width of a formatted output line.

Value Description

FORMAT_MESSAGE_ALLOCATE_BUFFER

Specifies lpBufferis a pointer to a PVOID pointer, and the nSizeparameter specifies the minimum number of bytes (ANSI) or characters (Unicode) to allocate for an output message buffer. FormatMessageallocates 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 LocalFreefunction to free the buffer when it is no longer needed.

FORMAT_MESSAGE_IGNORE_INSERTS

Specifies insert sequences in the message definition are to be ignored and passed through to the output buffer unchanged. Useful for retrieving a message for later formatting. If this flag is set, the Argumentsparameter is ignored.

FORMAT_MESSAGE_FROM_STRING

Specifies lpSourceis a pointer to a null-terminated message definition. The message definition can contain insert sequences, just as the message text in a message table resource can. This flag cannot be used with FORMAT_MESSAGE_FROM_HMODULE or FORMAT_MESSAGE_FROM_SYSTEM.

FORMAT_MESSAGE_FROM_HMODULE

Specifies lpSourceis a module handle containing the message table resources to search. If this handle is NULL, the current process's application image file is searched. This flag cannot be used with FORMAT_MESSAGE_FROM_STRING.

FORMAT_MESSAGE_FROM_SYSTEM

Specifies FormatMessageshould search the system message table resources for the requested message. If this flag is specified with FORMAT_MESSAGE_FROM_HMODULE, FormatMessagesearches the system message table if the message is not found in the module specified by lpSource. This flag cannot be used with FORMAT_MESSAGE_FROM_STRING.

If this flag is set, an application can pass the result of the CeGetLastErrorfunction to retrieve the message text for a system-defined error.

FORMAT_MESSAGE_ARGUMENT_ARRAY

Specifies the Argumentsparameter is not a va_liststructure, but a pointer to an array of 32-bit values that represent the arguments.

The low-order byte of dwFlagscan 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 value.

FormatMessageinterprets the value of the low-order byte as follows.

Value Description

0

There are no output-line width restrictions. FormatMessagestores line breaks that are in the message definition text in the output buffer.

A non-zero value other than FORMAT_MESSAGE_MAX_WIDTH_MASK

The maximum number of characters in an output line. FormatMessageignores regular line breaks in the message definition text. FormatMessagenever splits a string delimited by white space across a line break. FormatMessagestores hard-coded line breaks in the message definition text in the output buffer. Hard-coded line breaks are coded with the %n escape sequence.

FORMAT_MESSAGE_MAX_WIDTH_MASK

FormatMessageignores regular line breaks in the message definition text. FormatMessagestores hard-coded line breaks in the message definition text in the output buffer. FormatMessagegenerates no new line breaks.
dwMessageId

[in] Specifies the 32-bit message identifier for the requested message. This parameter is ignored if dwFlagsincludes FORMAT_MESSAGE_FROM_STRING.

dwLanguageId

[in] Specifies the 32-bit language identifier for the requested message. This parameter is ignored if dwFlagsincludes FORMAT_MESSAGE_FROM_STRING.

lpBuffer

[in] Long pointer to a buffer for the formatted and null-terminated message. If dwFlagsincludes FORMAT_MESSAGE_ALLOCATE_BUFFER, FormatMessageallocates a buffer using the LocalAllocfunction, and places the address of the buffer at the address specified in lpBuffer.

nSize

[in] 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

[in] Pointer 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 Argumentsarray, %2 indicates the second argument, and so on.

pcb

[out] Pointer to a DWORDthat receives the length of the string returned by FormatMessage. If FormatMessagesucceeds, pcbholds the number of bytes (ANSI version) or characters (Unicode version) stored in the output buffer, excluding the terminating null character.

Return Value

Returns NOERROR if the method completed successfully. In this case the value pointed to by the pcbparameter will be non-zero. Returns E_FAIL if the method failed.

Remarks

The FormatMessagemethod requires a message definition as input. The message definition can come from a buffer passed into FormatMessage, from a message table resource in an already-loaded module, or the caller can prompt FormatMessageto search the system's message table resources. FormatMessagefinds the message definition in a message table resource based on a message identifier and a language identifier. FormatMessagecopies the formatted message text to an output buffer, processing any embedded insert sequences if requested. FormatMessagealso allows the filter to define message codes specific to the filter.

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 Argumentsparameter 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 used as input for the message and are formatted as the insert values. Each insert must have a corresponding element in the array.

Requirements

Header replfilt.h
Library coredll.lib
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also

Other Resources

LocalAlloc
LocalFree