HRESULT

Dans le domaine de la programmation informatique, le HRESULT est un type de données utilisé dans les systèmes d'exploitation Windows, ainsi que dans l'ancien système d'exploitation IBM/Microsoft OS/2, pour représenter des états d'erreur et d'avertissement.

Le but original des HRESULTs était de disposer de plages de codes d'erreur formellement définies, pour un usage public et interne à Microsoft, qui permette d'éviter les collisions entre codes d'erreur dans les différents sous-systèmes du système d'exploitation OS/2.

Les HRESULTs sont des codes d'erreur numériques. Les différents bits dans un HRESULT encodent des informations concernant la nature du code d'erreur, ainsi que sa provenance.

Les codes d'erreur HRESULT sont les plus généralement rencontrés dans le domaine de la programmation COM, où ils forment la base pour une gestion normalisée des erreurs.

Le format HRESULT 
Une valeur HRESULT est composée de 32 bits divisée en trois domaines, le code de sévérité indique si la valeur de retour est une information, un avertissement ou une erreur. Le code d'établissement identifie la partie du système responsable de l'erreur. Le code d'erreur est un numéro unique qui est chargé de représenter l'exception. Chaque exception est associée à un HRESULT.

L'établissement est soit le nom de l'établissement soit un identifiant unique, la sévérité est composée d'une seule lettre, S ou E, qui indique si l'appel de la fonction a réussi (S) ou produit un message d'erreur (E), et la raison est un identificateur qui décrit la signification du code. Par exemple, le code de statut STG_E_FILENOTFOUND indique qu'une erreur liée au stockage s'est produite, plus précisément qu'un fichier demandé n'existe pas. Il convient de garder à l'esprit qu'une valeur HRESULT peut également être affichée sous la forme d'un entier non signé, au format hexadécimal.

Les HRESULTs sont organisés comme suit :

Détail du format 
 S - Sévérité - indique un succès ou un échec
 0 :Succès
 1 : Échec
 R - partie réservée du code d'établissement, correspond au second bit de sévérité NT.
 1 : Défaillance grave
 C - Client. Ce bit permet d'indiquer si la valeur est définie par un client, ou par Microsoft.
 0 : Défini par Microsoft
 1 : Défini par un client
 N - partie réservée du code d'établissement. Utilisé pour indiquer une valeur d'état NT liée.
 X - partie réservée du code d'établissement. Réservé pour un usage interne. Utilisé pour indiquer que la valeur HRESULT n'est pas une valeur d'état, mais un identifiant de message pour afficher du texte.
 Établissement - indique le service du système qui est responsable de l'erreur. Des exemples de codes d'établissement sont indiqués ci-dessous (pour la liste complète, voir ).
 1 - RPC
 2 - Dispatch (COM dispatch)
 3 - Stockage (OLE stockage)
 4 - ITF (Interface de gestion COM/OLE)
 7 - Win32 (codes d'erreurs Win32)
 8 - Windows
 9 - SSPI
 10 - Contrôle
 11 - CERT (Certificat client ou serveur)
 ...
 Code - est le code d'état de l'établissement

Comment fonctionnent les HRESULTs 
Un HRESULT est un descripteur de résultat opaque défini à zéro ou plus en cas de succès, et négatif pour un échec. En général, les fonctions renvoient le HRESULT S_OK (qui est égal à zéro) en cas de succès. Mais, dans de rares circonstances, les fonctions peuvent renvoyer des codes de réussite avec d'autres informations, par exemple S_FALSE=0x01.

Les HRESULTs sont généralement affichés en tant que valeur hexadécimale non signée, souvent préfixée par 0x. Dans ce cas, un nombre indiquant l'échec est reconnaissable car il commence par un symbole hexadécimal de 8 ou plus.

Les HRESULTs ont été initialement définis dans le système d'exploitation IBM/Microsoft OS/2 en tant que codes de retour génériques, et par la suite adopté dans Windows NT. Microsoft Visual Basic a considérablement amélioré les mécanismes d'erreurs HRESULT en y associant un objet IErrorInfo, en stockant un pointeur vers un object COM IErrorInfo dans la mémoire locale de thread. Le mécanisme IErrorInfo permet à des programmes d'associer un large éventail d'informations pour un HRESULT donné: la classe de l'objet qui a déclenché l'erreur, l'interface de l'objet qui a déclenché l'erreur, le texte de l'erreur; et un lien vers une rubrique d'aide dans un fichier d'aide. En outre, les récepteurs d'une erreur HRESULT peuvent obtenir la traduction du texte du message d'erreur sur demande.

Par la suite, HRESULT ainsi que son mécanisme IErrorInfoassocié ont été utilisés comme système de signalement d'erreur par défaut dans les composants COM.

Le support du mécanisme IErrorInfo dans Windows est très incohérent. Les anciennes API Windows ont tendance à ne pas le supporter du tout en retournant des HRESULTs sans IErrorInfo, tandis que les sous-systèmes COM les plus récents dans Windows fournissent souvent de nombreuses informations d'erreur dans la description du message de l'objet IErrorInfo. Les fonctionnalités plus avancées du mécanisme IErrorInfo — les liens de l'aide, et la demande de traduction — sont rarement utilisées.

Dans le Framework .NET, les codes d'erreur HRESULT/IErrorInfo sont convertis en exceptions CLR lors du passage du code natif au code managé; et les exceptions CLR sont converties en codes d'erreur HRESULT/IErrorInfo lors de la transition du code managé en code COM natif.

Utilisation des HRESULTs 
Le fichier winerror.h définit certaines valeurs HRESULT génériques. Les valeurs HRESULT codées en dur sont parfois encodées dans des fichiers d'en-tête (fichiers .h) pour un sous-système donné. Ces valeurs sont également définies dans les fichiers d'en-tête (.h) du SDK Microsoft Windows, ou du kit de développement de pilote.

Pour vérifier si un appel qui renvoie un HRESULT a réussi, assurez-vous que le champ S soit à 0 (un chiffre non-négatif) ou utilisez la macro FAILED(). Pour obtenir la partie Code d'un HRESULT, utilisez la macro HRESULT_CODE(). Vous pouvez également utiliser un outil appelé ERR.EXE pour prendre la valeur et la convertir en chaîne de caractère correspondante à l'erreur. Un autre outil appelé ERRLOOK.EXE peut également être utilisé pour afficher des chaînes d'erreur associés à une valeur HRESULT. ERRLOOK.EXE peut être exécuté à partir d'une invite de commande Visual Studio.

Les API natives de Windows SetErrorInfo et GetErrorInfo sont utilisées pour associer des codes de retour HRESULT à l'objet IErrorInfo correspondant.

La fonction FormatMessage peut être utilisée pour convertir des HRESULTs sans IErrorInfo en une chaîne de caractères lisible par un utilisateur.

Exemples 

 0x80070005
 0x8 - Échec
 0x7 - Win32
 0x5 - E_FAULT
 0x80090032
 0x8 - Échec
 0x9 - SSPI
 0x32 - La demande n'est pas prise en charge

Notes et références

Liens externes 

 Microsoft Open Protocol Specification - HRESULT Values
 Microsoft Developer Network Reference
 Windows Data Types
 Using Macros for Error Handling
 List of DOS, Windows and OS/2 error codes, comprend beaucoup de valeurs HRESULT communes

Programmation informatique