Utilisation de valeurs NTSTATUS

Notes

Si vous recherchez une table des mappages de valeurs NTSTATUS aux codes d’erreur Win32 correspondants, consultez mappages de code d’erreur NTSTATUS à Win32.

De nombreuses routines de pilotes standard en mode noyau et les routines de prise en charge des pilotes utilisent le type NTSTATUS pour les valeurs de retour. En outre, les pilotes fournissent une valeur typée NTSTATUS dans la structure de IO_STATUS_BLOCK d’un IRP lors de la fin des ADRESSES IP. Le type NTSTATUS est défini dans Ntdef.h et les codes d’état fournis par le système sont définis dans Ntstatus.h. (Les fournisseurs peuvent également définir des codes d’état privés, bien qu’ils aient rarement besoin. Pour plus d’informations, consultez Définition de nouvelles valeurs NTSTATUS.)

Les valeurs NTSTATUS sont divisées en quatre types : valeurs de réussite, valeurs d’information, avertissements et valeurs d’erreur.

De nombreuses valeurs sont affectées à chaque type. Une erreur courante, lors du test d’un retour réussi à partir d’une routine, consiste à comparer la valeur de retour de la routine avec STATUS_SUCCESS. Cette comparaison recherche une seule des valeurs de réussite.

Lors du test d’une valeur de retour, vous devez utiliser l’une des macros fournies par le système suivantes (définies dans Ntdef.h) :

NT_SUCCESS(État)
Prend la valeur TRUE si la valeur de retour spécifiée par Status est un type de réussite (0 − 0x3FFFFFFF) ou un type d’information (0x40000000 − 0x7FFFFFFF).

NT_INFORMATION(État)
Prend la valeur TRUE si la valeur de retour spécifiée par Status est un type d’information (0x40000000 − 0x7FFFFFFF).

NT_WARNING(État)
Prend la valeur TRUE si la valeur de retour spécifiée par Status est un type d’avertissement (0x80000000 − 0xBFFFFFFF).

NT_ERROR(État)
Prend la valeur TRUE si la valeur de retour spécifiée par Status est un type d’erreur (0xC0000000 - 0xFFFFFFFF).

Par exemple, supposons qu’un pilote appelle IoRegisterDeviceInterface pour inscrire une interface d’appareil. Si le pilote vérifie la valeur de retour à l’aide de la macro NT_SUCCESS, la macro prend la valeur TRUE si la routine retourne STATUS_SUCCESS, ce qui indique aucune erreur ou si elle retourne l’état d’information STATUS_OBJECT_NAME_EXISTS, ce qui indique que l’interface de périphérique est déjà inscrite.

Dans un autre exemple, supposons qu’un pilote appelle ZwEnumerateKey pour énumérer les sous-clés d’une clé de Registre spécifiée. Si la macro NT_SUCCESS prend la valeur FALSE, cela peut être dû au fait que la routine a retourné STATUS_INVALID_PARAMETER, qui est un code d’erreur, ou parce que la routine a retourné STATUS_NO_MORE_ENTRIES, qui est un code d’avertissement.

En guise de dernier exemple, supposons qu’un pilote envoie un IRP qui provoque la lecture d’informations à partir d’un appareil par un pilote de niveau inférieur. Si le pilote demandeur spécifie une mémoire tampon trop petite pour recevoir des informations, le pilote de niveau inférieur peut répondre en retournant STATUS_BUFFER_TOO_SMALL, qui est un code d’erreur. Si le premier pilote spécifie une mémoire tampon qui peut recevoir certaines informations demandées, mais pas toutes, le pilote de niveau inférieur peut répondre en fournissant autant de données que possible, puis en retournant STATUS_BUFFER_OVERFLOW, qui est un code d’avertissement. Notez que si le premier pilote teste la valeur d’état à l’aide de NT_SUCCESS ou de NT_ERROR incorrectement, il peut supprimer par inadvertance certaines des informations reçues.