Structure des codes d’erreur COM

  • Article

L’illustration suivante montre le format d’un HRESULT (ou SCODE) ; Les nombres indiquent des positions de bits :

Affiche le format d’un ' H RESULT' ou 'S CODE' avec des nombres indiquant des positions de bits.

Le bit d’ordre élevé dans HRESULT ou SCODE indique si la valeur de retour représente la réussite ou l’échec. Si elle est définie sur 0, SEVERITY_SUCCESS, la valeur indique la réussite. Si la valeur est 1, SEVERITY_ERROR, elle indique un échec.

Les bits R, C, N et r sont réservés.

Le champ d’installation indique le service système responsable de l’erreur. Microsoft alloue de nouveaux codes d’installation dès qu’ils deviennent nécessaires. La plupart des valeurs SCODEs et HRESULT définissent le champ d’installation sur FACILITY_ITF, indiquant une erreur de méthode d’interface.

Les champs d’installation courants sont décrits dans le tableau suivant.

Champ d’installation Valeur Description
FACILITY_DISPATCH
 2
 Pour les erreurs d’interface IDispatch de liaison tardive.
FACILITY_ITF
 4
 Pour la plupart des status codes retournés par les méthodes d’interface. La signification réelle de l’erreur est définie par l’interface. Autrement dit, deux HRESULTavec exactement la même valeur 32 bits retournée par deux interfaces différentes peuvent avoir des significations différentes.
FACILITY_NULL
 0
 Pour les codes de status courants, tels que S_OK.
FACILITY_RPC
 1
 Pour status codes retournés à partir d’appels de procédure distante.
FACILITY_STORAGE
 3
 Par status codes retournés par les appels de méthode IStorage ou IStream relatifs au stockage structuré. Les codes d’état dont la valeur de code (16 bits inférieurs) se trouve dans la plage des codes d’erreur MS-DOS (c’est-à-dire inférieur à 256) ont la même signification que l’erreur MS-DOS correspondante.
FACILITY_WIN32
 7
 Utilisé pour fournir un moyen de gérer les codes d’erreur à partir de fonctions dans l’API Windows en tant que HRESULT. Dans OLE 16 bits, les codes d’erreur système en double ont également été modifiés en FACILITY_WIN32.
FACILITY_WINDOWS
 8
 Utilisé pour les codes d’erreur supplémentaires à partir d’interfaces définies par Microsoft.

Le champ de code est un nombre unique qui est affecté pour représenter l’erreur ou l’avertissement.

Par convention, les valeurs HRESULT ont généralement des noms au format suivant : Facility_Severity_Reason.

L’installation est soit le nom de l’installation, soit un autre identificateur distinctif; La gravité est une lettre unique, S ou E, qui indique si l’appel de fonction a réussi (S) ou produit une erreur (E) ; et Reason est un identificateur qui décrit la signification du code. Par exemple, le code status STG_E_FILENOTFOUND indique qu’une erreur liée au stockage s’est produite ; en particulier, aucun fichier demandé n’existe. Les codes d’état de FACILITY_NULL omettent le préfixe Facility_.

Les codes d’erreur sont définis dans le contexte d’une implémentation d’interface. Une fois définis, les codes de réussite ne peuvent pas être modifiés ou de nouveaux codes de réussite ajoutés. Toutefois, de nouveaux codes d’échec peuvent être écrits. Microsoft se réserve le droit de définir de nouveaux codes d’échec (mais pas des codes de réussite) pour les interfaces décrites dans FACILITY_ITF ou dans de nouvelles installations.

Gestion des erreurs dans COM

Protocoles Windows : HRESULT