Usando valores NTSTATUS

Muitas rotinas de driver padrão no modo kernel e rotinas de suporte ao driver usam o tipo NTSTATUS para valores retornados. Além disso, os drivers fornecem um valor do tipo NTSTATUS na estrutura de IO_STATUS_BLOCK de um IRP ao concluir IRPs. O tipo NTSTATUS é definido em Ntdef.h e os códigos de status fornecidos pelo sistema são definidos em Ntstatus.h. (Os fornecedores também podem definir códigos de status privados, embora raramente precisem. Para obter mais informações, consulte Definindo novos valores NTSTATUS.)

Os valores de NTSTATUS são divididos em quatro tipos: valores de êxito, valores informativos, avisos e valores de erro.

Vários valores são atribuídos a cada tipo. Um erro comum, ao testar um retorno bem-sucedido de uma rotina, é comparar o valor retornado da rotina com STATUS_SUCCESS. Essa comparação verifica apenas um dos vários valores de êxito.

Ao testar um valor retornado, você deve usar uma das seguintes macros fornecidas pelo sistema (definidas em Ntdef.h):

NT_SUCCESS(Status)
Avaliará como TRUE se o valor retornado especificado por Status for um tipo de êxito (0 – 0x3FFFFFFF) ou um tipo informativo (0x40000000 − 0x7FFFFFFF).

NT_INFORMATION(Status)
Será avaliado como TRUE se o valor retornado especificado por Status for um tipo informativo (0x40000000 − 0x7FFFFFFF).

NT_WARNING(Status)
Avaliará como TRUE se o valor retornado especificado por Status for um tipo de aviso (0x80000000 − 0xBFFFFFFF).

NT_ERROR(Status)
Avaliará como TRUE se o valor retornado especificado por Status for um tipo de erro (0xC0000000 - 0xFFFFFFFF).

Por exemplo, suponha que um driver chame IoRegisterDeviceInterface para registrar uma interface do dispositivo. Se o driver verificar o valor retornado usando a macro NT_SUCCESS, a macro será avaliada como TRUE se a rotina retornar STATUS_SUCCESS, o que não indica erros ou se retornar o status STATUS_OBJECT_NAME_EXISTS informativo, que indica que a interface do dispositivo já está registrada.

Como outro exemplo, suponha que um driver chame ZwEnumerateKey para enumerar as subchaves de uma chave do Registro especificada. Se a macro NT_SUCCESS for avaliada como FALSE, pode ser porque a rotina retornou STATUS_INVALID_PARAMETER, que é um código de erro ou porque a rotina retornou STATUS_NO_MORE_ENTRIES, que é um código de aviso.

Como exemplo final, suponha que um driver envie um IRP que faz com que um driver de nível inferior leia informações de um dispositivo. Se o driver solicitante especificar um buffer muito pequeno para receber qualquer informação, o driver de nível inferior poderá responder retornando STATUS_BUFFER_TOO_SMALL, que é um código de erro. Se o primeiro driver especificar um buffer que pode receber algumas, mas não todas, das informações solicitadas, o driver de nível inferior poderá responder fornecendo o máximo de dados possível e retornando STATUS_BUFFER_OVERFLOW, que é um código de aviso. Observe que, se o primeiro driver testar o valor status usando NT_SUCCESS ou NT_ERROR incorretamente, ele poderá inadvertidamente descartar algumas das informações recebidas.