Definir tipos de erros personalizados

Artigo
07/08/2024

Os drivers podem especificar seus próprios tipos de erro e mensagens de erro. Para definir uma mensagem de erro personalizada, você deve primeiro definir um novo valor IO_ERR_XXX para especificar como o membro ErrorCode da entrada do log de erros. O Visualizador de Eventos usa o valor IO_ERR_XXX para pesquisar a mensagem de erro do driver.

Para dar suporte a mensagens de erro personalizadas em seu driver, siga estas etapas:

Crie um arquivo de texto de mensagem que especifique o valor IO_ERR_XXX personalizado e as mensagens de erro correspondentes. Para obter mais informações, consulte Criando o arquivo de texto de mensagem de erro.
Compile o arquivo de texto da mensagem de erro em um recurso e anexe o recurso à imagem do driver. Para obter mais informações, consulte Compilando o arquivo de texto da mensagem de erro.
Registre a imagem do driver como contendo mensagens de erro. Para obter mais informações, consulte Registrando-se como uma fonte de mensagens de erro.

Criando o arquivo de texto da mensagem de erro

A definição dos valores IO_ERR_XXX personalizados de um driver e os modelos de mensagem de erro correspondentes são anexados como um recurso de tabela de mensagens à imagem do driver. Você pode descrever as mensagens de um driver em um arquivo de texto de mensagem (que tem uma extensão de nome de arquivo .mc).

Um arquivo de texto de mensagem consiste em duas seções: uma seção de cabeçalho e uma seção de mensagem. A seção de cabeçalho permite a declaração de nomes simbólicos para valores numéricos, enquanto a seção de mensagem especifica os valores IO_ERR_XXX e os modelos de mensagem de erro correspondentes.

Para obter um exemplo de um arquivo de texto de mensagem, consulte o arquivo Serlog.mc no exemplo de driver serial disponível no GitHub.

Seção de cabeçalho

A seção de cabeçalho deve conter esta linha:

MessageIdTypedef=NTSTATUS

Isso garante que o tipo de valores IO_ERR_XXX gerados pelo Compilador de Mensagens seja declarado como NTSTATUS.

As outras diretivas que aparecem na seção de cabeçalho definem valores simbólicos que são usados no lugar de valores numéricos na seção de mensagem.

As diretivas SeverityNames e FacilityNames definem valores simbólicos para os campos de gravidade e instalação dos valores NTSTATUS. As diretivas são do formato keyword= ( values ), em que values consiste em uma ou mais instruções do nome = do formulário value : header_name, separadas por espaços em branco. O parâmetro name é o nome que você usa para especificar o valor numérico no arquivo de texto da mensagem, enquanto o header_name é o nome desse valor declarado no arquivo de cabeçalho C gerado pelo Compilador de Mensagens. A cláusula : header_name é opcional.

Aqui está um exemplo de uma declaração de cabeçalho de nomes simbólicos para códigos de gravidade:

SeverityNames = (
  Success       = 0x0:STATUS_SEVERITY_SUCCESS
  Informational = 0x1:STATUS_SEVERITY_INFORMATIONAL
  Warning       = 0x2:STATUS_SEVERITY_WARNING
  Error         = 0x3:STATUS_SEVERITY_ERROR
)

A diretiva LanguageNames define valores simbólicos para LCIDs (IDs de localidade). A diretiva tem o formato LanguageNames = ( values ), em que values consiste em uma ou mais instruções no formato language_name = lcid : langfile, separadas por espaço em branco. O parâmetro language_name é o nome que você usa no lugar de lcid no arquivo de texto da mensagem, enquanto o nome do arquivo especifica um nome de arquivo exclusivo (sem extensão). Quando o Compilador de Mensagens gera o script de recurso a partir do arquivo de texto da mensagem, ele armazena todos os recursos de cadeia de caracteres para esse idioma em um arquivo chamado langfile.caixa.

Seção de mensagens

Cada definição de mensagem começa com a definição do valor IO_ERR_XXX personalizado que o driver usa para relatar esse tipo específico de erro. O valor IO_ERR_XXX é definido por uma série de pares de valores de palavra-chave = . As palavras-chave possíveis e seu significado são os seguintes.

Palavra-chave	Valor
MessageId	Código do novo valor IO_ERR_XXX .
Gravidade	Campo de gravidade do novo valor IO_ERR_XXX . O valor especificado deve ser um dos nomes simbólicos definidos pela diretiva de cabeçalho SeverityNames .
Instalações	Campo de instalação do novo valor IO_ERR_XXX . O valor especificado deve ser um dos nomes simbólicos definidos pela diretiva de cabeçalho FacilityNames .
SymbolicName	O nome simbólico do novo valor IO_ERR_XXX . O Compilador de Mensagens gera um arquivo de cabeçalho C que contém uma declaração #define do nome como o valor NTSTATUS correspondente. O driver usa esse nome ao especificar o tipo de erro.

A primeira palavra-chave deve ser sempre MessageId.

O restante da definição de mensagem consiste em uma ou mais versões localizadas da mensagem de erro. Cada versão tem a seguinte forma:

Language=language_name
localized_message

O valor language_name , que deve ser um dos nomes simbólicos definidos pela diretiva de cabeçalho LanguageNames , especifica o idioma do texto da mensagem. O próprio texto da mensagem localizada consiste em uma cadeia de caracteres Unicode. Todas as cadeias de caracteres inseridas no formato "%n" serão tratadas como modelos que o Visualizador de Eventos substituirá quando o erro for registrado. A cadeia de caracteres "%1" é substituída pelo nome do objeto de dispositivo do driver, enquanto "%2" a "%n" são substituídas por todas as cadeias de caracteres de inserção fornecidas pelo driver.

A definição da mensagem é encerrada por um único ponto sozinho em uma linha.

Se você definir mensagens de erro personalizadas, não deverá usar cadeias de caracteres de inserção, a menos que seja necessário. As cadeias de caracteres de inserção não podem ser localizadas, portanto, devem ser usadas para cadeias de caracteres independentes de idioma, como números ou nomes de arquivo. A maioria dos drivers não usa cadeias de caracteres de inserção.

Compilando o arquivo de texto da mensagem de erro

Use o Compilador de Mensagens (mc.exe) para compilar seu arquivo de texto de mensagem em um arquivo de script de recurso (que tem uma extensão de nome de arquivo .rc). Um comando do formulário

mc filename.mc

faz com que o Compilador de Mensagens gere os seguintes arquivos:

filename.h, um arquivo de cabeçalho que contém declarações de cada valor IO_ERR_XXX personalizado em filename.mc.
filename.rc, um script de recurso.
Um arquivo para cada idioma que aparece no arquivo de texto da mensagem. Cada um desses arquivos armazena todos os recursos de cadeia de caracteres de mensagem de erro para um idioma. O arquivo para cada idioma é chamado langfile.bin, em que langfile é o valor especificado para o idioma na diretiva LanguageNames do arquivo de texto da mensagem.

Mais informações sobre o Compilador de Mensagens podem ser encontradas no SDK do Microsoft Windows.

O Compilador de Recursos converte um script de recurso em um arquivo de recurso que você pode anexar à imagem do driver. Se você usar o utilitário Build para criar seu driver, poderá garantir que o script de recurso seja convertido em um arquivo de recurso e anexado à imagem do driver simplesmente incluindo o nome do script de recurso na variável SOURCES do driver. Para obter mais informações sobre o Compilador de Recursos, consulte a documentação do SDK do Windows. Para obter informações sobre como usar o utilitário Build para criar seu driver, consulte Criando um driver.

Partilhar via