Arquivos de Texto da Mensagem

  • Artigo

As mensagens são definidas em um arquivo de texto de mensagem. O compilador de mensagem atribui números a cada mensagem e gera um arquivo de inclusão C/C++ que o aplicativo pode usar para acessar uma mensagem usando uma constante simbólica.

A sintaxe geral para instruções em um arquivo de texto de mensagem é a seguinte:

= palavra-chave valor

Espaços ao redor do sinal de igual são ignorados e o valor é delimitado por espaço em branco (incluindo quebras de linha) do próximo par palavra-chave/valor. Maiúsculas e minúsculas é ignorada ao comparar com nomes palavra-chave. A parte do valor pode ser uma constante de inteiro numérico usando a sintaxe C/C++, um nome de símbolo que segue as regras para identificadores C/C++ ou um nome de arquivo com 8 caracteres ou menos, sem períodos.

Para obter um arquivo de mensagem de exemplo, consulte Arquivo de texto de mensagem de exemplo.

Comentários

As linhas de comentário são permitidas no arquivo de texto da mensagem. Um ponto e vírgula (;) inicia um comentário que termina no final da linha. Siga o ponto e vírgula com um indicador de comentário em linha único C/C++ (//) para que o arquivo de cabeçalho gerado pelo compilador de mensagem seja compilado em seu aplicativo.

;// This is a single-line comment.

Para um comentário em bloco, comece cada linha com um ponto e vírgula e coloque um indicador de comentário de bloco aberto C/C++ (/*) após o ponto e vírgula na primeira linha e o indicador de comentário do bloco de fechamento (*/) após o ponto e vírgula na última linha.

;/* This is a block comment.
;   It spans multiple lines.
;*/

Seção de cabeçalho

O arquivo de texto da mensagem contém um cabeçalho que define nomes e identificadores de idioma para uso pelas definições de mensagem no corpo do arquivo. O cabeçalho contém zero ou mais das instruções a seguir.

Sintaxe de instrução Descrição
MessageIdTypedef=type Tipo a ser usado na definição de mensagem da seguinte maneira: #define nome ((tipo)0xnnnnnnnn)
O tipo deve ser grande o suficiente para acomodar todo o código de mensagem, como um DWORD. O tipo também pode ser um tipo definido no código-fonte do aplicativo. O valor padrão do tipo está vazio, portanto, nenhuma conversão de tipo é usada.
Essa instrução pode ser especificada no cabeçalho e sempre que necessário na seção de definição de mensagem.
SeverityNames=(name=number[:name]) Conjunto de nomes permitidos para a gravidade em uma definição de mensagem. Associado a cada nome de severidade é um número que, quando deslocado para a esquerda por 30 bits, fornece o padrão de bit para logical-OR com os valores de instalação e ID de mensagem para formar o código da mensagem. Qualquer valor de severidade que não caiba em 2 bits é um erro. Os códigos de severidade também podem receber nomes simbólicos. O valor padrão é definido da seguinte maneira: SeverityNames=( Success=0x0 Informational=0x1 Warning=0x2 Error=0x3)
FacilityNames=(name=number[:name]) Conjunto de nomes permitidos para os valores de instalação em uma definição de mensagem. Associado a cada nome de instalação é um número que, quando deslocado para a esquerda por 16 bits, fornece o padrão de bit para logical-OR com os valores de severidade e ID da mensagem para formar o código da mensagem. Qualquer valor de instalação que não caiba em 12 bits é um erro. Isso permite códigos de instalação 4096; os primeiros 256 códigos são reservados para uso do sistema. Os códigos de instalação também podem receber nomes simbólicos. O valor padrão é definido da seguinte maneira: FacilityNames=( System=0x0FF Application=0xFFF)
LanguageNames=(name=number:filename) Conjunto de nomes permitidos para os valores de idioma em uma definição de mensagem. O número é usado como o identificador de idioma na tabela de recursos. O arquivo especificado contém as mensagens para esse idioma. Normalmente, é um arquivo .bin gerado pelo compilador de mensagens.
Um valor de exemplo é: LanguageNames=(English=0x409:MSG00409)
Para obter uma lista de identificadores de idioma, consulte https://go.microsoft.com/fwlink/p/?linkid=190280.
OutputBase=number Radix de saída para as constantes de mensagem que o compilador de mensagem grava no arquivo de cabeçalho. Se presente, esse valor substitui a opção -d. Esse número pode ser 10 (decimal) ou 16 (hexadecimal).

Definições de mensagem

Um arquivo de texto de mensagem contém zero ou mais definições de mensagem após a seção de cabeçalho. A tabela a seguir descreve as instruções message-definition. A instrução MessageId marca o início da definição da mensagem. As instruções Severity e Facility são opcionais.

Sintaxe de instrução Descrição
MessageId=[number|+number] Identificador da mensagem. Essa instrução é necessária, embora o valor seja opcional. Se nenhum valor for especificado, o valor usado será o valor anterior para a instalação, mais um. Se o valor for especificado com um sinal de adição, o valor usado será o valor anterior para a instalação, mais o número após o sinal de adição. Qualquer valor especificado deve caber em 16 bits. Para obter mais detalhes sobre como o valor da mensagem é formado a partir da gravidade, da instalação e da ID da mensagem, consulte o diagrama em Winerror.h. Esse arquivo de cabeçalho define códigos de erro para o sistema.
Severity=name Um dos valores especificados por SeverityNames no cabeçalho . Essa instrução é opcional. Se nenhum valor for especificado, o valor usado será o valor especificado pela última vez para uma definição de mensagem. O padrão para a primeira definição de mensagem é Severity=Success
Facility=name Um dos valores especificados por FacilityNames no cabeçalho . Essa instrução é opcional. Se nenhum valor for especificado, o valor usado será o valor especificado pela última vez para uma definição de mensagem. O padrão para a primeira definição de mensagem é Facility=Application
SymbolicName=name Associa uma constante simbólica C/C++ ao código da mensagem. Ele é usado na definição de mensagem da seguinte maneira: #define nome ((tipo)0xnnnnnnnn)
OutputBase={number} Radix de saída para as constantes de mensagem que o compilador de mensagem grava no arquivo de cabeçalho. Se presente, esse valor substitui a opção -d. Esse número pode ser 10 (decimal) ou 16 (hexadecimal).
Language=name Um dos valores especificados por LanguageNames no cabeçalho . Essa instrução é opcional. Se nenhum valor for especificado, o valor usado será o valor especificado pela última vez para uma definição de mensagem. O padrão para a primeira definição de mensagem é o seguinte: Language=English
texto da mensagem Texto da mensagem. Ele está incluído no arquivo binário da mensagem. Ele também está incluído no arquivo de cabeçalho no bloco de comentários que precede diretamente a definição da mensagem.
. O texto da mensagem é encerrado por uma nova linha que contém um único período no início da linha.

Se a definição da mensagem incluir texto da mensagem para mais de um idioma, cada idioma exigirá sua própria instrução Language, texto da mensagem e terminação de nova linha com um ponto final. Por exemplo:

MessageId=0x1
Severity=Error
Facility=Runtime
SymbolicName=MSG_BAD_COMMAND
Language=English
You have chosen an incorrect command.
.

Language=Japanese
<Japanese message string goes here>
.

Você pode especificar as seguintes sequências de escape para formatar o texto da mensagem para uso pelo visualizador de eventos ou pelo aplicativo. O caractere de sinal de porcentagem (%) inicia todas as sequências de escape. Qualquer outro caractere após um sinal de porcentagem é exibido sem o sinal de porcentagem.

% n[! format_specifier!]

Descreve uma inserção. Cada inserção é uma entrada na matriz Arguments na função FormatMessage . O valor de n pode ser um número entre 1 e 99. O especificador de formato é opcional. Se nenhum valor for especificado, o padrão será !s!. Para obter informações sobre o especificador de formato, consulte wsprintf.

O especificador de formato pode usar * para a precisão ou a largura. Quando especificados, eles consomem inserções numeradas n+1 e n+2.

%0

Encerra uma linha de texto de mensagem sem um caractere de nova linha à direita. Isso pode ser usado para criar uma linha longa ou encerrar uma mensagem de prompt sem um caractere de nova linha à direita.

%.

Gera um único período. Isso pode ser usado para exibir um período no início de uma linha, o que de outra forma encerraria o texto da mensagem.

%!

Gera um único ponto de exclamação. Isso pode ser usado para especificar um ponto de exclamação imediatamente após uma inserção.

%%

Gera um único sinal de porcentagem.

%n

Gera uma quebra de linha dura quando ocorre no final de uma linha. Isso pode ser usado com FormatMessage para garantir que a mensagem se ajuste a uma determinada largura.

%b

Gera um caractere de espaço. Isso pode ser usado para garantir um número apropriado de espaços à direita em uma linha.

%r

Gera um retorno de carro rígido sem um caractere de nova linha à direita.