|
|
This document describes how messages will be input, stored and formattedby a Win32 application.
1. Message Input
Messages are input as ASCII text in a text file. The format of this file supports specifying multiple versions of the same message text, one for each language supported. It also supports automatic assignment of code numbers to each message, along with the generation of a C language include file for use by the application for accessing the messages using symbolic constants. The purpose of the message text file is to define all of the messages needed by an application, in a format that makes it easy to support multiple languages with the same image file.
Message text files are converted into binary resource files by the MC program. These binary resource files are then input to the RC compiler which will put them in the resource table for an application or DLL.
The format of the message text file (default extension is .mc). Basic syntax is Keyword=Value, where spaces around the equal sign are ignored, and the value is delimited by white space from the next keyword=value pair. Case is ignored when comparing against keyword names. The value portion can either be a numeric integer constant, {NUMBER}, using C syntax; a symbol name, {NAME}, that follows the rules for C identifier names; or a file name that follows the rules for the FAT file system (8 characters or less, no periods).
Comment lines are allowed in the message text file. The comment syntax is the same as for WIN.INI, namely a semicolon begins a comment which is terminated by the end of the line. Comments that exist by themselves on a line are copied as is to the output .h file.
The overall structure of a message text file consists of a header section which contains zero or more of the following keywords:
MessageIdTypedef={NAME} SeverityNames=({NAME}={NUMBER}:{NAME}) FacilityNames=({NAME}={NUMBER}:{NAME}) LanguageNames=({NAME}={NUMBER}:{FILENAME}[:{CODEPAGE}]) OutputBase={NUMBER}
These keywords have the following meaning:
MessageIdTypedef - gives a symbolic name that is output as the typedef name for each numeric MessageId value. The default value for this is NULL, which means there will be no type cast output when defining symbolic names for a MessageId.
SeverityNames - defines the set of names that are allowed as the value of the Severity keyword in the message definition. The set is delimited by left and right parenthesis. Associated with each severity name is a number that, when shifted left by 30, gives the bit pattern to logically OR with the Facility value and MessageId to come up with the full 32-bit message code. The default value of this keyword is:
SeverityNames=(Success=0x0 Informational=0x1 Warning=0x2 Error=0x3 )
Severity values occupy the high two bits of a 32-bit message code. Any severity value that does not fit in two bits is an error. The severity codes can be given symbolic names by following each value with :{NAME}
FacilityNames - defines the set of names that are allowed as the value of the Facility keyword in the message definition. The set is delimited by left and right parenthesis. Associated with each facility name is a number that, when shift it left by 16 bits, gives the bit pattern to logically OR with the Severity value and MessageId to come up with the full 32-bit message code. The default value of this keyword is:
FacilityNames=(System=0x0FF Application=0xFFF )
Facility codes occupy the low order 12 bits of the high order 16-bits of a 32-bit message code. Any facility code that does not fit in 12 bits is an error. This allows for 4096 facility codes. The first 256 are reserved for use by the system software.
The facility codes can be given symbolic names by following each value with :{NAME}
LanguageNames - defines the set of names that are allowed as the value of the Language keyword in the message definition. The set is delimited by left and right parenthesis. Associated with each language name is a number and a file name that will be used to name the binary output file that will contain all of the message text for that language. The number corresponds to the Language Id tag to use in the resource table. The number is separate from the file name with a colon. The initial value of this keyword is:
LanguageNames=(English=1:MSG00001)
Any new names that an application defines in its .mc file which don't override any of the builtin names will be added to the list of valid languages. This allows an application to support private languages with descriptive names.
If the message file contains messages for languages that must be represented in separate codepages, the optional fourth (4th) parameter may be used to specify the codepage that the messages for that Language's messages are in.
LanguageNames=(Japanese=411:MSG00411:932)
The default codepage used, if the codepage is not explicitly specified, is the OEM Codepage of the system.
OutputBase - sets the output radix for the constants output to C header file for messages. (It does not set the radix for the SEVERITY and FACILITY constants. These default to HEX and can be output in decimal using the -d switch.) If present, Outputbase overwrites the -d switch for message constants in the header file. Legal values are 10 and 16.
The OutputBase keyword is legal both in the header section and in the message definition section of the input file. The OutputBase can be changed as often as desired.
Following the header section are zero or more message definitions. Each message definition begins with one or more of the following keywords.
MessageId={|{NUMBER}|+{NUMBER}} Severity={SEVERITY_NAME} Facility={FACILITY_NAME} SymbolicName={NAME}
The MessageId keyword is required to mark the beginning of the message definition, although its value is optional. If no value is specified, then the value used will be the last value used for the facility, plus one. If the value is specified as +{NUMBER} then the value used will be the last value used for the facility, plus the number after the plus sign. Otherwise if a numeric value is given, that will be value used. Any MessageId value that does not fit in 16 bits is an error.
Severity and Facility are optional keywords that can specify additional bits to OR into the final 32-bit message code. If either of these are not specified they default to the value last specified for a message definition. The initial values of these prior to processing the first message definition is:
Severity=Success Facility=Application
The value associated with these keywords must match one of the names given to the FacilityNames and SeverityNames keywords. The SymbolicName keyword allows the ISV to associate a C symbolic constant name with the final 32-bit message code that is a result of ORing together the MessageId, Severity and Facility bits. The constant definition is output to the generated .h file with the following format:
// // {MESSAGETEXT} //
#define CONSTANT_SYMBOL_NAME ((MessageIdTypedef) 0x12345678)
where the comment before the definition is a copy of the message text for the first language specified in the message definition. The CONSTANT_SYMBOL_NAME is the value of the SymbolicName keyword. The MessageIdTypedef is not output if it is NULL, the default value.
After the message definition keywords, comes one or more message text definitions. Each message text definition begins with the Language keyword that identifies which binary output file this message text is to be output to. Beginning on the very next line is the first line of the message text. The message text is terminated by a line containing a single period at the beginning of the line, immediately followed by a new line. No spaces allowed around keyword. Within the message text, blank lines and white space are preserved as part of the message.
Language={LANGUAGE_NAME} {MESSAGETEXT} .
Within the message text, several escape sequences are supported for dynamically formatting the message. The percent sign character (%) begins all escape sequences.
%0 - This 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! - This identifies an insert. The value of n can be between 1 and 99. The printf format string must be bracketed by exclamation marks. It is optional and defaults to !s! if not specified.
The printf format string can contain the * specifier for either the precision or width components, and if so, they will consume inserts %n+1 and %n+2 for their values at run time. MC will print a warning message if an explicit reference is made to these inserts elsewhere in the message text.
Inserts must reference a parameter passed to the FormatMessage API call. It will return an error if a message refers to an insert that was not passed to the FormatMessage API call.
Any other character following a percent sign, other than a digit will be formatted in the output message without the percent sign. Some examples:
%% - will output a single percent sign in the formatted message text.
%n - will output 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.
%r - will output a hard carriage return, without a trailing newline.
%b - will output 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.
%t - will output a tab in the formatted message text.
%. - will output 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.
%! - will output 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.
Unicode support is not understood yet. If the input file is ASCII text, do we need an escape sequence to allow input of Unicode values? Or do we just let them use DBCS in the text file, assuming they have a text editor that can do this.
2. Message Compiler (MC)
This program converts .mc message text files into binary files suitable for inclusion into a .RC file by the resource compiler.
Command line syntax:
MC [-v] [-w] [-s] [-d] [-n] [-h DirSpec] [-e extension] [-r DirSpec] filename[.mc] ...
where:
-v - generates verbose output to stderr.
-w - generates a warning message whenever an insert escape sequence is seen that is a superset of the type supported by OS/2 mkmsgf (i.e. anything other than %0 and %n). Useful for converting old OS/2 message files to this format.
-s - Add an extra line to the beginning of each message that is the symbolic name associated with the message id.
-d - Output SEVERITY and FACILTY constants in decimal. Set the initial output radix for messages to decimal.
-n - Terminates all strings with null's in the message tables.
-e - Specify the extension for the header file. From 1 - 3 chars. -h DirSpec - specifies the target directory of the generated .h file. The file name is the name of the .mc file with a .h extension.
-r DirSpec - specifies the target directory of the generated .rc file. The file name is the name of the .mc file with a .rc extension.
filename.mc - specifes one or more input message files that will be compiled into one or more binary resource files, one for each language that the message files contain message text for.
The message compiler reads the .mc file and generates a .h file containing all the symbolic name definitions. For each LanguageId that was used to specify message text, it outputs a binary file containing a message table resource. It also outputs a single .rc file that contains the appropriate RC syntax to include each binary file output as a resource with the appropriate name and type ids.
3. Message Win32 API Calls
DWORDAPIENTRYFormatMessage( DWORD dwFlags, LPVOID lpSource, DWORD dwMessageId, DWORD dwLanguageId, LPSTR lpBuffer, DWORD nSize, va_list Arguments )
Routine Description:
This function formats a message string. Input to this function is a message definition. It can come from a buffer passed into this function. It can come from a message table resource in a module already loaded. Or the caller can ask this function to search the system message table resource(s) for the message. This function finds the message definition based on the Message Id and the Language Id and copies the message text to the output buffer, processing any imbedded insert sequences if requested.
Arguments:
dwFlags - Specifies options to the formatting process along with how to interpret the lpSource parameter. The low order 16bits of this parameter are the maximum width of a line, in characters. Possible values are:
FORMAT_MESSAGE_ALLOCATE_BUFFER - the lpBuffer is a PVOID * and nSize is the minimum size to allocate. This function will then allocate a buffer large enought to hold the formatted message and store the pointer to the buffer in the location pointed to by lpBuffer. Caller should free the buffer with LocalFree when they are done using it.
FORMAT_MESSAGE_IGNORE_INSERTS - insert sequences in the message definition will be ignored and passed through to the output buffer as is. Useful for fetching a message for later formatting. If this flag is set, the lpArguments parameter is ignored.
FORMAT_MESSAGE_FROM_STRING - lpSource is a pointer to a null terminated message definition. It can contain insert sequences just as the message text in the .mc file can.
FORMAT_MESSAGE_FROM_HMODULE - lpSource is a module handle that contains the message table resource(s) to search. If this handle is NULL, then the current process's application image file will be searched.
FORMAT_MESSAGE_FROM_SYSTEM - If the requested message was not found in lpSource or if lpSource was not examined (i.e. neither of the preceeding two flags was specified), then this function will search the system message table resource(s).
FORMAT_MESSAGE_ARGUMENT_ARRAY - If set, specifies that the passed 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.
FORMAT_MESSAGE_MAX_WIDTH_MASK - The low order 8 bits specify the maximum width of each line formatted into the output buffer. A maximum width of zero, means that no restrictions are placed on the width, and only the line breaks in the message definition will be placed in the output buffer. If a non-zero value is specified, then line breaks in the message definition text are ignored, and instead line breaks are calculated based on the maximum width, with white space delimited strings never being split across a line break. Hard coded line breaks in the message definition text, that are identified by the %n escape sequence, are always output to the output buffer.
If the width specified is FORMAT_MESSAGE_MAX_WIDTH_MASK, then line breaks in the message file are ignored and only hard coded line breaks are kept and none are generated.
lpSource - specifies where to retrieve the message definition from. The type of this parameter depends upon the settings in the dwFlags parameter.
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 LPSTR that points to unformatted message text. It will be scanned for inserts and formatted accordingly.
If neither of these options is specified, then this parameter is ignored.
dwMessageId - specifices the 32-bit message identifier that identifies the message being requested. This parameter is ignored if the FORMAT_MESSAGE_FROM_STRING flag is specified.
dwLanguageId - specifices the 32-bit language identifier that identifies the language of the message being requested. This parameter is ignored if the FORMAT_MESSAGE_FROM_STRING flag is specified.
lpBuffer - specifies a pointer to a buffer where the formatted message is to be written. A terminating null byte will also be written. If the FORMAT_MESSAGE_ALLOCATE_BUFFER flag was specified, then this parameter points to a 32-bit pointer value that is filled in by this call with a pointer allocated via LocalAlloc to contain the text of the message.
nSize - specifies the maximum number of bytes that can be stored in the output buffer. This parameter is ignore if the FORMAT_MESSAGE_ALLOCATE_BUFFER flag is set.
Arguments - specifies a pointer to variable number of arguments. These arguments are used to satisfy insert requests in the format string. Thus %1 in the format string specifies the first argument in the variable number of arguments described by the Arguments parameter; %3 would specify the third, etc.
The interpretation of each 32-bit arguments value depends upon the formatting information associated with the insert in the message definition. The default is to treat each pointer 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 that are are input to the message formatted as the insert values.Return Value:
DwORD - Returns the number of bytes actually stored in the output buffer, excluding the terminating null character. Returns 0 if an error occurred. Extended error status is available via the GetLastError API.
|
