Gravando no Log de Eventos do Sistema
Os erros são especificados pelo valor NTSTATUS. O sistema predefini valores NTSTATUS específicos que podem ser usados por drivers e os gravadores de driver podem definir erros adicionais. Observe que somente determinados valores NTSTATUS podem ser usados ao registrar erros em log.
Cada valor NTSTATUS que pode ser usado quando erros de registro em log tem uma mensagem de erro associada. Por exemplo, o driver de porta paralela usa o valor NTSTATUS PAR_INTERRUPT_CONFLICT para representar conflitos de interrupção de hardware, com o texto da mensagem "Conflito de interrupção detectado para %1".
O Visualizador de Eventos exibe o texto da mensagem na caixa de texto Descrição na folha de propriedades da entrada de log. Se a cadeia de texto da mensagem contiver "%1", o Visualizador de Eventos a substituirá pelo nome do dispositivo que registrou a entrada. O texto da mensagem pode conter parâmetros adicionais do formulário "%2", "%3" e assim por diante. Quando o driver registra o erro, ele pode fornecer valores de cadeia de caracteres para esses parâmetros. Esses valores de cadeia de caracteres são conhecidos como cadeias de caracteres de inserção. O Visualizador de Eventos os inserirá automaticamente no lugar dos valores percentuais.
O driver também pode incluir dados binários na entrada de log, conhecida como dados de despejo. O Visualizador de Eventos exibe os dados de despejo na caixa de texto Dados da folha de propriedades da entrada de log.
Você pode abrir a folha de propriedades de uma entrada de log clicando duas vezes na entrada no Visualizador de Eventos. A captura de tela a seguir mostra uma folha de propriedades de entrada de log de exemplo.
Os drivers usam a rotina IoAllocateErrorLogEntry para alocar uma entrada de log de erros. As entradas de log consistem em um cabeçalho IO_ERROR_LOG_PACKET de comprimento variável, seguido por cadeias de caracteres de inserção.
O diagrama a seguir mostra o layout de uma entrada de log de erros na memória.
O membro ErrorCode do IO_ERROR_LOG_PACKET especifica o valor NTSTATUS do erro. O membro DumpData especifica todos os dados de despejo para a entrada de log. DumpData é uma matriz de tamanho variável, cujo tamanho é especificado pelo membro DumpDataSize . Os drivers especificam o início da primeira cadeia de caracteres de inserção com o membro StringOffset e o número de cadeias de caracteres no membro NumberOfStrings . Cada cadeia de caracteres de inserção em si é uma cadeia de caracteres Unicode terminada em nulo.
Depois que o driver preenche a entrada de log de erros alocada, ele grava a entrada no log de erros usando IoWriteErrorLogEntry. IoWriteErrorLogEntry libera automaticamente a memória alocada para a entrada de log. Os drivers podem usar IoFreeErrorLogEntry para liberar todas as entradas de log não utilizadas.
Códigos de erro predefinidos (do formulário IO_ERR_XXX) são definidos no arquivo de cabeçalho ntiologc.h incluído no WDK (Kit de Driver do Windows). A mensagem de erro associada a cada código de erro pode ser encontrada nos comentários de ntiologc.h, ao lado da declaração do código de erro. Para usar um código de erro predefinido, o driver deve registrar o arquivo do sistema, iologmsg.dll, como a origem das mensagens de erro associadas. Para obter mais informações, consulte Registrando-se como uma fonte de mensagens de erro.
Os drivers também podem definir seus próprios tipos de erro personalizados e mensagens de erro associadas. Para obter mais informações, consulte Definindo tipos de erro personalizados.