ICeFileFilter::FormatMessage

The ICeFileFilter::FormatMessage 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;

At a Glance

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 FormatMessage 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:

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. FormatMessage 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 retrieving 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 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 that lpSource is a module handle containing the message-table resources to search. If this lpSource handle is NULL, the current process's application image file will be searched. This flag cannot be used with FORMAT_MESSAGE_FROM_STRING.

FORMAT_MESSAGE_FROM_SYSTEM

Specifies that FormatMessage should search the system message-table resources for the requested message. If this flag is specified with FORMAT_MESSAGE_FROM_HMODULE, FormatMessage searches 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 specified, an application can pass the result of the CeGetLastError 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 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.

FormatMessage interprets the value of the low-order byte as follows:

0

There are no output line width restrictions. FormatMessage stores line breaks that are in the message definition text in 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. FormatMessage ignores regular line breaks in the message definition text. FormatMessage never splits a string delimited by white space across a line break. FormatMessage stores 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

FormatMessage ignores regular line breaks in the message definition text. FormatMessage stores hard-coded line breaks in the message definition text in the output buffer. FormatMessage generates no new line breaks.

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.

lpBuffer

Pointer to a buffer for the formatted (and null-terminated) message. If dwFlags includes FORMAT_MESSAGE_ALLOCATE_BUFFER, FormatMessage 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

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

pcb

Pointer to a DWORD that receives the length of the string returned by FormatMessage. If FormatMessage succeeds, pcb holds the number of bytes (ANSI version) or characters (Unicode version) stored in the output buffer, excluding the terminating null character.

Return Values

NOERROR

FormatMessage was successful. The variable pointed to by the pcb parameter should be non-zero.

E_FAIL

FormatMessage failed.

Remarks

The FormatMessage method 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 FormatMessage to search the system's message table resources. FormatMessage finds the message definition in a message table resource based on a message identifier and a language identifier. FormatMessage copies the formatted message text to an output buffer, processing any embedded insert sequences if requested. FormatMessage also allows the filter to define message codes specific to the filter. For more information, see Transferring Files and Filter Defined Error Values.