Usar valores NTSTATUS

Importante

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

Muitas rotinas de driver padrão do 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 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 de retorno 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):

Macro	Descrição
NT_SUCCESS (Status)	Avalia como TRUE se o valor retornado especificado por Status for um tipo de sucesso (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)	Avalia como TRUE se o valor retornado especificado por Status for um tipo de aviso (0x80000000 − 0xBFFFFFFF).
NT_ERROR(Status)	Avalia 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 de 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 que não há erros, 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 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, as informações solicitadas, o driver de nível inferior poderá responder fornecendo o máximo de dados possível e, em seguida, retornando STATUS_BUFFER_OVERFLOW, que é um código de aviso. 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.