Usar valores NTSTATUS

Importante

Si busca una tabla de asignaciones de valores NTSTATUS a los códigos de error de Win32 correspondientes, vea NTSTATUS to Win32 Error Code Mappings (Asignaciones de código de error de NT32 a Win32).

Muchas rutinas de controlador estándar en modo kernel y rutinas de compatibilidad de controladores usan el tipo NTSTATUS para los valores devueltos. Además, los controladores proporcionan un valor con tipo NTSTATUS en la estructura de IO_STATUS_BLOCK de IRP al completar irP. El tipo NTSTATUS se define en Ntdef.h y los códigos de estado proporcionados por el sistema se definen en Ntstatus.h. (Los proveedores también pueden definir códigos de estado privados, aunque rara vez necesitan. Para obtener más información, vea Definir nuevos valores NTSTATUS).

Los valores NTSTATUS se dividen en cuatro tipos: valores correctos, valores informativos, advertencias y valores de error.

Se asignan numerosos valores a cada tipo. Un error común, al probar una devolución correcta de una rutina, es comparar el valor devuelto de la rutina con STATUS_SUCCESS. Esta comparación comprueba solo uno de los valores correctos.

Al probar un valor devuelto, debe usar una de las siguientes macros proporcionadas por el sistema (definidas en Ntdef.h):

Macro	Descripción
NT_SUCCESS(Status)	Se evalúa como TRUE si el valor devuelto especificado por Status es un tipo correcto (0 – 0x3FFFFFFF) o un tipo informativo (0x40000000 – 0x7FFFFFFF).
NT_INFORMATION(Status)	Se evalúa como TRUE si el valor devuelto especificado por Status es un tipo informativo (0x40000000 – 0x7FFFFFFF).
NT_WARNING(Status)	Se evalúa como TRUE si el valor devuelto especificado por Status es un tipo de advertencia (0x80000000 − 0xBFFFFFFF).
NT_ERROR(Estado)	Se evalúa como TRUE si el valor devuelto especificado por Status es un tipo de error (0xC0000000 - 0xFFFFFFFF).

Por ejemplo, supongamos que un controlador llama a IoRegisterDeviceInterface para registrar una interfaz de dispositivo. Si el controlador comprueba el valor devuelto mediante la macro NT_SUCCESS, la macro se evalúa como TRUE si la rutina devuelve STATUS_SUCCESS, que indica que no hay errores o si devuelve el estado informativo STATUS_OBJECT_NAME_EXISTS, lo que indica que la interfaz del dispositivo ya está registrada.

Como otro ejemplo, supongamos que un controlador llama a ZwEnumerateKey para enumerar las subclaves de una clave del Registro especificada. Si la macro NT_SUCCESS se evalúa como FALSE, puede deberse a que la rutina devuelta STATUS_INVALID_PARAMETER, que es un código de error o porque la rutina devolvió STATUS_NO_MORE_ENTRIES, que es un código de advertencia.

Como ejemplo final, supongamos que un controlador envía un IRP que hace que un controlador de nivel inferior lea información de un dispositivo. Si el controlador solicitante especifica un búfer demasiado pequeño para recibir información, el controlador de nivel inferior puede responder devolviendo STATUS_BUFFER_TOO_SMALL, que es un código de error. Si el primer controlador especifica un búfer que puede recibir algunos, pero no todos, de la información solicitada, el controlador de nivel inferior puede responder proporcionando tantos datos como sea posible y, a continuación, devolviendo STATUS_BUFFER_OVERFLOW, que es un código de advertencia. Si el primer controlador prueba el valor de estado mediante NT_SUCCESS o NT_ERROR incorrectamente, podría quitar accidentalmente parte de la información recibida.