Usando valores NTSTATUS

Observação

Se você estiver procurando uma tabela de mapeamentos de valores NTSTATUS para os códigos de erro do Win32 correspondentes, consulte mapeamentos de código de erro NTSTATUS para Win32.

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 NTSTATUS são divididos em quatro tipos: valores de sucesso, 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 sucesso.

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

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

NT_INFORMATION(Status)
Avalia como TRUE se o valor retornado especificado pelo Status for um tipo informativo (0x40000000 – 0x7FFFFFFF).

NT_WARNING(Status)
Avalia como TRUE se o valor retornado especificado pelo Status for um tipo de aviso (0x80000000 – 0xBFFFFFFF).

NT_ERROR(Status)
Avalia como TRUE se o valor retornado especificado pelo 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 indica nenhum erro ou se retornar o status informativo STATUS_OBJECT_NAME_EXISTS, o 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 retornada STATUS_INVALID_PARAMETER, que é um código de erro ou porque a rotina retornada 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 de status usando NT_SUCCESS ou NT_ERROR incorretamente, ele poderá descartar inadvertidamente algumas das informações recebidas.