Definición de tipos de error personalizados

Los controladores pueden especificar sus propios tipos de error y mensajes de error. Para definir un mensaje de error personalizado, primero debe definir un nuevo valor IO_ERR_XXX para especificarlo como miembro ErrorCode de la entrada del registro de errores. El Visor de eventos usa el valor IO_ERR_XXX para buscar el mensaje de error del controlador.

Para admitir mensajes de error personalizados en el controlador, siga estos pasos:

1. Cree un archivo de texto de mensaje que especifique el valor personalizado IO_ERR_XXX y los mensajes de error correspondientes. Para obtener más información, vea Crear el archivo de texto del mensaje de error.

2. Compile el archivo de texto del mensaje de error en un recurso y adjunte el recurso a la imagen del controlador. Para obtener más información, vea Compilar el archivo de texto del mensaje de error.

3. Registre la imagen del controlador como que contiene mensajes de error. Para obtener más información, consulte Registro como origen de mensajes de error.

Crear el archivo de texto del mensaje de error

La definición de los valores personalizados de IO_ERR_XXX de un controlador y las plantillas de mensaje de error coincidentes se adjuntan como un recurso de tabla de mensajes a la imagen del controlador. Puede describir los mensajes de un controlador en un archivo de texto de mensaje (que tiene una extensión de nombre de archivo .mc).

Un archivo de texto de mensaje consta de dos secciones: una sección de encabezado y una sección de mensajes. La sección de encabezado permite la declaración de nombres simbólicos para valores numéricos, mientras que la sección del mensaje especifica los valores IO_ERR_XXX y las plantillas de mensaje de error coincidentes.

Para obtener un ejemplo de un archivo de texto de mensaje, consulte el archivo Serlog.mc en el ejemplo de controlador serie disponible en GitHub.

Sección de encabezado

La sección de encabezado debe contener esta línea:

MessageIdTypedef=NTSTATUS

Esto garantiza que el tipo de IO_ERR_XXX valores generados por el compilador de mensajes se declare como NTSTATUS.

Las demás directivas que aparecen en la sección de encabezado definen valores simbólicos que se usan en lugar de valores numéricos en la sección del mensaje.

Las directivas SeverityNames y FacilityNames definen valores simbólicos para los campos de gravedad y instalación de los valores NTSTATUS. Las directivas son de la palabra clave form= ( valores ), donde los valores constan de una o varias instrucciones del valor de nombre = del formulario : header_name, separados por espacios en blanco. El parámetro name es el nombre que se usa para especificar el valor numérico en el archivo de texto del mensaje, mientras que el header_name es el nombre de este valor declarado en el archivo de encabezado de C generado por el compilador de mensajes. La cláusula : header_name es opcional.

Este es un ejemplo de una declaración de encabezado de nombres simbólicos para códigos de gravedad:

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

La directiva LanguageNames define valores simbólicos para identificadores de configuración regional (LCID). La directiva es del formato LanguageNames = ( values ), donde los valores constan de una o más instrucciones del formulario language_name = lcid : langfile, separados por espacios en blanco. El parámetro language_name es el nombre que se usa en lugar de lcid en el archivo de texto del mensaje, mientras que el nombre de archivo especifica un nombre de archivo único (sin extensión). Cuando el compilador de mensajes genera el script de recursos desde el archivo de texto del mensaje, almacena todos los recursos de cadena para este idioma en un archivo denominado langfile.bin.

Sección de mensajes

Cada definición de mensaje comienza con la definición del valor de IO_ERR_XXX personalizado que el controlador usa para notificar este tipo de error determinado. El valor IO_ERR_XXX se define mediante una serie de pares de valor de palabra clave = . Las posibles palabras clave y su significado son las siguientes.

Palabra clave	Valor
MessageId	Campo de código del nuevo valor IO_ERR_XXX .
Gravedad	Campo gravedad del nuevo valor IO_ERR_XXX . El valor especificado debe ser uno de los nombres simbólicos definidos por la directiva de encabezado SeverityNames .
Instalaciones	Campo de instalación del nuevo valor IO_ERR_XXX . El valor especificado debe ser uno de los nombres simbólicos definidos por la directiva de encabezado FacilityNames .
SymbolicName	Nombre simbólico del nuevo valor IO_ERR_XXX . El compilador de mensajes genera un archivo de encabezado de C que contiene una declaración #define del nombre como el valor NTSTATUS correspondiente. El controlador usa ese nombre al especificar el tipo de error.

La primera palabra clave siempre debe ser MessageId.

El resto de la definición del mensaje consta de una o varias versiones localizadas del mensaje de error. Cada versión tiene el formato :

Language=language_name
localized_message

El language_name valor, que debe ser uno de los nombres simbólicos definidos por la directiva de encabezado LanguageNames , especifica el idioma del texto del mensaje. El propio texto del mensaje localizado consta de una cadena Unicode. Las cadenas incrustadas del formulario "%n" se tratarán como plantillas que el Visor de eventos reemplazará cuando se registre el error. La cadena "%1" se reemplaza por el nombre del objeto de dispositivo del controlador, mientras que "%2" a "%n" se reemplaza por las cadenas de inserción proporcionadas por el controlador.

La definición del mensaje finaliza por un solo punto en una línea.

Si define mensajes de error personalizados, no debe usar cadenas de inserción a menos que sea necesario. Las cadenas de inserción no se pueden localizar, por lo que deben usarse para cadenas independientes del lenguaje, como números o nombres de archivo. La mayoría de los controladores no usan cadenas de inserción.

Compilar el archivo de texto del mensaje de error

Use el compilador de mensajes (mc.exe) para compilar el archivo de texto del mensaje en un archivo de script de recursos (que tiene una extensión de nombre de archivo .rc). Comando del formulario

mc filename.mc

hace que el compilador de mensajes genere los siguientes archivos:

• filename.h, un archivo de encabezado que contiene declaraciones de cada valor personalizado IO_ERR_XXX en nombre de archivo.mc.

• filename.rc, un script de recursos.

• Un archivo para cada idioma que aparece en el archivo de texto del mensaje. Cada uno de estos archivos almacena todos los recursos de cadena de mensaje de error para un idioma. El archivo de cada idioma se denomina langfile.bin, donde langfile es el valor especificado para el idioma en la directiva LanguageNames del archivo de texto del mensaje.

Puede encontrar más información sobre el compilador de mensajes en Microsoft Windows SDK.

El compilador de recursos convierte un script de recursos en un archivo de recursos que puede asociar a la imagen del controlador. Si usa la utilidad Build para compilar el controlador, puede asegurarse de que el script de recursos se convierte en un archivo de recursos y se adjunta a la imagen del controlador simplemente mediante la inclusión del nombre del script de recursos en la variable SOURCES para el controlador. Para obtener más información sobre el compilador de recursos, consulte la documentación de Windows SDK. Para obtener información sobre el uso de la utilidad Build para compilar el controlador, consulte Building a Driver (Compilación de un controlador).