Utilisation de valeurs NTSTATUS

Notes

Si vous recherchez une table de mappages de valeurs NTSTATUS avec les codes d’erreur Win32 correspondants, consultez Mappages de codes d’erreur NTSTATUS vers 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 de type NTSTATUS dans la structure de IO_STATUS_BLOCK d’un IRP lors de l’exécution des IRP. Le type NTSTATUS est défini dans Ntdef.h, et les codes status fournis par le système sont définis dans Ntstatus.h. (Les fournisseurs peuvent également définir des codes de status privés, même s’ils en ont rarement besoin. Pour plus d’informations, consultez Définition de nouvelles valeurs NTSTATUS.)

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

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

Lorsque vous testez 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(Status)
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 n’indique aucune erreur, ou si elle retourne le status STATUS_OBJECT_NAME_EXISTS informationnel, ce qui indique que l’interface de l’appareil 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 retournée STATUS_INVALID_PARAMETER, qui est un code d’erreur, ou parce que la routine retournée STATUS_NO_MORE_ENTRIES, qui est un code d’avertissement.

Comme dernier exemple, supposons qu’un pilote envoie un IRP qui provoque la lecture des informations 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 une partie, mais pas la totalité, des informations demandées, 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 status en utilisant NT_SUCCESS ou NT_ERROR incorrectement, il peut supprimer par inadvertance certaines des informations reçues.