Partilhar via

Arquivos de texto de mensagem

  • Artigo

As mensagens são definidas em um arquivo de texto de mensagem. O compilador de mensagens 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

Os 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. O caso é ignorado quando comparado com nomes de palavras-chave. O valor parte pode ser uma constante inteira numérica usando 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 pontos.

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

Observações

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 de linha única C/C++ (//) para que o arquivo de cabeçalho gerado pelo compilador de mensagens seja compilado em seu aplicativo.

;// This is a single-line comment.

Para um comentário de bloco, comece cada linha com um ponto-e-vírgula e, em seguida, 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 de bloco fechado (*/) 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 seguintes instruções.

Sintaxe da instrução Descrição
MessageIdTypedef=tipo Digite a ser usado na definição de mensagem da seguinte maneira: #define nome ((type)0xnnnnnnnn)
O tipo deve ser grande o suficiente para acomodar todo o código da mensagem, como um DWORD. O tipo também pode ser um tipo definido no código-fonte do aplicativo. O valor padrão para tipo está vazio, portanto, nenhuma conversão de tipo é usada.
Esta instrução pode ser especificada no cabeçalho e quantas vezes forem necessárias na seção de definição de mensagem.
SeverityNames=(nome=número[:nome]) Conjunto de nomes permitidos para a severidade em uma definição de mensagem. Associado a cada nome de gravidade está um número que, quando deslocado para a esquerda por 30 bits, dá o padrão de bits para lógico-OU com os valores de facilidade e ID da mensagem para formar o código da mensagem. Qualquer valor de gravidade que não se encaixe em 2 bits é um erro. Os códigos de gravidade também podem receber nomes simbólicos. O valor padrão é definido da seguinte forma: SeverityNames=( Success=0x0 Informational=0x1 Warning=0x2 Error=0x3)
FacilityNames=(nome=número[:nome]) Conjunto de nomes permitidos para os valores de recurso em uma definição de mensagem. Associado a cada nome de recurso está um número que, quando deslocado para a esquerda por 16 bits, dá o padrão de bits para lógico-OU com os valores de gravidade e ID da mensagem para formar o código da mensagem. Qualquer valor de recurso que não caiba em 12 bits é um erro. Isso permite 4096 códigos de instalação; 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 forma: FacilityNames=( System=0x0FF Application=0xFFF)
LanguageNames=(nome=número:nome do arquivo) Conjunto de nomes permitidos para os valores de idioma em uma definição de mensagem. O número é usado como 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 exemplo de valor é: LanguageNames=(English=0x409:MSG00409)
Para obter uma lista de identificadores de idioma, consulte https://go.microsoft.com/fwlink/p/?linkid=190280.
OutputBase=número Radix de saída para as constantes de mensagem que o compilador de mensagens grava no arquivo de cabeçalho. Se presente, esse valor substitui a opção -d. Este 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 de definição de mensagem. A instrução MessageId marca o início da definição da mensagem. As instruções Severity e Facility são opcionais.

Sintaxe da instrução Descrição
MessageId=[número|+número] Identificador da mensagem. Esta instrução é obrigató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 mais, o valor usado será o valor anterior para a instalação, mais o número após o sinal de mais. Qualquer valor especificado deve caber em 16 bits. Para obter mais detalhes sobre como o valor da mensagem é formado a partir da gravidade, recurso e ID da mensagem, consulte o diagrama em Winerror.h. Este arquivo de cabeçalho define códigos de erro para o sistema.
Severidade=nome Um dos valores especificados por SeverityNames no cabeçalho. Esta declaraçã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=nome Um dos valores especificados por FacilityNames no cabeçalho. Esta declaraçã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=nome Associa uma constante simbólica C/C++ ao código da mensagem. Ele é usado na definição de mensagem da seguinte forma: #define nome ((tipo)0xnnnnnnnn)
OutputBase={número} O radix de saída para as constantes de mensagem que o compilador de mensagens grava no arquivo de cabeçalho. Se presente, esse valor substitui a opção -d. Este número pode ser 10 (decimal) ou 16 (hexadecimal).
Idioma=nome Um dos valores especificados por LanguageNames no cabeçalho. Esta declaraçã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 para a 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 é terminado por uma nova linha que contém um único ponto no início da linha.

Se a definição de mensagem incluir texto de mensagem para mais de um idioma, cada idioma exigirá sua própria instrução de idioma, texto da mensagem e terminação de nova linha com um ponto. 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 seu 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çãoFormatMessage. 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 especificado, eles consomem inserções numeradas n+1 e n+2.

%0

Encerra uma linha de texto da 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 ponto no início de uma linha, 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 rígida quando ocorre no final de uma linha. Isso pode ser usado com FormatMessage para garantir que a mensagem se encaixe em 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 carruagem rígida sem um caractere de nova linha à direita.