ICeFileFilter::FormatMessage

Article
08/28/2006

The FormatMessage method formats a message string concerning file conversion.

Syntax

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

Parameters

dwFlags
[in] Contains a set of bit flags that specify aspects of the formatting process and how to interpret the lpBuffer parameter. See Remarks for the possible bit flags.
dwMessageId
[in] Specifies the 32-bit message identifier for the requested message. This parameter is ignored if dwFlags includes FORMAT_MESSAGE_FROM_STRING.
dwLanguageId
[in] Specifies the 32-bit language identifier for the requested message. This parameter is ignored if dwFlags includes FORMAT_MESSAGE_FROM_STRING.
lpBuffer
[in] Reference to a buffer for the formatted and null-terminated message.
nSize
[in] Specifies the maximum number of bytes (ANSI version) or characters (Unicode version) that can be stored in the output buffer if the FORMAT_MESSAGE_ALLOCATE_BUFFER flag is not set. If FORMAT_MESSAGE_ALLOCATE_BUFFER is set, nSize specifies the minimum number of bytes or characters to allocate for an output buffer.
Arguments
[in] Reference to an array of values that are used as insert values in the formatted message. %1 in the format string indicates the first value in the array, %2 indicates the second value, and so on.
pcb
[out] Reference to a variable that receives the length of the string returned by FormatMessage.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The method completed successfully. The variable referenced by pcb should be non-zero.

Remarks

dwFlags can be a combination of the bit flags described in the following two tables. These flags are defined in the winbase.h header file.

Flag	Value	Description
FORMAT_MESSAGE_ALLOCATE_BUFFER	0x00000100	Specifies that lpBuffer references a PVOID pointer and that nSize specifies the minimum number of bytes (ANSI version) or characters (Unicode version) to allocate for an output message buffer. The method 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 Windows CE LocalFree function to free the buffer when it is no longer needed.
FORMAT_MESSAGE_IGNORE_INSERTS	0x00000200	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	0x00000400	Specifies that lpBuffer 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	0x00000800	Specifies that lpBuffer is a module handle containing the message table resources to search. If lpBuffer 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	0x00001000	Specifies that the method should search the system message table resources for the requested message. An application can pass the result of the CeGetLastError function to retrieve the message text for a system-defined error. If this flag is combined with FORMAT_MESSAGE_FROM_HMODULE and the message is not found in the message table resources specified by lpBuffer, the method searches the system message table. This flag cannot be combined with FORMAT_MESSAGE_FROM_STRING.
FORMAT_MESSAGE_ARGUMENT_ARRAY	0x00002000	Specifies that the Arguments parameter is not of type va_list structure but is a pointer to an array of 32-bit values that represent the arguments.

The following table lists the low-order byte values that specify how the method handles line breaks in the output buffer and can also 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.

Low-order Byte Value	Description
0	There are no output line width restrictions. The method 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. The method ignores regular line breaks in the message definition text, never splits a string delimited by white space across a line break, and 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	The method ignores regular line breaks in the message definition text, stores hard-coded line breaks in the message definition text in the output buffer, and generates no new line breaks.

For the Arguments parameter, the interpretation of each value depends on the formatting information associated with the insert value in the message definition required by the method. The default is to treat each value as a pointer to a null-terminated string.

By default, Arguments is of type va_list *, which is a language-specific and implementation-specific data type for describing a variable number of arguments.

If Arguments is not of type va_list *, specify the FORMAT_MESSAGE_ARGUMENT_ARRAY flag using dwFlags and use Arguments to reference an array of 32-bit values. These values are used as insert values in the formatted message. Each insert must have a corresponding element in the array.

If the method succeeds, pcb references the number of bytes (ANSI version) or characters (Unicode version) stored in the output buffer, excluding the terminating null character.

The method requires a message definition as input. The message definition can come from a buffer passed to the method, from a message table resource in an already-loaded module, or the caller can prompt the method to search the system's message table resources. The method finds the message definition in a message table resource based on a message identifier and a language identifier.

The method copies the formatted message text to an output buffer, processing any embedded insert sequences if requested. The method also allows the file filter to define message codes specific to the filter.

Requirements

Smartphone: Windows Mobile 2002 and later
OS Versions: Windows CE 3.0 and later
Header: replfilt.h

Share via