estrutura IO_ERROR_LOG_PACKET (wdm.h)

Artigo
08/08/2023

A estrutura IO_ERROR_LOG_PACKET serve como o cabeçalho para uma entrada de log de erros.

Sintaxe

typedef struct _IO_ERROR_LOG_PACKET {
  UCHAR         MajorFunctionCode;
  UCHAR         RetryCount;
  USHORT        DumpDataSize;
  USHORT        NumberOfStrings;
  USHORT        StringOffset;
  USHORT        EventCategory;
  NTSTATUS      ErrorCode;
  ULONG         UniqueErrorValue;
  NTSTATUS      FinalStatus;
  ULONG         SequenceNumber;
  ULONG         IoControlCode;
  LARGE_INTEGER DeviceOffset;
  ULONG         DumpData[1];
} IO_ERROR_LOG_PACKET, *PIO_ERROR_LOG_PACKET;

Membros

MajorFunctionCode

Indica o código de função principal IRP_MJ_XXX do IRP que o driver estava tratando quando o erro ocorreu. Definir esse valor é opcional.

RetryCount

Indica o número de vezes que o driver repetiu a operação e encontrou esse erro. Use zero para indicar que o driver tentou a operação uma vez ou adicione um para cada repetição além da tentativa inicial.

DumpDataSize

Indica o tamanho, em bytes, do membro DumpData de comprimento variável dessa estrutura. O valor especificado deve ser um múltiplo de sizeof(ULONG).

NumberOfStrings

Indica o número de cadeias de caracteres de inserção que o driver fornecerá com essa entrada de log de erros. Os drivers definem esse valor como zero para erros que não precisam de cadeias de caracteres de inserção. O Visualizador de Eventos usa essas cadeias de caracteres para preencher as entradas "%2" por meio de "%n" no modelo de cadeia de caracteres para esse código de erro.

As próprias cadeias de caracteres Unicode terminadas em nulo seguem a estrutura IO_ERROR_LOG_PACKET na memória.

StringOffset

Indica o deslocamento, em bytes, desde o início da estrutura, em que os dados de cadeia de caracteres de inserção fornecidos pelo driver começam. Normalmente, isso será sizeof(IO_ERROR_LOG_PACKET) mais o valor do membro DumpDataSize . Se não houver cadeias de caracteres de inserção fornecidas pelo driver, StringOffset poderá ser zero.

EventCategory

Especifica a categoria de evento para o erro. Um driver especifica as categorias de evento compatíveis e as cadeias de caracteres descritivas correspondentes em seu catálogo de mensagens. O Visualizador de Eventos exibe a cadeia de caracteres descritiva como o valor category do erro.

ErrorCode

Especifica o tipo de erro. O Visualizador de Eventos usa o código de erro para determinar qual cadeia de caracteres exibir como o valor Descrição do erro. O Visualizador de Eventos usa o modelo de cadeia de caracteres para o erro fornecido no catálogo de mensagens do driver, substitui "%1" no modelo pelo nome do objeto de dispositivo do driver e substitui "%2" por "%n" pelas cadeias de caracteres de inserção fornecidas com a entrada de log de erros.

ErrorCode é uma constante definida pelo sistema ou definida pelo driver; consulte Erros de registro em log para obter mais informações.

UniqueErrorValue

Um valor específico do driver que indica onde o erro foi detectado no driver. Definir esse valor é opcional.

FinalStatus

Especifica o valor NTSTATUS a ser retornado para a operação que disparou o erro. Definir esse valor é opcional.

SequenceNumber

Especifica um número de sequência atribuído pelo driver para o IRP atual, que deve ser constante durante a vida útil de uma determinada solicitação. Definir esse valor é opcional.

IoControlCode

Para um IRP IRP_MJ_DEVICE_CONTROL ou IRP_MJ_INTERNAL_DEVICE_CONTROL , esse membro especifica o código de controle de E/S para a solicitação que corrigiu o erro. Caso contrário, esse valor será zero. Definir esse valor é opcional.

DeviceOffset

Especifica o deslocamento especificado pelo driver para o dispositivo em que o erro ocorreu. Definir esse valor é opcional.

DumpData[1]

Uma matriz de tamanho variável que pode ser usada para armazenar dados binários específicos do driver, como valores de registro ou qualquer outra informação útil para identificar a causa do erro. Os drivers devem especificar o tamanho, em bytes, da matriz no membro DumpDataSize dessa estrutura.

Comentários

Os drivers usam a rotina IoAllocateErrorLogEntry para alocar uma entrada de log de erros. A estrutura IO_ERROR_LOG_PACKET serve como o cabeçalho para o buffer retornado. Ele é seguido na memória por qualquer cadeia de caracteres de inserção para a entrada de log.

Observe que o próprio gerenciador de E/S insere algumas informações no log de erros do sistema, como o nome do dispositivo e do driver. O gerente de E/S reserva 80 bytes para armazenar essas informações. Se o tamanho dessas informações exceder 80 bytes, o gerenciador de E/S truncará as cadeias de caracteres de inserção do driver conforme necessário.

Para obter mais informações sobre como usar essa estrutura, consulte Erros de log.