HRESULT

HRESULT es un tipo de dato de programación informática que representa el estado de finalización de una función .

Se utiliza en el código fuente de aplicaciones dirigidas a Microsoft Windows y a sistemas operativos anteriores de IBM/Microsoft OS/2 , pero su diseño no limita su uso a estos entornos; puede utilizarse en cualquier sistema que admita enteros de 32 bits .

El propósito original de HRESULT era establecer rangos de códigos de estado tanto para uso público como interno de Microsoft, con el fin de evitar colisiones entre códigos de estado en diferentes subsistemas del sistema operativo OS/2.

Un HRESULT está diseñado para ser simultáneamente un valor numérico simple y una estructura de campos que indican la gravedad, la instalación y el código de estado.

El uso de HRESULT es más común en la programación COM , donde constituye la base de un mecanismo estandarizado de manejo de errores , pero su uso no se limita a COM. Por ejemplo, puede utilizarse como alternativa al uso más tradicional de un resultado booleano de aprobado/reprobado.

HRESULT se define en un archivo de encabezado del sistema como un entero con signo de 32 bits ^{[ 1 ]} y a menudo se trata de forma opaca como un entero, especialmente en el código que consume una función que devuelve HRESULT. Un valor HRESULT consta de los siguientes elementos separados:

• Gravedad: indica si la función tuvo éxito o fracasó.
• Instalación: identifica la parte del sistema a la que se aplica el estado.
• Código: identifica una condición particular en el contexto de la instalación.

Un valor HRESULT es una estructura con los siguientes campos de bits : ^{[ 2 ]}

• S - Gravedad; indica éxito (0) o fracaso (1)
• R - Reservado; corresponde al segundo bit de gravedad de NTSTATUS (1 - Fallo grave)
• C - Cliente; especifica si el valor está definido por Microsoft (0) o definido por el cliente (1).
• N - Reservado; se utiliza para indicar un valor NTSTATUS que se ha asignado a un HRESULT.
• X - Reservado para uso interno; se utiliza para indicar un valor que no es un estado, sino un identificador de mensaje para cadenas de visualización.
• Instalación: indica el servicio del sistema responsable del estado. Ejemplos:
  • 1 - RPC
  • 2 - Despacho (despacho COM)
  • 3 - Almacenamiento (almacenamiento OLE)
  • 4 - ITF (Gestión de la interfaz COM/OLE)
  • 7 - Win32 (códigos de error Win32 sin procesar)
  • 8 - Windows
  • 9 - SSPI
  • 10 - Control
  • 11 - CERT (Certificado de cliente o de servidor)
  • ...
• Código: el código de estado de la instalación.

En ocasiones, un valor HRESULT se muestra como un valor hexadecimal de 8 dígitos.

Ejemplos: ^{[ 3 ]}

• 0x80070005
  • SRCNX<Facility-><Code---------->, significados de campos de bits
  • 10000000000001110000000000000101, 0x80070005, HRESULT como binario y HRESULT como hexadecimal
  • 1..............................., 0x1, S, Gravedad, fallo (1)
  • .0.............................., 0x0, R, Reservado
  • ..0............................., 0x0, C, Cliente, definido por Microsoft (0)
  • ...0............................, 0x0, N, Reservado
  • ....0..........................., 0x0, X,
  • .....00000000111................, 0x7Instalación: win32
  • ................0000000000000101, 0x5, Código: E_FAULT

• 0x80090032
  • 0x8- Estado: Fallo
  • 0x9- Instalación: SSPI
  • 0x32- Código: La solicitud no es compatible

En ocasiones, un valor HRESULT se muestra como un número entero con signo, pero esto es menos común y más difícil de leer.

Un HRESULT a veces se representa como un identificador con el formato Facility_Severity_Moason : ^{[ 4 ]}

• Instalación es el nombre de la instalación o algún otro identificador distintivo.
• La gravedad se indica con una sola letra: S para éxito o E para error (fallo).
• La razón describe el significado del código.

Por ejemplo, STG_E_FILENOTFOUND indica un error relacionado con el almacenamiento; el archivo no existe.

La parte de la instalación se omite si la instalación es 0 (FACILITY_NULL) o para algunos valores muy comunes. Por ejemplo: S_OK, E_FAIL, E_INVALIDARG.

Esta representación es más fácil de leer que un formato numérico, pero es menos precisa, ya que, aunque se basa en la convención, no existe un algoritmo definitivo para convertir entre valor y nombre.

El código HRESULT se definió originalmente en el sistema operativo IBM/Microsoft OS/2 como un código de retorno de error de propósito general, y posteriormente se adoptó en Windows NT.

Microsoft Visual Basic mejoró sustancialmente los mecanismos de notificación de errores HRESULT al asociar un objeto IErrorInfo con un HRESULT y almacenar (un puntero a) dicho objeto en el almacenamiento local del hilo . El mecanismo IErrorInfo permite a los programas asociar una amplia variedad de información con un error HRESULT específico: la clase del objeto que generó el error, la interfaz de dicho objeto, el texto del error y un enlace a un tema de ayuda en un archivo de ayuda. Además, quienes reciben un error HRESULT pueden obtener el texto del mensaje de error en formato localizado cuando lo soliciten.

Posteriormente, HRESULT y el IErrorInfomecanismo asociado se utilizaron como mecanismo predeterminado de notificación de errores en COM.

La compatibilidad con el mecanismo IErrorInfo en Windows es muy inconsistente. Las API antiguas de Windows tienden a no admitirlo en absoluto, devolviendo HRESULT sin IErrorInfodatos. Los subsistemas COM más modernos de Windows suelen proporcionar información de error detallada en la descripción del mensaje del objeto IErrorInfo. Las funciones más avanzadas de los mecanismos de error IErrorInfo, como los enlaces de ayuda y la localización bajo demanda, se utilizan con poca frecuencia.

En .NET Framework , los códigos de error HRESULT/IErrorInfo se traducen en excepciones CLR al pasar de código nativo a código administrado , y las excepciones CLR se traducen en códigos de error HRESULT/IErrorInfo al pasar de código COM administrado a código COM nativo .

Dado que HRESULT se define como un entero con signo y que el campo de gravedad es el bit más significativo , un valor negativo indica fallo y otros valores indican éxito. El código de éxito más utilizado es S_OKque tiene valor 0. Sin embargo, en raras ocasiones, una función devuelve un código de éxito con información adicional como S_FALSEque tiene valor 1.

Cuando un valor HRESULT se muestra en formato hexadecimal (generalmente para depuración ), un desarrollador puede identificar un valor como indicativo de fallo si comienza con el dígito 8 o superior en la octava posición, la más significativa. Tenga en cuenta que, si no se rellena con ceros a la izquierda hasta completar los 8 dígitos, un valor podría interpretarse erróneamente como un fallo. Por ejemplo, 80005 indica éxito aunque comience con 8. Si se rellena hasta completar los 8 dígitos, esto queda claro: 00080005. Esto resulta algo artificial, ya que normalmente el éxito se representa con 0, que es claramente un código de éxito.

Las formas programáticas de comprobar el estado de fallo son realizar una prueba de resultado negativo o utilizar una macro definida por el sistema. ^{[ 5 ]}

HRESULT hr = func(...); if (hr < 0) ; // falló if (hr >= 0) ; // éxito if (FAILED(hr)) ; // falló if (SUCEEDED(hr)) ; // éxito

Las pruebas para 0, como (hr)o , (!hr)funcionarán la mayoría de las veces, pero son incorrectas para los códigos de éxito que se usan con poca frecuencia, distintos de , S_OKcomo S_FALSE.

Para obtener la parte del código de un HRESULT, utilice la HRESULT_CODE()macro.

Utilice la herramienta ERR.EXE para traducir un valor al texto del mensaje correspondiente.

La herramienta ERRLOOK.EXE permite visualizar las cadenas de error asociadas a un valor HRESULT determinado. Se puede ejecutar desde la línea de comandos de Visual Studio .

El sistema win32 SetErrorInfoasocia un valor HRESULT con el IErrorInfoobjeto correspondiente. GetErrorInfoLee esta información.

El formato Win32 FormatMessage se puede utilizar para obtener una descripción legible para humanos de algunos valores HRESULT que no son IErrorInfo.

El winerror.harchivo de encabezado define algunos valores HRESULT de uso común. Estos valores a veces se codifican en los archivos de encabezado (.h) de un subsistema. También se definen en los archivos de encabezado correspondientes del SDK o DDK de Microsoft Windows Platforms.

El nombre HRESULT parece significar "identificador de resultado", ya que muchos otros tipos de Windows usan la letra H para referirse a un identificador. Por ejemplo, HMODULE es un identificador de módulo, lo que significa que un valor HMODULE se refiere a un recurso de módulo. Sin embargo, un valor HRESULT no se refiere a un recurso, por lo que no es un identificador. Según Raymond Chen, "en el pasado, realmente era un identificador de un objeto que contenía información detallada sobre errores... El equipo de COM decidió que la relación costo-beneficio simplemente no valía la pena, por lo que HRESULT se convirtió en un simple número. Pero el nombre se mantuvo". ^{[ 6 ]}