HRESULT

Un article de Wikipédia, l'encyclopédie libre.
Si ce bandeau n'est plus pertinent, retirez-le. Cliquez ici pour en savoir plus.
Si ce bandeau n'est plus pertinent, retirez-le. Cliquez ici pour en savoir plus.

Cet article ne s'appuie pas, ou pas assez, sur des sources secondaires ou tertiaires ().

Pour améliorer la vérifiabilité de l'article ainsi que son intérêt encyclopédique, il est nécessaire, quand des sources primaires sont citées, de les associer à des analyses faites par des sources secondaires.

Si ce bandeau n'est plus pertinent, retirez-le. Cliquez ici pour en savoir plus.
Si ce bandeau n'est plus pertinent, retirez-le. Cliquez ici pour en savoir plus.

Cet article est orphelin. Moins de trois articles lui sont liés ().

Vous pouvez aider en ajoutant des liens vers [[HRESULT]] dans les articles relatifs au sujet.

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[modifier | modifier le code]

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] :

Bit 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
Champ S R C N X Etablissement Code

Détail du format[modifier | modifier le code]

  • 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 [2]).
    • 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[modifier | modifier le code]

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.

Utilisation des HRESULTs[modifier | modifier le code]

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ères 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.

Exemples[modifier | modifier le code]

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

Notes et références[modifier | modifier le code]

  1. ↑ « Structure of COM Error Codes »
  2. ↑ a et b MSDN Windows référence des codes d'Erreur.
  3. ↑ descripteur de résultat opaque
  4. ↑ ERR.EXE
  5. ↑ ERRLOOK.EXE
  6. ↑ FormatMessage
  7. ↑ [1] Codes d'erreur Win32

Liens externes[modifier | modifier le code]

Ce document provient de « https://fr.wikipedia.org/w/index.php?title=HRESULT&oldid=209696706 ».