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[1].

Les HRESULTs sont organisés comme suit[2] :

Un HRESULT est un descripteur de résultat opaque[3] 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.

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[4] pour prendre la valeur et la convertir en chaîne de caractère correspondante à l'erreur. Un autre outil appelé ERRLOOK.EXE[5] 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[6] peut être utilisée pour convertir des HRESULTs sans IErrorInfo en une chaîne de caractères lisible par un utilisateur.

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

• 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