HRESULT
"오늘의AI위키"의 AI를 통해 더욱 풍부하고 폭넓은 지식 경험을 누리세요.
1. 개요
HRESULT는 32비트 부호 있는 정수로 정의된 오류 반환 코드이며, 주로 Microsoft Windows API와 COM(Component Object Model)에서 사용된다. HRESULT는 심각도, 기능, 코드로 구성된 비트 필드 구조를 가지며, 오류의 심각도와 발생한 시스템 구성 요소, 구체적인 오류 정보를 나타낸다. HRESULT는 16진수 또는 텍스트 형식으로 표현되며, IErrorInfo 인터페이스와 연결되어 오류에 대한 추가 정보를 제공한다. Visual Basic, .NET Framework 등에서 사용되며, 오류 코드 추출, 오류 메시지 변환을 위한 다양한 도구가 제공된다. HRESULT는 원래 IBM/Microsoft OS/2에서 유래되었으며, 윈도우 NT에 채택되었다.
더 읽어볼만한 페이지
| HRESULT |
|---|
2. 구조
HRESULT는 32비트 부호 있는 정수로 정의되며,[1] 함수 성공 여부(심각도), 관련 시스템 구성 요소(기능), 특정 조건(코드)을 나타내는 비트 필드 구조를 갖는다.[2]
| 비트 | 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 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 필드 | S | R | C | N | X | 기능 | 코드 | |||||||||||||||||||||||||
- S: 심각도 (성공 또는 실패)
- R: 예약됨
- C: 고객 (Microsoft 또는 고객 정의)
- N: 예약됨
- X: 예약됨
- 기능: 시스템 서비스
- 코드: 기능의 상태 코드
HRESULT는 8자리 16진수로 표현되기도 한다. 예를 들어 `0x80070005`는 실패(S=1), Win32 기능(기능=7), E\_FAULT 코드(코드=5)를, `0x80090032`는 실패(S=1), SSPI 기능(기능=9), 요청 미지원(코드=0x32)을 나타낸다.[3]
2. 1. 심각도 (Severity)
HRESULT의 최상위 비트(31번 비트)는 오류의 심각도를 나타내며, 0은 성공, 1은 실패를 의미한다.[2]2. 2. 기능 (Facility)
HRESULT에서 기능(Facility)은 심각도 비트 다음의 11비트(16~26번 비트)로 구성되며, 오류가 발생한 시스템 구성 요소를 나타낸다.[2] 예를 들어, 기능 코드가 1이면 RPC, 7이면 Win32, 9이면 SSPI를 나타낸다.다음은 기능 코드의 예시이다.
| 코드 | 설명 |
|---|---|
| 1 | RPC |
| 2 | 디스패치(COM 디스패치) |
| 3 | 저장소(OLE 저장소) |
| 4 | ITF(COM/OLE 인터페이스 관리) |
| 7 | Win32 (원시 Win32 오류 코드) |
| 8 | Windows |
| 9 | SSPI |
| 10 | 제어 |
| 11 | CERT(클라이언트 또는 서버 인증서) |
2. 3. 코드 (Code)
나머지 16비트(0~15번 비트)는 기능 내에서 발생한 특정 오류 코드를 나타낸다.[2]| 비트 | 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 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 필드 | S | R | C | N | X | 기능 | 코드 | |||||||||||||||||||||||||
2. 4. 비트 필드 구조
HRESULT는 시스템 헤더 파일에서 32비트 부호 있는 정수로 정의되어 있으며[1], HRESULT를 반환하는 함수를 사용하는 코드에서 정수로 취급되는 경우가 많다. HRESULT 값은 다음과 같은 비트 필드를 가진 구조체이다.[2]| 비트 | 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 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 필드 | S | R | C | N | X | 기능 | 코드 | |||||||||||||||||||||||||
- S - 심각도 - 성공(0) 또는 실패(1)를 나타낸다.
- R - 예약됨; NTSTATUS의 두 번째 심각도 비트에 해당한다(1 - 심각한 실패).
- C - 고객. 값이 Microsoft에서 정의한 값(0)인지 고객이 정의한 값(1)인지를 지정한다.
- N - 예약됨; HRESULT에 매핑된 NTSTATUS 값을 나타내는 데 사용된다.
- X - 내부 사용을 위해 예약됨; 상태가 아닌 표시 문자열의 메시지 ID를 나타내는 데 사용된다.
- 기능 - 상태를 담당하는 시스템 서비스를 나타낸다.
| 기능 코드 | 설명 |
|---|---|
| 1 | RPC |
| 2 | 디스패치(COM 디스패치) |
| 3 | 저장소(OLE 저장소) |
| 4 | ITF(COM/OLE 인터페이스 관리) |
| 7 | Win32 (원시 Win32 오류 코드) |
| 8 | Windows |
| 9 | SSPI |
| 10 | 제어 |
| 11 | CERT(클라이언트 또는 서버 인증서) |
| ... |
- 코드 - 기능의 상태 코드
3. 표현 방식
HRESULT는 숫자(10진수 또는 16진수) 또는 텍스트 형식으로 표현될 수 있다. HRESULT 값은 8자리 16진수나 부호 있는 정수로 표현될 수 있지만, 가독성을 위해 'Facility_Severity_Reason' 형태의 텍스트로 표현되기도 한다.[3][4]
3. 1. 숫자 표현
HRESULT 값은 때때로 8자리 16진수 값으로 표시된다.[3]예:
- `0x80070005`
| 10000000000001110000000000000101, 0x80070005 | HRESULT를 이진법 및 16진법으로 표현 |
| 1..............................., 0x1 | S, 심각도, 실패 (1) |
| .0.............................., 0x0 | R, 예약됨 |
| ..0............................., 0x0 | C, 고객, Microsoft에서 정의 (0) |
| ...0............................, 0x0 | N, 예약됨 |
| ....0..........................., 0x0 | X |
| .....00000000111................, 0x7 | 기능: win32 |
| ................0000000000000101, 0x5 | 코드: E_FAULT |
- `0x80090032`
| 0x8 | 상태: 실패 |
| 0x9 | 기능: SSPI |
| 0x32 | 코드: 요청이 지원되지 않음 |
때때로 HRESULT 값은 부호 있는 정수로 표시되지만, 이는 덜 일반적이며 읽기가 더 어렵다.
3. 2. 텍스트 표현
HRESULT는 'Facility_Severity_Reason' 형식의 식별자로 표현되는 경우가 있다.[4]- Facility는 시설 이름 또는 다른 구별 식별자이다.
- Severity는 성공을 의미하는 S 또는 오류(실패)를 의미하는 E, 단일 문자이다.
- Reason은 코드의 의미를 설명한다.
예를 들어, STG_E_FILENOTFOUND는 스토리지 관련 오류, 즉 파일이 존재하지 않음을 나타낸다.
Facility가 0(FACILITY_NULL)이거나 매우 일반적인 값인 경우 Facility 부분은 생략된다. 예를 들어 S_OK, E_FAIL, E_INVALIDARG와 같다.
이 표현은 숫자 형식보다 읽기 쉽지만, 값과 이름 간의 변환에 대한 확실한 알고리즘은 관례에 기반하고 있어 덜 정확하다.
4. IErrorInfo 인터페이스
마이크로소프트 비주얼 베이직은 HRESULT와 IErrorInfo 객체를 연결하고 (포인터) IErrorInfo 객체를 스레드 로컬 저장소에 저장함으로써 HRESULT 오류 보고 메커니즘을 실질적으로 향상시켰다. IErrorInfo 메커니즘을 통해 프로그램은 특정 HRESULT 오류에 오류를 발생시킨 객체의 클래스, 오류를 발생시킨 객체의 인터페이스, 오류 텍스트, 도움말 파일의 도움말 항목 링크 등 다양한 정보를 연결할 수 있다. 또한, HRESULT 오류를 수신한 측에서는 필요에 따라 오류 메시지에 대한 현지화된 텍스트를 얻을 수 있다.
4. 1. IErrorInfo의 역할
마이크로소프트 비주얼 베이직은 HRESULT와 IErrorInfo 객체를 연결하고 (포인터) IErrorInfo 객체를 스레드 로컬 저장소에 저장함으로써 HRESULT 오류 보고 메커니즘을 실질적으로 향상시켰다. IErrorInfo 메커니즘을 통해 프로그램은 특정 HRESULT 오류에 오류를 발생시킨 객체의 클래스, 오류를 발생시킨 객체의 인터페이스, 오류 텍스트, 도움말 파일의 도움말 항목 링크 등 다양한 정보를 연결할 수 있다. 또한, HRESULT 오류를 수신한 측에서는 필요에 따라 오류 메시지에 대한 현지화된 텍스트를 얻을 수 있다.4. 2. 활용
마이크로소프트 비주얼 베이직은 HRESULT와 IErrorInfo 객체를 연결하고 (포인터) IErrorInfo 객체를 스레드 로컬 저장소에 저장함으로써 HRESULT 오류 보고 메커니즘을 실질적으로 향상시켰다. IErrorInfo 메커니즘을 통해 프로그램은 특정 HRESULT 오류에 다양한 정보(오류를 발생시킨 객체의 클래스, 오류를 발생시킨 객체의 인터페이스, 오류 텍스트, 도움말 파일의 도움말 항목 링크 등)를 연결할 수 있다. 또한, HRESULT 오류를 수신한 측에서는 필요에 따라 오류 메시지에 대한 현지화된 텍스트를 얻을 수 있다.이후, HRESULT 및 관련 `IErrorInfo` 메커니즘은 COM에서 기본 오류 보고 메커니즘으로 사용되었다.
Windows에서 IErrorInfo 메커니즘에 대한 지원은 매우 일관성이 없다. 이전 Windows API는 이를 전혀 지원하지 않는 경향이 있으며, `IErrorInfo` 데이터 없이 HRESULT를 반환한다. 더 현대적인 Windows COM 하위 시스템은 IErrorInfo 객체의 메시지 설명에 광범위한 오류 정보를 제공하는 경우가 많다. IErrorInfo 오류 메커니즘의 더 발전된 기능(도움말 링크 및 주문형 현지화)은 거의 사용되지 않는다.
.NET Framework에서는 네이티브 코드에서 관리 코드(managed code)로 전환될 때 HRESULT/IErrorInfo 오류 코드가 CLR 예외로 변환된다. CLR 예외는 관리 코드에서 네이티브 COM 코드로 전환될 때 HRESULT/IErrorInfo 오류 코드로 변환된다.
5. HRESULT 값 사용
HRESULT 값을 사용하여 함수의 성공 또는 실패 여부를 확인하고, 오류 코드를 분석할 수 있다.
`HRESULT_CODE()` 매크로를 사용하여 HRESULT 값에서 오류 코드 부분을 추출할 수 있다.
[http://www.microsoft.com/downloads/details.aspx?FamilyID=be596899-7bb8-4208-b7fc-09e02a13696c&DisplayLang=en ERR.EXE] 도구를 사용하면 HRESULT 값을 해당 메시지 텍스트로 변환할 수 있다.
[http://msdn.microsoft.com/en-us/library/5tbh0w11%28v=vs.71%29.aspx ERRLOOK.EXE] 도구를 사용하면 주어진 HRESULT 값과 관련된 오류 문자열을 표시할 수 있다. 이 도구는 비주얼 스튜디오 명령 프롬프트에서 실행할 수 있다.
win32 `SetErrorInfo` 함수는 HRESULT 값을 해당 `IErrorInfo` 객체와 연결한다. `GetErrorInfo` 함수는 이 정보를 읽는다.
win32 [http://msdn.microsoft.com/en-us/library/ms679351(VS.85).aspx FormatMessage] 함수를 사용하면 일부 비-IErrorInfo HRESULT 값에 대한 사람이 읽을 수 있는 설명을 얻을 수 있다.
`winerror.h` 헤더 파일은 일반적으로 사용되는 일부 HRESULT 값을 정의한다. HRESULT 값은 때때로 하위 시스템의 헤더(.h) 파일에 인코딩된다. 이러한 값은 Microsoft Windows 플랫폼 SDK 또는 DDK의 해당 헤더 파일에도 정의되어 있다.
5. 1. 성공/실패 확인
HRESULT는 부호 있는 정수로 정의되며, 최상위 비트가 심각도 필드이므로 음수 값은 실패, 그 외의 값은 성공을 나타낸다. 가장 일반적으로 사용되는 성공 코드는 `S_OK`이며 값은 0이다. 그러나 드물게 함수는 값 1을 갖는 `S_FALSE`와 같이 추가 정보를 가진 성공 코드를 반환하기도 한다.[5]HRESULT 값이 16진수로 표시될 때 (주로 디버깅을 할 때) 개발자는 8번째 자리 숫자가 8 이상이면 실패를 나타내는 값으로 식별할 수 있다. 8자리로 채워지지 않으면 값이 실패로 잘못 인식될 수 있다. 예를 들어 80005는 8로 시작하지만 성공이다. 8자리로 채우면 00080005가 된다. 이는 일반적으로 성공이 명확하게 성공 코드인 0이기 때문에 다소 인위적이다.
실패 상태를 확인하는 프로그래밍 방식은 음수를 테스트하거나 시스템 정의 매크로를 사용하는 것이다.[5]
```c++
HRESULT hr = func(...);
if (hr < 0) ; // 실패
if (hr >= 0) ; // 성공
if (FAILED(hr)) ; // 실패
if (SUCCEEDED(hr)) ; // 성공
```
`(hr)` 또는 `(!hr)`과 같이 0을 테스트하는 것은 대부분의 경우 작동하지만, `S_OK` 이외의 `S_FALSE`와 같은 드물게 사용되는 성공 코드에는 잘못된 것이다.
HRESULT의 코드 부분을 얻으려면 `HRESULT_CODE()` 매크로를 사용한다.
5. 2. 오류 코드 추출
`HRESULT_CODE()` 매크로를 사용하여 HRESULT 값에서 오류 코드 부분을 추출할 수 있다.[5]6. HRESULT의 기원
HRESULT라는 이름은 다른 많은 윈도우 자료형에서 H를 핸들이라는 뜻으로 사용하기 때문에 "결과 핸들"을 의미하는 것처럼 보인다. 예를 들어, HMODULE은 모듈 핸들로, HMODULE 값은 모듈 리소스를 의미한다. 그러나 HRESULT 값은 리소스를 참조하지 않으므로 핸들이 아니다. 레이몬드 첸은 "옛날에는 리치 오류 정보 개체를 다루는 핸들이었습니다... COM 팀은 비용/편익이 단순히 그만한 가치가 없다고 판단하여 HRESULT는 단순한 숫자로 바뀌었습니다. 하지만 이름은 그대로였습니다."라고 말한다.[7]
7. 도구
HRESULT 값을 해당 메시지 텍스트로 변환하려면 [http://www.microsoft.com/downloads/details.aspx?FamilyID=be596899-7bb8-4208-b7fc-09e02a13696c&DisplayLang=en ERR.EXE] 도구를 사용할 수 있다. 주어진 HRESULT 값과 관련된 오류 문자열을 표시하려면 [http://msdn.microsoft.com/en-us/library/5tbh0w11%28v=vs.71%29.aspx ERRLOOK.EXE] 도구를 사용할 수 있으며, 비주얼 스튜디오 명령 프롬프트에서 실행할 수 있다. 일부 비-IErrorInfo HRESULT 값에 대한 사람이 읽을 수 있는 설명을 얻으려면 win32 [http://msdn.microsoft.com/en-us/library/ms679351(VS.85).aspx FormatMessage]를 사용할 수 있다.
참조
[1]
웹사이트
Windows Data Types (BaseTsd.h) - Win32 apps
https://docs.microso[...]
2022-07-10
[2]
웹사이트
'[MS-ERREF]: HRESULT'
https://docs.microso[...]
2022-07-10
[3]
웹사이트
'[MS-ERREF]: Win32 Error Codes'
https://docs.microso[...]
2022-07-10
[4]
웹사이트
Structure of COM Error Codes - Win32 apps
https://docs.microso[...]
2022-07-11
[5]
웹사이트
Using Macros for Error Handling - Win32 apps
https://docs.microso[...]
2022-07-10
[6]
웹사이트
Why does HRESULT begin with H when it's not a handle to anything?
https://devblogs.mic[...]
2018-01-17
[7]
웹인용
Why does HRESULT begin with H when it's not a handle to anything?
https://devblogs.mic[...]
2022-07-11
본 사이트는 AI가 위키백과와 뉴스 기사,정부 간행물,학술 논문등을 바탕으로 정보를 가공하여 제공하는 백과사전형 서비스입니다.
모든 문서는 AI에 의해 자동 생성되며, CC BY-SA 4.0 라이선스에 따라 이용할 수 있습니다.
하지만, 위키백과나 뉴스 기사 자체에 오류, 부정확한 정보, 또는 가짜 뉴스가 포함될 수 있으며, AI는 이러한 내용을 완벽하게 걸러내지 못할 수 있습니다.
따라서 제공되는 정보에 일부 오류나 편향이 있을 수 있으므로, 중요한 정보는 반드시 다른 출처를 통해 교차 검증하시기 바랍니다.
문의하기 : help@durumis.com