Utiliser les valeurs NTSTATUS
Important
Si vous recherchez une table de mappages de valeurs NTSTATUS aux codes d’erreur Win32 correspondants, consultez NTSTATUS to Win32 Error Code Mappings.
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 IO_STATUS_BLOCK d’un IRP lors de l’achèvement des IRPS. 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, même s’ils ont 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 d’une routine, consiste à comparer la valeur de retour de la routine avec STATUS_SUCCESS. Cette comparaison vérifie uniquement l’une 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) :
| Macro | Description |
|---|---|
| NT_SUCCESS(Status) | 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(Status) | 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 qu’aucune erreur n’est détectée ou si elle retourne l’état d’information STATUS_OBJECT_NAME_EXISTS, ce qui indique que l’interface de l’appareil est déjà inscrite.
Comme 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 a retourné STATUS_NO_MORE_ENTRIES, qui est un code d’avertissement.
Dans un dernier exemple, supposons qu’un pilote envoie un IRP qui provoque la lecture d’informations d’un pilote de niveau inférieur à partir d’un appareil. 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, mais pas toutes, 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. 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.